Configure the Bridge with environment variables or aDocumentation Index
Fetch the complete documentation index at: https://docs.ctrlnode.ai/llms.txt
Use this file to discover all available pages before exploring further.
.env file. The open-source runtime reads configuration at startup — it does not prompt for secrets on every launch once ~/.ctrlnode/.env exists.
Install scripts (
install.ps1 / install.sh) run the interactive setup and write ~/.ctrlnode/.env for you. Use this page as the reference when editing that file by hand.Where settings live
Search order for.env (first existing file is loaded; keys already in the process environment are never overwritten from file):
./.env(current working directory){AGENTS_FOLDER}/.ctrlnode/.env~/.env
PAIRING_TOKEN=test in PowerShell/bash, that value overrides the token in ~/.ctrlnode/.env — a common cause of auth failures.
Recommended persistent location:
Core connection
| Variable | Required | Default | Description |
|---|---|---|---|
PAIRING_TOKEN | Yes | — | Token from CtrlNode Bridge Setup (app → project → Bridge Tokens) |
SAAS_URL | No | wss://api.ctrlnode.ai/ws/bridge | WebSocket URL for the control plane |
SAAS_URL to the wss://…/ws/bridge endpoint your operator provides.
Workspace layout
| Variable | Required | Default | Description |
|---|---|---|---|
AGENTS_FOLDER | No | User home directory | Parent directory for Bridge data |
{AGENTS_FOLDER}/.ctrlnode/ for task folders, workspace paths, and metadata. Non–OpenClaw providers also use paths under this tree.
Install scripts often set AGENTS_FOLDER in your shell profile so every terminal session agrees on the same root.
How providers are loaded
| Variable | Required | Default | Description |
|---|---|---|---|
PROVIDERS | No | All built-in providers | Comma-separated subset to load, e.g. copilot,cursor |
PROVIDER | No | — | Legacy alias for a single provider id |
sync_{provider}_agents after connect. The Bridge maps each agent id to the provider that registered it. You normally do not need to restrict PROVIDERS unless you want to disable unused implementations on a small machine.
Per-provider install and credentials: Providers.
OpenClaw paths
| Variable | Default | Description |
|---|---|---|
OPENCLAW_GATEWAY_URL | http://localhost:18789 | OpenClaw gateway HTTP base URL |
OPENCLAW_GATEWAY_TOKEN | — | Bearer token for gateway /tools/invoke |
OPENCLAW_HOME | ~/.openclaw (resolved) | OpenClaw state directory root |
OPENCLAW_CONFIG_PATH | — | Explicit path to openclaw.json |
OPENCLAW_STATE_DIR | — | Alternative state directory hint for config resolution |
PROVIDERS but openclaw.json is missing, the Bridge logs a warning and skips OpenClaw rather than exiting. Other providers can still run.
Provider credentials (summary)
Set only what you use. Full guides: Providers.| Provider id | Primary secrets / setup |
|---|---|
openclaw | OPENCLAW_GATEWAY_TOKEN, optional OPENCLAW_GATEWAY_URL |
claude | Claude Code CLI login (subscription) |
claude-sdk | ANTHROPIC_API_KEY or claude login / subscription mode |
copilot | COPILOT_GITHUB_TOKEN or copilot login |
gemini | GEMINI_API_KEY or GOOGLE_API_KEY, or gemini auth login |
codex | CODEX_API_KEY or codex auth login; optional CODEX_BIN_PATH |
cursor | CURSOR_API_KEY (required); Node.js for the SDK runner |
Connection and session timing
| Variable | Default | Description |
|---|---|---|
HEARTBEAT_MS | 30000 | Heartbeat interval to the control plane |
RECONNECT_MS | 5000 | Delay before reconnect after disconnect |
CONNECTION_TIMEOUT_MS | 10000 | WebSocket connect timeout |
POLL_CONFIG_MS | 60000 | Remote config poll interval |
AGENT_IDLE_RESET_MS | 15000 | Idle threshold for agent session handling |
SESSION_HISTORY_POLL_MS | 5000 | OpenClaw session history poll interval |
SESSION_INACTIVITY_TIMEOUT_MINUTES | 5 | Session inactivity cutoff |
Per-provider task timeouts
Each provider supports{PROVIDER}_TIMEOUT_MINUTES (default 10), for example:
CLAUDE_TIMEOUT_MINUTES,CLAUDE_SDK_TIMEOUT_MINUTESCOPILOT_TIMEOUT_MINUTES,GEMINI_TIMEOUT_MINUTES,CODEX_TIMEOUT_MINUTES,CURSOR_TIMEOUT_MINUTES
Claude / Copilot / Codex tuning
| Variable | Provider | Description |
|---|---|---|
CLAUDE_TOOLS | claude | Allowed tools for CLI (default Read,Write,Edit) |
CLAUDE_MAX_TURNS | claude | Max turns (default 20) |
CLAUDE_SKIP_PERMISSIONS | claude | Default true — avoids interactive permission prompts in unattended runs |
CLAUDE_SDK_TOOLS | claude-sdk | SDK tool allowlist |
CLAUDE_SDK_MAX_TURNS | claude-sdk | Default 50 |
CLAUDE_SDK_PERMISSION_MODE | claude-sdk | bypassPermissions, acceptEdits, dontAsk |
CLAUDE_SDK_EXECUTABLE | claude-sdk | Path to claude binary if not on PATH |
CODEX_BIN_PATH | codex | Absolute path when codex is not on PATH |
File watcher
| Variable | Default | Description |
|---|---|---|
WATCHER_USE_POLLING | false | Set true on network filesystems (SMB, NFS) |
WATCHER_POLL_INTERVAL | 1000 | Poll interval in ms when polling is enabled |
Debugging
| Variable | Description |
|---|---|
BRIDGE_INCOMING_DUMP_PATH | Optional directory to dump raw inbound WebSocket payloads for support |
ctrlnode-bridge in a terminal and watch stderr for JSON logs: handshake_sent, connecting, sync_*_agents, and provider warnings (missing API keys, skipped OpenClaw).
Re-run interactive setup only when starting from an empty config: ctrlnode-bridge --setup in a TTY (not used in normal service installs).
Troubleshooting
Bridge disconnected in the app
Bridge disconnected in the app
Confirm
ctrlnode-bridge is running, PAIRING_TOKEN in ~/.ctrlnode/.env is current, and no stale shell PAIRING_TOKEN overrides the file. Regenerate the token in Bridge Setup if needed.401 or auth errors on dispatch
401 or auth errors on dispatch
Check the provider’s API key or CLI login. The task may show Failed or Blocked; see Events in the app for CLI output.
Agent not found
Agent not found
Ensure the agent exists in Team and the Bridge completed handshake (
sync_*_agents). Reconnect the Bridge and refresh Team.Wrong provider ran the task
Wrong provider ran the task
Verify the project’s agent type matches the CLI you installed. Avoid restricting
PROVIDERS to a single id unless every agent in that project uses that CLI. See Providers.Workflow actions disabled (503)
Workflow actions disabled (503)
CtrlNode requires a live Bridge for run, clone, and rerun. Connect the Bridge first — see Install.
Duplicate PAIRING_TOKEN= in .env
Duplicate PAIRING_TOKEN= in .env
Pasting tokens sometimes adds a second
PAIRING_TOKEN= line. Keep one line; installers normalize common mistakes.