Bridge overview

Outbound WebSocket runtime — ctrlnode binary, BASE_PATH, all providers, Hermes, routing

The Bridge is the open-source agent runtime you install on your machine. CtrlNode is the control plane in the browser; ctrlnode executes tasks locally and streams results over a single outbound WebSocket. Repositories and agent workspaces stay on your hardware.

Source: github.com/ctrlnode-ai/ctrlnode

Architecture

Component	Role
Web app	Tasks, Kanban, workflows, routines, team, project work directory
Bridge (ctrlnode)	Connection, dispatch, file sync, provider implementations
Providers	OpenClaw, Claude, Copilot, Gemini, Codex, Cursor, Hermes

No inbound ports. Works behind NAT, in Docker, and on headless hosts.

Binary name

Platform	Release asset	Typical command
Windows	ctrlnode.exe	ctrlnode
Linux	ctrlnode-linux-x64 or ctrlnode-linux-x64-baseline	ctrlnode
macOS (ARM)	ctrlnode-darwin-arm64	ctrlnode

Legacy names such as ctrlnode-bridge are no longer used in installers or docs.

Pairing

1. Sign in at app.ctrlnode.ai.
2. Open System → Bridge Setup (or the setup wizard token step).
3. Generate a pairing token and copy it once.
4. Run ctrlnode with that token (see Install).

The Bridge sends a handshake with version and loaded providers. CtrlNode marks the org connected when the socket is live.

Configuration

Installers write:

~/.ctrlnode/.env

with PAIRING_TOKEN, SAAS_URL, and BASE_PATH (workspace parent). The Bridge also reads .env from {BASE_PATH}/.ctrlnode/.env first, then cwd. See Configuration.

Data layout under BASE_PATH

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

Hermes runtime profiles (config.yaml, SOUL.md) live under ~/.hermes/profiles/{agentId}/ (HERMES_HOME at spawn). The .ctrlnode/agents/ folder is for Bridge-managed AGENTS.md copies when a Hermes agent is provisioned — Claude, Copilot, Cursor, and Gemini do not use it.

Project work directory is configured in the app per project (not BASE_PATH). Tasks in WORK DIRECTORY mode can read and edit that full directory. See Task work modes.

Agent routing (no PROVIDERS env)

All provider implementations load in every Bridge process. PROVIDERS / PROVIDER environment variables are ignored.

CtrlNode drives routing:

1. Each project has a default agent type (CLI badge).
2. Each agent in Team has agent_type.
3. On connect, CtrlNode sends sync_{provider}_agents per provider.
4. Dispatch resolves agent id → provider → runs that CLI/SDK.

Project agent type	Bridge provider id
OpenClaw	openclaw
ClaudeCode	claude
ClaudeAgentSdk	claude-sdk
Copilot	copilot
Gemini	gemini
CodexSdk	codex
Cursor	cursor
Hermes	hermes

Runtime responsibilities

• Dispatch — run provider for task intent; stream activity to CtrlNode
• Task modes — OUTPUT ONLY (isolated task folder) vs WORK DIRECTORY (project repo or Bridge home)
• Terminal states — completed, blocked, failed (including CLI auth errors)
• File events — notify the app when agents write under task or repo paths
• Models — report models per provider after connect
• Sync — register agents from CtrlNode; OpenClaw may discover local openclaw.json agents

Related docs

Topic	Page
Install	Install
Environment	Configuration
CLIs	Providers
Task OUTPUT vs WORK DIRECTORY	Task work modes
UI tokens	Bridge Setup