Skip to main content

SET UP A REMOTE-ONLY ORCHESTRATOR

This guide sets up a swamp serve instance that acts purely as an orchestrator. Local execution is disabled — every workflow step must declare placement and be dispatched to a remote worker.

Prerequisites

Enable remote-only mode

CLI flag

swamp serve --remote-only --auth-mode token --host 0.0.0.0 \
  --cert-file cert.pem --key-file key.pem

Config file

Add remote-only: true to .swamp/serve.yaml:

# .swamp/serve.yaml
remote-only: true
host: "0.0.0.0"

auth:
  mode: token

tls:
  cert-file: /etc/certs/server.crt
  key-file: /etc/certs/server.key

Environment variable

SWAMP_REMOTE_ONLY=true swamp serve

System daemon

swamp serve daemon enable --remote-only --auth-mode token \
  --cert-file cert.pem --key-file key.pem

Add placement to your workflows

Every step must declare target, labels, or platform — directly or through inheritance from a job or workflow. The most common pattern is setting placement at the workflow level so all steps inherit it:

name: build-pipeline
labels:
  pool: workers

jobs:
  - name: build
    steps:
      - name: compile
        task:
          type: behavior
          behavior: builder
          methodName: run
      - name: test
        task:
          type: behavior
          behavior: tester
          methodName: run

Both steps inherit labels: {pool: workers} from the workflow and are dispatched to matching workers.

See Workflow Placement for the full inheritance model and placement field reference.

Verify the configuration

Check that the server reports remote-only mode on the health endpoint, with a server token (see Monitor Server Health to mint one):

curl https://swamp.example.com/api/v1/health \
  -H "Authorization: Bearer health-monitor.secret"

The response includes:

{
  "remoteOnly": true
}

Fix placement errors

If a workflow step lacks placement, the run fails immediately with:

Step '<name>' has no placement but the server is running in remote-only mode.
Add a placement block (target, labels, or platform) to the workflow step, job,
or workflow so it can be dispatched to a remote worker.

Add a target, labels, or platform field to the step, job, or workflow to fix it. Use swamp workflow validate to catch missing placement before running.