REMOTE EXECUTION

In this tutorial, we will mint an enrollment token, start the Swamp orchestrator, connect a worker, and run a workflow step on that worker. By the end you will have a local orchestrator dispatching work to a separate worker process.

What we will build

We will create a behavior that echoes a message, place it on a worker using the target: field in a workflow step, and watch the orchestrator route the execution to the connected worker.

Before we start

This tutorial assumes:

• Swamp is installed. If not, run curl -fsSL https://swamp-club.com/install.sh | sh.
• You have a Swamp repository. The Your First Automation tutorial covers installation and repo setup. If you already have a repo, use that.
• You have signed in with swamp auth login. Every Swamp command needs a swamp-club.com account.

Create an enrollment token

Workers authenticate with the orchestrator using enrollment tokens. Tokens are one-time secrets that Swamp stores in its own _token-secrets vault, so you do not need to create a vault first. Open a terminal in your Swamp repo and create one:

$ swamp worker token create build-node --duration 1h

You should see output like:

Token: build-node
Expires: 2026-10-14T05:05:53.900Z
Vault: _token-secrets (key worker-token-build-node)

  build-node.2d3b910665c9d667e651d217dc692205997297ba80aa4c3e9fffae2ec1585949

This token is shown once and will not be displayed again — store it now.

Copy the full token string (the line starting with build-node.). You will need it when connecting the worker.

Confirm the token exists:

$ swamp worker token list

You should see:

NAME        STATE   EXPIRES                   ENROLLMENTS
build-node  unused  2026-10-14T05:05:53.900Z  -

Notice the unused state and the empty ENROLLMENTS column. The token has not been claimed by a worker yet.

Start the orchestrator

The orchestrator listens for worker connections and dispatches placed steps. In the same terminal, start it:

$ swamp serve

Leave this terminal running. The orchestrator will log connections and step dispatches as they happen.

Connect a worker

Open a second terminal, navigate to the same Swamp repo, and connect a worker using the token you copied earlier:

$ swamp worker connect ws://localhost:9090 --token <token> --cache-dir /tmp/swamp-worker

Replace <token> with the full token string from the creation step.

The --cache-dir flag tells the worker where to store its identity and cached data. Without it, the worker gets a fresh identity each time it starts, which means the orchestrator treats it as a new machine on every restart. Pointing --cache-dir at a stable path lets the worker reconnect with the same identity across restarts.

If the connection succeeds, the worker logs that it has enrolled and is waiting for work. Back in the orchestrator terminal, you should see a log line indicating the worker connected. If you run swamp worker token list again, the token state changes to enrolled and the ENROLLMENTS column shows the worker's machine identifier.

Create a behavior

We need a simple behavior for the worker to execute. Create a command/shell behavior that echoes a message. Ask Claude Code:

Create a command/shell behavior called remote-echo that echoes "executed on a worker"

Verify the behavior works locally before placing it on the worker:

$ swamp behavior run remote-echo execute

You should see executed on a worker in the output. The behavior works. Now we will route it through the orchestrator to the connected worker.

Create a workflow with a placed step

Create a workflow that targets the worker. Ask Claude Code:

Create a workflow called remote-demo with one job called build.
The job has one step called echo-on-worker that runs the
remote-echo behavior's execute method. The step should have a
target field set to "build-node" so it runs on the worker.

The resulting workflow YAML should look like this:

id: <generated-uuid>
name: remote-demo
description: Run a step on a remote worker
jobs:
  - name: build
    steps:
      - name: echo-on-worker
        target: build-node
        task:
          type: behavior
          behavior: remote-echo
          methodName: execute
version: 1

Notice the target: build-node field on the step. This tells the orchestrator to dispatch this step to a worker whose enrollment token name matches build-node. Without target, the step would run locally.

Run the workflow

With the orchestrator and worker still running in their terminals, open a third terminal and run the workflow:

$ swamp workflow run remote-demo --server ws://localhost:9090

Watch the three terminals:

1. Orchestrator — logs that it received the workflow run, matched the echo-on-worker step to the build-node worker, and dispatched it.
2. Worker — logs that it received the step, executed the remote-echo behavior, and returned the result.
3. Workflow runner — shows the step completing successfully, with output like:

     Remote   ws://localhost:9090
 system │ Starting workflow remote-demo · 04:06:14 UTC

  build │ start 04:06:14 UTC
  build │ step echo-on-worker · remote-echo · execute · start 04:06:14 UTC
  build │ executed on a worker
  build │ done echo-on-worker in 581ms · 04:06:15 UTC
  build │ completed in 585ms · 04:06:15 UTC

 system │ Completed workflow remote-demo succeeded in 590ms · 04:06:15 UTC

    ┌────────────────────────┐
    │ Data produced          │
    │  result    from build  │
    │                        │
    └────────────────────────┘

The step ran on the worker, not locally. The orchestrator routed it based on the target field, the worker executed it, and the result flowed back through the orchestrator to the workflow runner.

To see the full workflow report, run:

$ swamp report get @swamp/workflow-summary --workflow remote-demo

Verify the stored data

Confirm the data was saved as usual:

$ swamp data query \
    'behaviorName == "remote-echo" && specName == "result"' \
    --select 'attributes.stdout'

You should see:

executed on a worker

Data produced by remote workers is stored in the same .swamp/data/ directory as locally executed steps. The workflow runner handles the transfer transparently.

Clean up

Stop the worker with Ctrl-C in its terminal, then stop the orchestrator with Ctrl-C in its terminal.

You have minted an enrollment token, started an orchestrator, connected a worker, placed a workflow step on that worker using target:, and observed the end-to-end execution. To understand how the orchestrator routes steps and how workers negotiate trust, see Remote Execution. For the full list of swamp worker and swamp serve flags, see the Worker Commands reference. For authentication, access control, and operating a production server, see the swamp serve how-to guides.