One control plane, explicit dependencies.
Switchyard is configured through environment variables. The important part is not memorising names — it is understanding which boundary each value configures: Trestle coordination, Cloudflare Artifacts Git hosting, local execution, or control-plane operation.
Core configuration
| Variable | Required? | Purpose |
|---|---|---|
SWITCHYARD_TRESTLE_URL | Yes | Trestle base URL (commonly http://127.0.0.1:7350). |
SWITCHYARD_TRESTLE_USER / SWITCHYARD_TRESTLE_PASS | Yes | Trusted control-plane credentials used to provision/read/write coordination records. |
SWITCHYARD_ARTIFACTS_ACCOUNT | Yes | Cloudflare account id that owns the Artifacts namespace. |
SWITCHYARD_ARTIFACTS_NAMESPACE | Yes | Artifacts namespace containing the authoritative Git repositories. |
SWITCHYARD_ARTIFACTS_TOKEN_CMD | Yes | Command used to obtain a fresh account credential; repo-scoped Git tokens are minted from it as needed. |
SWITCHYARD_STATIC_DIR | Yes | Nift-built web application directory served by the control plane. |
SWITCHYARD_LISTEN | No | Listen address; keep this on localhost when a reverse proxy is in front (default 127.0.0.1:8080). |
SWITCHYARD_DATA_DIR | Yes | Local operational state such as scratch Git work and the fallback credential-encryption key. |
SWITCHYARD_STRUT_BIN | Unused | Accepted for compatibility; the deterministic adapter is now an in-process Go function, so no worker binary is required. |
Background workers
| Variable | Typical value | Effect |
|---|---|---|
SWITCHYARD_RECONCILE_INTERVAL | 15s | How often Artifacts refs are reconciled against durable coordination state. This is the correctness safety net. |
SWITCHYARD_QUEUE_ID | Queue id | Enables the Cloudflare Queue event fast path. Optional because reconciliation still guarantees eventual convergence. |
SWITCHYARD_QUEUE_PULL_INTERVAL | 5s | How often the event consumer pulls the Cloudflare Queue. |
SWITCHYARD_WORKFLOW_INTERVAL | 2s | Polling cadence for durable workflow runs ready to advance. |
SWITCHYARD_QUEUE_INTEGRATE_INTERVAL | 3s | Polling cadence for the canonical Integration Queue worker. |
Credential encryption
SWITCHYARD_SECRET_KEY may provide the 32-byte key used for provider credential encryption. If it is absent, Switchyard persists a local fallback key under the data directory. That fallback is convenient for self-hosting, but its threat model is deliberately limited: encrypted Trestle records plus a key on the same compromised host do not protect against full-host compromise.
Example development environment
export SWITCHYARD_TRESTLE_URL=http://127.0.0.1:7350
export SWITCHYARD_TRESTLE_USER=admin
export SWITCHYARD_TRESTLE_PASS=CHANGE_ME
export SWITCHYARD_ARTIFACTS_ACCOUNT=YOUR_ACCOUNT_ID
export SWITCHYARD_ARTIFACTS_NAMESPACE=switchyard-dev
export SWITCHYARD_ARTIFACTS_TOKEN_CMD=/opt/switchyard/token.sh
export SWITCHYARD_STATIC_DIR=/opt/switchyard/public
export SWITCHYARD_LISTEN=127.0.0.1:8080
export SWITCHYARD_DATA_DIR=/opt/switchyard/data
# SWITCHYARD_STRUT_BIN is no longer required (in-process deterministic adapter).
export SWITCHYARD_RECONCILE_INTERVAL=15s
export SWITCHYARD_QUEUE_ID=YOUR_QUEUE_ID # optional fast path
export SWITCHYARD_QUEUE_PULL_INTERVAL=5s
export SWITCHYARD_WORKFLOW_INTERVAL=2s
export SWITCHYARD_QUEUE_INTEGRATE_INTERVAL=3s
Production topology
Internet
│
Caddy / reverse proxy (:443)
│
Switchyard (127.0.0.1:8080)
├── Trestle (localhost/private)
└── Cloudflare Artifacts + Queue (outbound HTTPS)
Keep Trestle and the raw Switchyard listen socket private. Public exposure should terminate TLS at the reverse proxy and forward only the application/control-plane HTTP surface.