Documentation Index
Fetch the complete documentation index at: https://docs.ctrlnode.ai/llms.txt
Use this file to discover all available pages before exploring further.
The Bridge is the open-source agent runtime you install on your own machine. CtrlNode is the control plane in the browser; the Bridge executes tasks locally and streams results back over a single outbound WebSocket. Your repositories and agent workspaces stay on your machine.
Source code: github.com/ctrlnode-ai/ctrlnode
Architecture
| Component | Role |
|---|
| Web app | Tasks, Kanban, workflows, routines, team, tokens |
| Bridge | Persistent connection, dispatch, file sync, provider routing |
| Providers | OpenClaw, Claude, Copilot, Gemini, Codex, Cursor (see Providers) |
Pairing
- Sign in at app.ctrlnode.ai.
- Open System → Bridge Setup (or complete the setup wizard token step).
- Generate a pairing token and copy it once.
- Start the Bridge with that token (see Install).
The Bridge sends a handshake with its version and enabled providers. CtrlNode marks the org as connected when the socket is live.
Configuration file
On first run, the interactive wizard (or your installer) typically writes:
The Bridge also reads .env from the current working directory and from {AGENTS_FOLDER}/.ctrlnode/.env. Shell environment variables override file values — if PAIRING_TOKEN is set in your terminal, it wins over the file.
Workspaces
Non-OpenClaw providers store task and workspace data under:
{AGENTS_FOLDER}/.ctrlnode/tasks/...
AGENTS_FOLDER to your home directory by default. Each agent has a workspace folder; CtrlNode can push AGENTS.md and read task artifacts when the Bridge is connected.
OpenClaw uses paths from openclaw.json and talks to a local HTTP gateway (default http://localhost:18789).
Agent routing
When you create a project, you pick a default agent type (CLI). Each agent in Team is registered with that type. On connect, CtrlNode sends sync_{provider}_agents messages so the Bridge maps agent IDs to the correct provider implementation.
| Project agent type | Bridge provider id |
|---|
OpenClaw | openclaw |
ClaudeCode | claude |
ClaudeAgentSdk | claude-sdk |
Copilot | copilot |
Gemini | gemini |
CodexSdk | codex |
Cursor | cursor |
What the Bridge does at runtime
- Dispatch — receives task intents, runs the provider, streams stdout/activity to CtrlNode
- Terminal states — reports
completed, blocked, or failed (including auth errors from the underlying CLI)
- File events — notifies the app when agents write under task folders
- Models — reports available models per provider after connect (shown in the agent editor)
- Sync — registers agents from CtrlNode; OpenClaw can additionally discover local
openclaw.json agents
| Topic | Page |
|---|
| Install scripts | Install |
| Environment variables | Configuration |
| Per-CLI setup | Providers |
| Tokens in the UI | Bridge Setup |
| First-time wizard | Quickstart |
