Register a worker using the worker-led method

In the worker-led method, the worker generates a registration request when it starts. You submit that request to a controller to authorize the worker.

Use this method when an operator brings a worker online manually, or when the system that provisions the worker cannot reach the Boundary API.

Requirements

Before you register a worker using the worker-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:worker-led action on workers in the global scope.

You do not need to add any registration parameters to the worker configuration file.

You cannot set the name and description fields in the configuration file for workers that use the worker-led method. Among the registration methods, external KMS supports those fields in the configuration file. To label a worker-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 generate the registration request:

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

Boundary prints the registration request in the startup output:

==> Boundary server configuration:

                               Cgo: disabled
                        Listener 1: tcp (addr: "0.0.0.0:9202", max_request_duration: "1m30s", purpose: "proxy")
                         Log Level: info
                             Mlock: supported: true, enabled: false
                           Version: Boundary v1.0.0+ent
        Worker Auth Current Key Id: provable-jumbo-copy-annually-naming-skydiver-handwoven-dyslexic
  Worker Auth Registration Request: GzusqckarbczHoLGQ4UA25uSQhnZ1cxNFiDqWNng6k4gsK2NZCwET4nFBF8jMGMDEj1quqY7T6kFtWH1BJBsntxejcWw9QYibFKeXTVyx7NDmooVMbAm9RJwkzBnfgvMNdjvyR8Zdd3NXM66QqFnWosp3QR5ySg5jqMhG8EeAPzELRNmkcoSATrjAqgJe82hf8qiudcpJuBQmGtfpE4aCeChBDYUEjp1NphLXoCzAeqhtuy8oqZx8pBdvBWpVpHLQ89fauPfCqecoMP2uzH5hbNvjhLfza1JPodGSoYDdQ
          Worker Auth Storage Path: /var/lib/boundary
          Worker Public Proxy Addr: 10.0.0.10:9202

==> Boundary server started! Log data will stream in below:

Boundary writes the same value to the auth_request_token file in the auth_storage_path directory:

$ cat /var/lib/boundary/auth_request_token

Until you register the worker, it logs that it is not authenticated to an upstream. You can ignore these messages until you complete the registration.

Register the worker

Complete the following steps to register the worker using the Admin UI:

Log in to Boundary as the admin user.
Select Workers in the navigation pane.
Click New.
(Optional) You can use the New PKI Worker page to construct the contents of the worker configuration file, if you did not create the configuration file already. Provide the following details, and Boundary constructs the worker configuration file for you:
- Boundary Cluster ID
- Worker public address
- Config file path
- Worker Tags
- Local Session Recording Storage
Under Confirm the worker when they connect, paste the Worker Auth Registration Request key. Boundary prints the Worker Auth Registration Request key in the CLI output when you start the worker. You can also read the value from the auth_request_token file in the worker's auth_storage_path directory.
Click Register Worker. Boundary marks the registration request as Registered.
Click Done.
Boundary returns you to the Workers page, where the new worker appears in the list.

Complete the following steps to register the worker using the CLI:

Set the BOUNDARY_ADDR environment variable to the address of your Boundary cluster:
```
$ export BOUNDARY_ADDR="https://boundary.example.com:9200"
```

Log in to the CLI as the admin user. Provide the auth method ID and admin login name, and enter the password when Boundary prompts you for it:

$ boundary authenticate password \
  -auth-method-id=ampw_nihdQAQjRN \
  -login-name=admin

Boundary returns the authentication information and stores the token in your keyring:

Authentication information:
  Account ID:      acctpw_mGfnmjtath
  Auth Method ID:  ampw_nihdQAQjRN
  Expiration Time: Fri, 14 Aug 2026 13:44:25 MDT
  User ID:         u_GENi0SquNe

The token name "default" was successfully stored in the chosen keyring and is not displayed here.

Export the Worker Auth Registration Request value as an environment variable. Boundary prints this value when you start the worker, and also writes it to the auth_request_token file in the worker's auth_storage_path directory:
```
$ export WORKER_TOKEN=$(cat /var/lib/boundary/auth_request_token)
```

$ boundary workers create worker-led -worker-generated-auth-token=$WORKER_TOKEN

Boundary returns the new worker resource:

Worker information:
  Active Connection Count:   0
  Created Time:              Fri, 07 Aug 2026 13:44:30 MDT
  ID:                        w_UJ3Qq63Jx0
  Local Storage State:       unknown
  Type:                      pki
  Updated Time:              Fri, 07 Aug 2026 13:44:30 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

The Local Storage State value is unknown until the worker reports its first status to the controller.

After the worker registers, Boundary deletes the auth_request_token file from the worker's auth_storage_path directory. The activation token is single use, so you cannot register the same worker twice with the same token.

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 appear in the worker list, refer to Troubleshoot workers.