Register a worker using the controller-led method

출처: HashiCorp Boundary docs In the controller-led method, you generate an activation token on the controller before you start the worker. You provide that token to the worker in its configuration file, and the worker presents it to the controller for authorization when it starts. Use this method when you provision workers using a configuration management tool or an instance template, because you can inject the activation token when you render the configuration file.

Requirements

Before you register a worker using the controller-led method, you must have:

A worker configuration file with an auth_storage_path value. Refer to Create the worker configuration.
Network access from the worker to its upstream controller or worker on port 9201.
Permission to perform the create:controller-led action on workers in the global scope.

Generate an activation token

Complete the following steps to generate an activation token:

Log in to Boundary as a user with permission to create workers.
Use the following command to create the worker resource and generate an activation token:$ boundary workers create controller-led Boundary returns the worker resource and the activation token:Worker information: Active Connection Count: 0 Controller-Generated Activation Token: neslat_2KrShA8kh6VUbJBYa4ZXUe7yRpPs2xKNYst2wqyvadQ6ooSZ4XQTfifKG4tNp2vhaAVeBSvHofWDNzbUYUyK2C8ypbYnx Created Time: Fri, 07 Aug 2026 13:45:37 MDT ID: w_6GkcuYV2mn Local Storage State: unknown Type: pki Updated Time: Fri, 07 Aug 2026 13:45:37 MDT Version: 1

Scope: ID: global Name: global Type: global

Authorized Actions: no-op read update delete add-worker-tags set-worker-tags remove-worker-tags 3. Copy the Controller-Generated Activation Token value.The token begins with the neslat_ prefix. It is valid for one worker only. Boundary creates the worker resource immediately, before the worker starts. The worker appears in the worker list with no address until it starts and reports status.

Add the token to the worker configuration

Add the activation token to the worker stanza using the controller_generated_activation_token parameter: /etc/boundary.d/egress-worker.hcl

worker
 {

  public_addr       
=
 "10.0.0.10:9202"

  initial_upstreams 
=
 [
"10.0.0.1:9201"
]

  auth_storage_path 
=
 "/var/lib/boundary"

  controller_generated_activation_token 
=
 "neslat_2KrShA8kh6VUbJBYa4ZXUe7yRpPs2xKNYst2wqyvadQ6ooSZ4XQTfifKG4tNp2vhaAVeBSvHofWDNzbUYUyK2C8ypbYnx"

}

To avoid writing the token into the configuration file, you can read it from an environment variable or a file:

worker
 {

  # Read the token from an environment variable

  controller_generated_activation_token 
=
 "env://ACT_TOKEN"

  # Or read the token from a file

  # controller_generated_activation_token = "file:///tmp/worker_act_token"

}

You cannot set the name and description fields in the configuration file for workers that use the controller-led method. Among the registration methods, external KMS supports those fields in the configuration file. To label a controller-led worker, use the boundary workers update command after you register it. Refer to Update the name and description. Note The activation token is single use. After the worker authorizes successfully, the token is unusable, so it is safe to leave it in the configuration file.

Start the worker

Start the worker to complete the registration:

$
 boundary server -config=/etc/boundary.d/egress-worker.hcl

The worker reads the activation token and authorizes itself to the cluster. Unlike the worker-led method, a controller-led worker does not write an auth_request_token file to its auth_storage_path directory. If the activation token is missing when the worker starts, and the worker is not yet authorized, the worker prints a registration request for the worker-led method instead. If you have not used the worker-led flow to authorize the worker, you can add the activation token and restart the worker to use it.

Verify the registration

Use the following command to list the workers that are registered with the controller:

$
 boundary workers list

Boundary returns each registered worker, its address, and its release version:

Worker information:

  ID:                        w_UJ3Qq63Jx0

    Version:                 1

    Address:                 10.0.0.10:9202

    ReleaseVersion:          Boundary v1.0.0+ent

    Last Status Time:        Fri, 07 Aug 2026 19:45:12 UTC

    Authorized Actions:

      no-op

      read

      update

      delete

      add-worker-tags

      set-worker-tags

      remove-worker-tags

A recent Last Status Time value indicates that the worker is connected to its upstream and reporting status. Use the following command to view the details for a specific worker:

$
 boundary workers read -id w_UJ3Qq63Jx0

Boundary returns the worker's configuration tags, storage state, and connected downstream workers:

Worker information:

  Active Connection Count:   0

  Address:                   10.0.0.10:9202

  Created Time:              Fri, 07 Aug 2026 13:44:30 MDT

  ID:                        w_UJ3Qq63Jx0

  Last Status Time:          2026-08-07 19:45:22.616245 +0000 UTC

  Local Storage State:       not configured

  Release Version:           Boundary v1.0.0+ent

  Type:                      pki

  Updated Time:              Fri, 07 Aug 2026 13:45:22 MDT

  Version:                   1

  Scope:

    ID:                      global

    Name:                    global

    Type:                    global

  Tags:

    Configuration:

      type: ["worker1" "ingress"]

    Canonical:

      type: ["worker1" "ingress"]

  Authorized Actions:

    no-op

    read

    update

    delete

    add-worker-tags

    set-worker-tags

    remove-worker-tags

The output includes the following fields that indicate worker health:

Last Status Time - The time the worker last reported status to a controller.
Local Storage State - The state of the worker's local storage. The value is not configured unless you configure the worker for session recording.
Release Version - The Boundary version the worker runs.
Tags - The Configuration tags come from the worker configuration file. The Canonical tags include both configuration tags and any API tags you add.

Next steps

After you register the worker, you can:

Add worker tags to control which sessions the worker proxies.
Configure a worker filter on a target, credential store, or storage bucket.
Configure multi-hop sessions to chain workers across networks. If the worker does not report status, refer to Troubleshoot workers.