Register a worker using the controller-led method
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_pathvalue. 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-ledaction on workers in theglobalscope.
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-ledBoundary 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-tagsCopy the
Controller-Generated Activation Tokenvalue.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.
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 isnot configuredunless you configure the worker for session recording.Release Version- The Boundary version the worker runs.Tags- TheConfigurationtags come from the worker configuration file. TheCanonicaltags 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.