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: model_method
          modelIdOrName: builder
          methodName: run
      - name: test
        task:
          type: model_method
          modelIdOrName: 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:

curl https://swamp.example.com/
{
  "name": "swamp-serve",
  "version": "...",
  "instanceId": "a1b2c3d4",
  "remoteOnly": true
}

The remoteOnly field also appears in the health endpoint response.

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.

← PreviousMonitor Server HealthNext →Set Up Extension Trust