Bridge configuration

Configure the Bridge with environment variables or ~/.ctrlnode/.env. The runtime reads config at startup; installers (install.ps1 / install.sh) create the initial file.

Interactive setup belongs in install scripts, not in the Bridge binary. After install, edit ~/.ctrlnode/.env or your shell profile.

Where settings live

.env search order (first existing file wins; keys already in the process environment are not overwritten from file, except installer overrides — see below):

{BASE_PATH}/.ctrlnode/.env (recommended — written by installers)
./.env (current working directory)
~/.env (home directory)

For keys PAIRING_TOKEN, SAAS_URL, and BASE_PATH, values in ~/.ctrlnode/.env from the installer override stale shell exports so a random PAIRING_TOKEN=test in your profile does not break production pairing. Example:

PAIRING_TOKEN=your_token_from_bridge_setup
SAAS_URL=wss://api.ctrlnode.ai/ws/bridge
BASE_PATH=C:\Users\you

On disk, Bridge data lives under:

{BASE_PATH}/.ctrlnode/
  tasks/              # per-task output folders (OUTPUT ONLY mode)
  agents/             # Hermes only: optional AGENTS.md + .meta.json
  .hermes-sessions/   # Hermes CLI conversation resume
  .codex-agents/      # Codex per-agent CODEX_HOME

Core connection

Variable	Required	Default	Description
`PAIRING_TOKEN`	Yes	—	Token from Bridge Setup in the app
`SAAS_URL`	No	`wss://api.ctrlnode.ai/ws/bridge`	Control plane WebSocket URL

Workspace: `BASE_PATH` (replaces `AGENTS_FOLDER`)

Variable	Required	Default	Description
`BASE_PATH`	No	User home directory	Parent directory for `{BASE_PATH}/.ctrlnode`

Installers set BASE_PATH (not AGENTS_FOLDER). This is the “workspace parent” you choose at install time — where task folders and Bridge metadata are stored.

AGENTS_FOLDER is legacy. Do not document or set it for new installs. Use BASE_PATH only.

Project work directory is separate: it is configured per project in the web app (repositoryPaths), not via a Bridge env var. See Tasks — work modes.

Providers: no `PROVIDERS` env var

The Bridge always loads all built-in providers:

openclaw, claude, claude-sdk, copilot, gemini, codex, cursor, hermes

Variable	Effect today
`PROVIDERS`	Ignored (kept only for backwards compatibility)
`PROVIDER`	Ignored

Routing is driven by CtrlNode: on connect the server sends sync_{provider}_agents for each CLI type. The Bridge maps each agent id → provider. Install only the CLIs you use; missing tools fail tasks with clear errors instead of silent mis-routing.

If openclaw.json is missing, OpenClaw is skipped at runtime with a warning — other providers still work.

Per-provider setup: Providers.

OpenClaw paths

Variable	Default	Description
`OPENCLAW_GATEWAY_URL`	`http://localhost:18789`	Gateway HTTP base
`OPENCLAW_GATEWAY_TOKEN`	—	Bearer token for `/tools/invoke`
`OPENCLAW_HOME` / `OPENCLAW_CONFIG_PATH` / `OPENCLAW_STATE_DIR`	resolved	See OpenClaw provider page

Provider credentials (summary)

Provider id	Primary setup
`openclaw`	`OPENCLAW_GATEWAY_TOKEN`, gateway URL
`claude`	Claude Code CLI login
`claude-sdk`	`ANTHROPIC_API_KEY` or subscription / `claude login`
`copilot`	`copilot login` or `COPILOT_GITHUB_TOKEN`
`gemini`	`GEMINI_API_KEY` / `GOOGLE_API_KEY` or `gemini auth login`
`codex`	`CODEX_API_KEY` or `codex auth login`; optional `CODEX_BIN_PATH`
`cursor`	`CURSOR_API_KEY` (required)
`hermes`	`pip install "hermes-agent[acp]"`, `hermes` on PATH; optional `HERMES_USE_ACP=false` for CLI-only

Hermes-specific

Variable	Default	Description
`HERMES_HOME`	—	Emergency global override only; normally each agent uses `~/.hermes/profiles/{agentId}/`
`HERMES_TIMEOUT_MINUTES`	`15`	Task timeout
`HERMES_USE_ACP`	ACP on	Set `false` or `0` to force `hermes chat` CLI instead of `hermes acp`

See Hermes provider.

Timers and watcher

Variable	Default
`HEARTBEAT_MS`	`30000`
`RECONNECT_MS`	`5000`
`CONNECTION_TIMEOUT_MS`	`10000`
`POLL_CONFIG_MS`	`60000`
`AGENT_IDLE_RESET_MS`	`15000`
`SESSION_HISTORY_POLL_MS`	`5000`
`SESSION_INACTIVITY_TIMEOUT_MINUTES`	`5`
`WATCHER_USE_POLLING`	`false`
`WATCHER_POLL_INTERVAL`	`1000`

Per-provider *_TIMEOUT_MINUTES default to 10 (Hermes 15).

Debugging

Variable	Description
`BRIDGE_INCOMING_DUMP_PATH`	Optional directory to dump raw inbound WebSocket payloads

Run ctrlnode in a terminal and watch stderr for handshake_sent, sync_*_agents, and provider warnings.

Troubleshooting

Bridge disconnected

Confirm ctrlnode is running, PAIRING_TOKEN in ~/.ctrlnode/.env is current, and shell PAIRING_TOKEN is unset.

Wrong provider ran the task

Match the agent’s agent type in Team to the installed CLI. Do not set PROVIDERS — it has no effect. Reconnect Bridge after creating agents.

Tasks write outside the repo in WORK DIRECTORY mode

Ensure the project has a Project work directory configured and the task mode is WORK DIRECTORY. See Task work modes.

​Where settings live

​Core connection

​Workspace: BASE_PATH (replaces AGENTS_FOLDER)

​Providers: no PROVIDERS env var

​OpenClaw paths

​Provider credentials (summary)

​Hermes-specific

​Timers and watcher

​Debugging

​Troubleshooting

​Related

Where settings live

Core connection

Workspace: `BASE_PATH` (replaces `AGENTS_FOLDER`)

Providers: no `PROVIDERS` env var

OpenClaw paths

Provider credentials (summary)

Hermes-specific

Timers and watcher

Debugging

Troubleshooting

Related