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

> All agent CLIs load in one Bridge — sync_*_agents routing, Hermes, env vars

The Bridge loads **every** built-in provider in one process. You do **not** enable or disable providers with `PROVIDERS` — that variable is ignored. CtrlNode routes each task to the provider that owns the agent id via **`sync_{provider}_agents`** on connect.

Open-source reference: [github.com/ctrlnode-ai/ctrlnode](https://github.com/ctrlnode-ai/ctrlnode).

## Supported providers

| CtrlNode agent type | Bridge id    | Guide                                              |
| ------------------- | ------------ | -------------------------------------------------- |
| `OpenClaw`          | `openclaw`   | [OpenClaw](/bridge/providers/openclaw)             |
| `ClaudeCode`        | `claude`     | [Claude Code (CLI)](/bridge/providers/claude-code) |
| `ClaudeAgentSdk`    | `claude-sdk` | [Claude Agent SDK](/bridge/providers/claude-sdk)   |
| `Copilot`           | `copilot`    | [GitHub Copilot](/bridge/providers/copilot)        |
| `Gemini`            | `gemini`     | [Gemini CLI](/bridge/providers/gemini)             |
| `CodexSdk`          | `codex`      | [OpenAI Codex](/bridge/providers/codex)            |
| `Cursor`            | `cursor`     | [Cursor](/bridge/providers/cursor)                 |
| `Hermes`            | `hermes`     | [Hermes](/bridge/providers/hermes)                 |

<Note>
  Pick the **agent type** that matches the CLI installed on the Bridge host. One Bridge can serve Copilot, Hermes, and Cursor agents at the same time.
</Note>

## How routing works

```mermaid theme={null}
sequenceDiagram
  participant App as CtrlNode app
  participant API as API
  participant Bridge as ctrlnode
  participant CLI as Agent CLI
  App->>API: Dispatch task
  API->>Bridge: intent (WebSocket)
  Bridge->>CLI: provider for agent id
  CLI-->>Bridge: stream + result
  Bridge-->>API: task_complete / blocked
  API-->>App: SignalR update
```

1. Create a **project** with a default agent type (CLI badge in the sidebar).
2. Register **agents** in Team with that type (or override per agent).
3. Bridge connects → CtrlNode pushes **`sync_{provider}_agents`** for each provider that has agents.
4. **Dispatch** uses the agent id to select the implementation.

Install only the CLIs you need. If a provider is not installed, tasks for that agent fail with a clear error — not silent routing to another tool.

## Multi-provider Bridge

**Do not set `PROVIDERS`.** One `ctrlnode` process already includes:

```text theme={null}
openclaw, claude, claude-sdk, copilot, gemini, codex, cursor, hermes
```

Reduce disk and attack surface by uninstalling unused CLIs on the host, not by env vars.

## Sessions and resume

| Provider                                          | Session behavior                                            |
| ------------------------------------------------- | ----------------------------------------------------------- |
| `claude` (CLI)                                    | Resumes with Claude `--resume` when the same task continues |
| `claude-sdk`, `copilot`, `gemini`, `hermes` (ACP) | Fresh ACP session per dispatch                              |
| `codex`, `cursor`                                 | Per-agent home / SDK runner isolation                       |
| `openclaw`                                        | OpenClaw gateway sessions                                   |
| `hermes` (CLI fallback)                           | Resume ids under agent Hermes profile dirs                  |

## Common troubleshooting

| Symptom                  | Likely cause                                                      |
| ------------------------ | ----------------------------------------------------------------- |
| Task stuck in **Inbox**  | Bridge offline or agent not synced                                |
| **Failed** with 401      | Expired API key or CLI not logged in                              |
| **Agent not found**      | Agent created after connect — restart `ctrlnode`                  |
| Wrong tool ran the task  | Agent type ≠ installed CLI                                        |
| No terminal event in app | Outdated Bridge — current builds send `contextTaskId` on dispatch |

## Per-provider documentation

<CardGroup cols={2}>
  <Card title="OpenClaw" icon="robot" href="/bridge/providers/openclaw">
    HTTP gateway, `openclaw.json`, orchestration
  </Card>

  <Card title="Claude Code (CLI)" icon="terminal" href="/bridge/providers/claude-code">
    `claude` CLI, `CLAUDE.md` in task folder
  </Card>

  <Card title="Claude Agent SDK" icon="code" href="/bridge/providers/claude-sdk">
    `@anthropic-ai/claude-agent-sdk`
  </Card>

  <Card title="GitHub Copilot" icon="github" href="/bridge/providers/copilot">
    `copilot` ACP, PAT or login
  </Card>

  <Card title="Gemini CLI" icon="google" href="/bridge/providers/gemini">
    `gemini` ACP
  </Card>

  <Card title="OpenAI Codex" icon="openai" href="/bridge/providers/codex">
    `@openai/codex-sdk`
  </Card>

  <Card title="Cursor" icon="cursor" href="/bridge/providers/cursor">
    `@cursor/sdk`, `CURSOR_API_KEY`
  </Card>

  <Card title="Hermes" icon="wand-magic-sparkles" href="/bridge/providers/hermes">
    `hermes acp` (primary) or `hermes chat` CLI
  </Card>
</CardGroup>