> ## 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.

# 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](https://app.ctrlnode.ai) 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](https://github.com/ctrlnode-ai/ctrlnode)

## Architecture

```mermaid theme={null}
flowchart TB
  subgraph cloud [CtrlNode cloud]
    App[Web app]
    API[API + SignalR]
  end
  subgraph local [Your machine]
    Bridge[ctrlnode]
    CLI[Agent CLIs / SDKs]
    Data["{BASE_PATH}/.ctrlnode"]
  end
  App --> API
  Bridge -->|outbound WSS| API
  App -->|live updates| API
  Bridge --> CLI
  CLI --> Data
```

| 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](https://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](/bridge/install)).

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

## Configuration

Installers write:

```text theme={null}
~/.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](/bridge/configuration).

## Data layout under `BASE_PATH`

```text theme={null}
{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](/tasks/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](/bridge/install)                    |
| Environment                   | [Configuration](/bridge/configuration)        |
| CLIs                          | [Providers](/bridge/providers)                |
| Task OUTPUT vs WORK DIRECTORY | [Task work modes](/tasks/task-work-modes)     |
| UI tokens                     | [Bridge Setup](/getting-started/bridge-setup) |