Skip to main content
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.

​
Supported providers

CtrlNode agent typeBridge idGuide
OpenClawopenclawOpenClaw
ClaudeCodeclaudeClaude Code (CLI)
ClaudeAgentSdkclaude-sdkClaude Agent SDK
CopilotcopilotGitHub Copilot
GeminigeminiGemini CLI
CodexSdkcodexOpenAI Codex
CursorcursorCursor
HermeshermesHermes
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.

​
How routing works

  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: 
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

ProviderSession behavior
claude (CLI)Resumes with Claude --resume when the same task continues
claude-sdk, copilot, gemini, hermes (ACP)Fresh ACP session per dispatch
codex, cursorPer-agent home / SDK runner isolation
openclawOpenClaw gateway sessions
hermes (CLI fallback)Resume ids under agent Hermes profile dirs

​
Common troubleshooting

SymptomLikely cause
Task stuck in InboxBridge offline or agent not synced
Failed with 401Expired API key or CLI not logged in
Agent not foundAgent created after connect — restart ctrlnode
Wrong tool ran the taskAgent type ≠ installed CLI
No terminal event in appOutdated Bridge — current builds send contextTaskId on dispatch

​
Per-provider documentation

OpenClaw

HTTP gateway, openclaw.json, orchestration

Claude Code (CLI)

claude CLI, CLAUDE.md in task folder

Claude Agent SDK

@anthropic-ai/claude-agent-sdk

GitHub Copilot

copilot ACP, PAT or login

Gemini CLI

gemini ACP

OpenAI Codex

@openai/codex-sdk

Cursor

@cursor/sdk, CURSOR_API_KEY

Hermes

hermes acp (primary) or hermes chat CLI