CtrlNode Bridge 2026.2.4

CtrlNode Bridge v2026.2.4 Release Notes

This release adds live model updates from the server and fixes premature task completion.

---

What's new

Model list updated from the server — no Bridge reinstall needed

Model lists are now fetched from the CtrlNode backend on startup and refreshed after every connection. New models — including Claude Fable 5 and Claude Mythos 5 — become available automatically without installing a new Bridge version.

When the server is unreachable the previous cached list is used; if no cache exists, the built-in fallback list applies.

Auto-update on startup

Bridge checks for a newer version before connecting. When one is available it shows the versions and a link to the release notes, then asks [Y/n]. Answering Y downloads the new binary, replaces the current executable, and restarts automatically.

Non-interactive environments (no TTY, Docker) skip the prompt and continue with the current version. Network errors are ignored so the Bridge always starts.

Fix: task marked done too early

Agents that write several output files in sequence could trigger a premature task_complete signal when the first file landed. Bridge now waits 45 seconds after the last file write before declaring the task done, giving the agent time to finish all its output. An explicit <TASK_COMPLETED:…> or <TASK_FAILED:…> tag cancels the wait immediately.

---

Upgrade

Replace the binary and restart. No configuration changes are required. Run ctrlnode --setup if you want to update your workspace, pairing token, or provider API keys.

CtrlNode Bridge 2026.2.3

CtrlNode Bridge v2026.2.3 Release Notes

This release improves error handling in the Hermes provider, adds automatic Codex binary discovery, and adds support for the new Claude Opus 4.8 model.

---

What's new

Claude Opus 4.8 support

claude-opus-4-8 is now included in the known-models fallback lists for Anthropic, Copilot, and Cursor providers. When no API key is configured the model is available immediately; with an API key it is returned directly from the live API.

Hermes ACP — blockable error detection

The Hermes ACP provider can now distinguish between configuration errors (invalid model, missing or invalid API key) and fatal execution errors. When a configuration error is detected in the agent output or stderr, the task is marked as blocked instead of failed, which allows the orchestrator to surface a clear remediation message rather than treating it as an unrecoverable failure.

Detected patterns include: invalid model ID, invalid or missing API key, and similar provider-side configuration problems.

Hermes ACP — stderr capture

The Hermes ACP process now captures stderr in addition to stdout. The captured stderr is included in blockable-error detection, so configuration errors printed to stderr are correctly classified.

Codex — automatic binary resolution

The Codex SDK provider now resolves the codex binary from the system PATH automatically when CODEX_BIN_PATH is not set. On Windows it prefers the .exe over a .cmd wrapper to ensure direct spawning works correctly.

Installer simplified

The install scripts (install.ps1 / install.sh) no longer ask for the binary install directory (it defaults silently to %LOCALAPPDATA%\Programs\ctrlnode on Windows and /usr/local/bin on Linux/macOS). API key configuration has been removed from the installer entirely — run ctrlnode --setup after installation to configure the pairing token and any provider API keys.

---

Binaries

File	Target
ctrlnode.exe	Windows x64
ctrlnode-linux-x64	Linux x64 (requires AVX2)
ctrlnode-linux-x64-baseline	Linux x64 (no AVX2 — older CPUs / cloud VMs)
ctrlnode-darwin-arm64	macOS Apple Silicon

---

Upgrade

Replace the binary and restart. No configuration changes are required. Run ctrlnode --setup if you want to update your workspace, pairing token, or provider API keys.

CtrlNode Bridge 2026.2.2

CtrlNode Bridge v2026.2.2 Release Notes

This release adds Hermes provider support, renames the binary to ctrlnode, and introduces an interactive setup wizard so first-run configuration requires no manual file editing.

---

What's new

Hermes provider

The Bridge now supports Hermes as a native provider via the ACP protocol (hermes acp). Each Hermes agent gets its own isolated profile directory so credentials and conversation history never mix across agents.

Binary renamed to ctrlnode

The binary was previously named ctrlnode-bridge[.exe]. It is now simply ctrlnode[.exe]. The install scripts install it under the new name and add it to PATH.

Setup wizard (ctrlnode --setup)

Run ctrlnode --setup to configure the Bridge interactively:

• Choose your workspace — the root folder the Bridge can read and write. For developers, this is typically your code root.
• Enter your pairing token (Settings → Bridge at app.ctrlnode.ai).
• The token is saved to <workspace>/.ctrlnode/.env and BASE_PATH is persisted as a user environment variable automatically.

On subsequent runs the Bridge reads the saved config with no prompts. If the token is missing it asks inline before connecting.

Config file shown at startup

The Bridge now prints which .env file it loaded at startup, and reminds you of the --setup command if you need to reconfigure.

---

Binaries

File	Target
ctrlnode.exe	Windows x64
ctrlnode-linux-x64	Linux x64 (requires AVX2)
ctrlnode-linux-x64-baseline	Linux x64 (no AVX2 — older CPUs / cloud VMs)
ctrlnode-darwin-arm64	macOS Apple Silicon

---

Upgrade

Replace the binary with the new ctrlnode binary and restart. If you have ctrlnode-bridge in your PATH, remove or rename the old binary. Run ctrlnode --setup if you want to move your workspace or update your pairing token.

CtrlNode Bridge 2026.2.1

CtrlNode Bridge 2026.2.1 Release Notes

This release adds model selection support to the Bridge: every provider now reports the AI models it supports, and CtrlNode displays them as suggestions when you create or edit an agent — so you can pick the exact model without having to remember or type IDs manually.

---

What's new

Model selection in agent setup

When the Bridge connects to CtrlNode, it queries each provider's available models and sends them to the platform. The agent creation and edit forms now show a MODEL field with a searchable drop-down populated from the live list.

• Start typing to filter — press Enter or click a suggestion to confirm.
• If no model is entered the provider uses its default.
• The list is scoped to the selected provider when one is detected; otherwise all known models across providers are shown.

Built-in model lists per provider

Each provider ships a curated fallback list used when the live API is unavailable or no API key is configured:

Provider	Source	Notable models
copilot	GitHub Copilot docs	claude-sonnet-4-6, gemini-2.5-pro, gpt-5.5, gpt-5.3-codex, …
gemini	Google AI Gemini API docs	gemini-2.5-pro/flash/flash-lite, gemini-3.1-flash-lite, gemini-3.1-pro-preview
cursor	Cursor pricing docs	claude-opus-4-7, gpt-5.5, grok-4.3, grok-4.20, kimi-k2.5, composer-2.5, …
claude / claude-sdk	Anthropic API (/v1/models)	dynamic list fetched at connect time
claude-code	Anthropic API (/v1/models)	dynamic list fetched at connect time
codex	OpenAI API (/v1/models)	dynamic list fetched at connect time

When a live API call succeeds, the dynamic list replaces the fallback. MultiProvider merges and deduplicates lists from all sub-providers.

New IProvider.listModels() method

All providers now implement the optional listModels(): Promise<string[]> method on the IProvider interface. The Bridge calls this once after the handshake and sends the results to CtrlNode via a new WebSocket message:

{ "action": "available_models", "models": { "copilot": ["claude-sonnet-4-6", ...], "cursor": [...] } }

CtrlNode stores the map, broadcasts it over SignalR to connected clients, and includes it in the /api/system/bridge/status REST response so the UI stays in sync even after a page refresh.

---

Binaries

File	Target
ctrlnode-bridge.exe	Windows x64
ctrlnode-bridge-linux-x64	Linux x64 (requires AVX2)
ctrlnode-bridge-linux-x64-baseline	Linux x64 (no AVX2 — older CPUs / cloud VMs)
ctrlnode-bridge-darwin-arm64	macOS Apple Silicon

---

Upgrade

Replace the binary and restart the Bridge process. No configuration changes are required — the model list is populated automatically on connect.

CtrlNode Bridge 2026.2.0

CtrlNode Bridge 2026.2.0 Release Notes

This release expands the Bridge beyond OpenClaw by introducing a multi-provider architecture — you can now connect any supported AI coding agent CLI (Claude, Copilot, Gemini, Codex, Cursor) to CtrlNode, alongside or instead of OpenClaw. Each backend is called a Provider.

---

What's new

Multi-provider architecture

The Bridge now manages multiple agent providers in a single process. A new PROVIDERS environment variable accepts a comma-separated list of provider names:

PROVIDERS=openclaw,claude,copilot,cursor,gemini,cursor

The previous PROVIDER (singular) variable still works as a fallback. When more than one provider is listed, a MultiProvider composite routes each task to the correct backend based on agent ownership, with first-registered provider winning on ID conflicts.

New providers

Provider name	SDK / protocol	Key env var
openclaw	OpenClaw Gateway HTTP (unchanged)	OPENCLAW_GATEWAY_TOKEN
claude	@anthropic-ai/claude-agent-sdk	ANTHROPIC_API_KEY
copilot	@agentclientprotocol/sdk (ACP)	(Copilot extension)
gemini	@agentclientprotocol/sdk (ACP)	(Gemini CLI)
codex	@openai/codex-sdk	CODEX_API_KEY
cursor	@cursor/sdk via Node.js runner	CURSOR_API_KEY

All providers implement the same IProvider interface (dispatchTask, sendToSession, invokeTool, discoverAgents, deleteAgent, resolveFilesystemBase), so the Bridge core treats them identically.

Provider-specific highlights

Claude Agent SDK (claude-sdk)

• Uses the programmatic @anthropic-ai/claude-agent-sdk query() API — no subprocess, no stdin/arg-length limits.
• Writes a CLAUDE.md context file into the task folder with the agent's role and instructions so Claude picks them up via normal project-file discovery.
• Splits the task prompt into body + ## INSTRUCTIONS block, placing instructions in the system prompt for a cleaner agent context.
• Real-time streaming of assistant events forwarded to CtrlNode SaaS.
• Session resume support (session ID cached per taskId).
• CLAUDE_SDK_TOOLS, CLAUDE_SDK_MAX_TURNS, CLAUDE_SDK_TIMEOUT_MINUTES, CLAUDE_SDK_PERMISSION_MODE, CLAUDE_SDK_MODEL env vars.

Cursor SDK (cursor)

• @cursor/sdk uses gRPC (HTTP/2) which is incompatible with Bun's http2 stack; the provider spawns a Node.js child process (cursor-sdk-runner.mjs) and communicates over stdin/stdout JSONL.
• The runner binary is embedded in the Bridge executable; on first run it is extracted to a temp path. The cached file is always overwritten to prevent stale-runner issues after upgrades.
• CURSOR_API_KEY, CURSOR_TIMEOUT_MINUTES.

Copilot / Gemini ACP (copilot, gemini)

• Both use the Agent Client Protocol (ACP) SDK over stdio.
• Agent instructions (description) are prepended to the task prompt so each agent behaves according to its configured role.
• COPILOT_TIMEOUT_MINUTES, GEMINI_TIMEOUT_MINUTES.

Codex SDK (codex)

• Wraps @openai/codex-sdk, which drives codex app-server internally over stdio JSON-RPC.
• Per-agent CODEX_HOME provisioning keeps each agent's configuration isolated.
• CODEX_TIMEOUT_MINUTES.

Shared provider utilities

A new providerFileUtils.ts module centralises the filesystem bookkeeping that was previously duplicated across providers:

• writeTaskOutputs — writes the final output markdown and agent log, stripping <TASK_COMPLETED/FAILED/BLOCKED> tags from persisted files.
• detectStatusTag — detects completion / blocked / failed status from agent output text.
• writeOutputFile / writeAgentLog — low-level writers shared by all providers.

Agent lifecycle & synchronisation

• sync_claude_sdk_agents, sync_copilot_agents, sync_gemini_agents, sync_codex_agents, sync_cursor_agents WebSocket commands register provider agents from the SaaS without requiring the Bridge to auto-discover them (prevents phantom UNREGISTERED cards before any agent is configured).
• delete_agent_folders command removes agent filesystem folders recursively.
• Purged/deleted agent IDs are tracked in memory to prevent re-discovery from SDK list() calls within the same session.

Environment & configuration

• .env loading from cwd at startup covers all new env vars (API keys, timeout overrides).
• AGENTS_CTRLNODE_ROOT is now the canonical workspace root used consistently across all providers for task folder resolution and filesystem operations.
• resolveProjectHome(agentId) derives the agent's project home within the root.
• Startup validation warns early when a required API key is missing for a configured provider.

Filesystem handlers

• resolveFilesystemBase / resolveFilesystemBaseByProvider on every provider enable correct path resolution for read_file, write_file, list_files, delete_path SaaS commands regardless of which provider owns the agent.
• trustedFolders.json is updated automatically when Gemini trust is enabled for a workspace.

---

Breaking changes / migration

What changed	Action required
PROVIDER (singular) now becomes PROVIDERS[0]	No action — existing .env files continue to work
Default providers when PROVIDERS/PROVIDER is unset now includes all backends	If you only want OpenClaw, set PROVIDERS=openclaw explicitly
openclaw.json remains the source of truth for OpenClaw agents	No change

---

Install

Linux / macOS — one-liner, detects platform and CPU automatically:

curl -fsSL https://github.com/ctrlnode-ai/ctrlnode/releases/download/v2026.2.0/install.sh | sh

Windows (PowerShell):

irm https://github.com/ctrlnode-ai/ctrlnode/releases/download/v2026.2.0/install.ps1 | iex

Manual download

Platform	File
Linux (modern CPUs, AVX2)	ctrlnode-bridge-linux-x64
Linux (older CPUs, AVX only)	ctrlnode-bridge-linux-x64-baseline
macOS (Apple Silicon)	ctrlnode-bridge-darwin-arm64
Windows	ctrlnode-bridge.exe

Not sure which Linux binary? grep -q avx2 /proc/cpuinfo && echo standard || echo baseline

Quick start (multi-provider example)

# .env
PAIRING_TOKEN=your_pairing_token

# Run OpenClaw + Claude SDK + Cursor simultaneously
PROVIDERS=openclaw,claude-sdk,cursor

OPENCLAW_GATEWAY_TOKEN=your_openclaw_token
ANTHROPIC_API_KEY=your_anthropic_key
CURSOR_API_KEY=your_cursor_key

./ctrlnode-bridge-linux-x64

See the README and setup guides for full instructions.

CtrlNode Bridge 2026.1.0

CtrlNode Bridge 2026.1.0 Release Notes

First public release of the CtrlNode Bridge — the open-source connector between your local OpenClaw runtime and CtrlNode SaaS.

Install

Linux / macOS — one-liner, detects platform and CPU automatically:

curl -fsSL https://github.com/ctrlnode-ai/ctrlnode/releases/download/v2026.1.0/install.sh | sh

Windows (PowerShell):

irm https://github.com/ctrlnode-ai/ctrlnode/releases/download/v2026.1.0/install.ps1 | iex

The installer downloads the right binary, adds it to PATH, asks for your two tokens and prints the exact run command.

Manual download

Platform	File
Linux (modern CPUs, AVX2)	ctrlnode-bridge-linux-x64
Linux (older CPUs, AVX only)	ctrlnode-bridge-linux-x64-baseline
macOS (Apple Silicon)	ctrlnode-bridge-darwin-arm64
Windows	ctrlnode-bridge.exe

Not sure which Linux binary? grep -q avx2 /proc/cpuinfo && echo standard || echo baseline

Quick start (manual)

Linux / macOS

PAIRING_TOKEN="your_pairing_token" \
OPENCLAW_GATEWAY_TOKEN="your_gateway_token" \
./ctrlnode-bridge-linux-x64

Windows (PowerShell)

$env:PAIRING_TOKEN = "your_pairing_token"
$env:OPENCLAW_GATEWAY_TOKEN = "your_gateway_token"
.\ctrlnode-bridge.exe

See the README and setup guides for full instructions.