Bridge configuration

BASE_PATH, .env precedence, all providers loaded, Hermes env vars, and timeouts

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):

1. {BASE_PATH}/.ctrlnode/.env (recommended — written by installers)
2. ./.env (current working directory)
3. ~/.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.

Related

• Install
• Providers
• Overview