Bridge overview - CtrlNode

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

Sign in at app.ctrlnode.ai.
Open System → Bridge Setup (or the setup wizard token step).
Generate a pairing token and copy it once.
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:

Each project has a default agent type (CLI badge).
Each agent in Team has agent_type.
On connect, CtrlNode sends sync_{provider}_agents per provider.
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

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

​Architecture

​Binary name

​Pairing

​Configuration

​Data layout under BASE_PATH

​Agent routing (no PROVIDERS env)

​Runtime responsibilities

​Related docs