Register a worker using the worker-led method

출처: HashiCorp Boundary docs 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 IDWorker public addressConfig file pathWorker TagsLocal 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. 3. 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) 4. Register the worker using the worker-led method:$ 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.