Start and verify a worker

A Boundary worker starts with the boundary server command, and you can run it in the foreground, as a systemd service, or in a container. After it starts, the worker connects to its upstream and reports status to a controller, which you confirm with the boundary workers list command.

Requirements

Before you start a worker, you must have:

A worker configuration file. Refer to Create the worker configuration.
Network access from the worker to its upstream on port 9201.
Write access to the auth_storage_path directory, if you use the controller-led or worker-led registration method.
A host that meets the worker hardware requirements. Refer to System requirements.

Start the worker

Select the method that matches how you deploy the Boundary worker:

Run the worker in the foreground to confirm that the configuration is valid. This method is useful when you first bring a worker online, because Boundary streams events to the terminal.

Pass the full path to the worker configuration file:

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

Boundary prints a startup summary, then streams events:

==> 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: GzusqckarbczHoLGQ4UA25uSQhnZ1cxNFiDqWNng6k4gsK2NZCwET4nFBF8jMGMDEj1quqY7T6kFtWH1BJBs
          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:

The summary confirms the values Boundary read from the configuration file. Check that the Listener 1 address and the Worker Public Proxy Addr values match what you expect.

HashiCorp recommends that you run Boundary as a non-root user, and that you manage the Boundary process under systemd with that user.

Complete the following steps to run a worker as a systemd service:

Add the boundary system user and group, and give the user ownership of the configuration file and binary:
```
$ sudo adduser --system --group boundary || true ;
$ sudo chown boundary:boundary /etc/boundary.d/egress-worker.hcl ;
$ sudo chown boundary:boundary /usr/local/bin/boundary
```
If you configure the worker for session recording, the boundary user also requires access to the recording_storage_path directory.

Create a unit file at /etc/systemd/system/boundary-worker.service. Update the path on the ExecStart line to match the location of your worker configuration file:

/etc/systemd/system/boundary-worker.service

[Unit]
Description="HashiCorp Boundary worker"
Documentation=https://developer.hashicorp.com/boundary/docs
StartLimitIntervalSec=60
StartLimitBurst=3

[Service]
EnvironmentFile=-/etc/boundary.d/boundary.env
User=boundary
Group=boundary
ProtectSystem=full
ProtectHome=read-only
ExecStart=/usr/bin/boundary server -config=/etc/boundary.d/egress-worker.hcl
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
LimitMEMLOCK=infinity

[Install]
WantedBy=multi-user.target

The ExecReload directive sends SIGHUP to the worker, which reloads the initial_upstreams, tags, and ssh_known_hosts_path values without restarting the process. The KillSignal directive sends SIGINT, which starts a graceful shutdown so that the worker drains any active sessions.

Set the permissions on the unit file:

$ sudo chmod 664 /etc/systemd/system/boundary-worker.service

Reload the systemd daemon, then enable and start the service:

$ sudo systemctl daemon-reload ;
$ sudo systemctl enable boundary-worker ;
$ sudo systemctl start boundary-worker

Confirm that the service is running:

$ sudo systemctl status boundary-worker

If you use the worker-led registration method, the worker writes its registration request to the auth_request_token file in the auth_storage_path directory. You can also find the value in the service logs:

$ sudo journalctl -u boundary-worker | grep "Worker Auth Registration Request"

Run the worker in a container by mounting a volume for the worker's storage, mounting the configuration file, and passing the configuration path to the server command.

The container image runs Boundary as the boundary user. Its entry point adds the boundary command in front of the arguments you pass, so you pass server rather than boundary server.

The following example runs a worker using the Boundary Enterprise image:

$ docker run \
  --name boundary-worker \
  --detach \
  -p 9202:9202 \
  -v boundary-worker-data:/boundary \
  -v /etc/boundary.d/egress-worker.hcl:/boundary/worker.hcl:ro \
  -e BOUNDARY_LICENSE=file:///boundary/license.hclic \
  hashicorp/boundary-enterprise:latest \
  server -config=/boundary/worker.hcl

Set auth_storage_path to /boundary in the worker configuration file so that the worker writes its credentials to the mounted volume.

Warning

Mount the volume at /boundary rather than at a directory beneath it. The boundary user owns the /boundary directory in the image, so a volume that you mount at that path inherits the correct ownership. A volume that you mount at a nested path such as /boundary/data belongs to root. The worker then fails to start with a permission denied error when it tries to create the nodecreds directory.

Mount the storage directory on a volume that persists across container restarts. If you do not, the worker generates new credentials each time it starts, and you have to register it again.

Set public_addr in the configuration file to an address that clients and downstream workers can reach. Other hosts cannot reach the container's internal address.

To run workers on Kubernetes, use the Boundary worker Helm chart instead of running the container directly. Refer to Deploy workers using a Helm chart.

This page describes how to start an individual worker. To deploy a full self-managed environment, refer to Deploy workers. To deploy workers on Kubernetes, refer to the Boundary Helm charts.

Register the worker

A worker cannot proxy sessions until it registers with a controller. If you have not registered this worker, refer to Register workers and complete the registration method you chose.

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

Verify the worker

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.

Verify a multi-hop chain

In a multi-hop deployment, the Directly Connected Downstream Workers field shows which workers connect through each worker. Use this field to confirm the shape of the chain.

Read the worker at the top of the chain:

$ boundary workers read -id w_UJ3Qq63Jx0

The output lists the worker directly below it:

Worker information:
  Address:                   10.0.0.10:9202
  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

  Directly Connected Downstream Workers:
    w_GHBqIeHMyR

Repeat this command for each worker in the chain. The worker at the end of the chain has no downstream workers.

Confirm the proxy listener

From a host that reaches the worker, confirm that the worker accepts connections on its proxy port:

$ nc -vz 10.0.0.10 9202

If the connection fails, check that the listener stanza binds an address the client can reach, and that your firewall rules allow inbound traffic on the proxy port.

Next steps

If you have not registered the worker yet, register it with a controller. A worker cannot proxy sessions until it registers.

After you register and verify the worker, you can:

Add worker tags to control which sessions the worker proxies.
Manage workers to update, reload, or decommission the worker.
Configure multi-hop sessions to chain workers across networks.

If the worker does not report status, refer to Troubleshoot workers.