Skip to content

README.md

Latest commit

 

History

History
243 lines (164 loc) · 9.03 KB

README.md

File metadata and controls

243 lines (164 loc) · 9.03 KB
CTRL NODE

Orchestrate AI coding agents — tasks, routines, and workflows — from anywhere.

License: ELv2 Release Website

Website · Releases · Bridge setup

CTRL NODE is a remote orchestration platform for AI coding agents. Install the Bridge binary on any machine — your laptop, a dev VPS, a CI box — and from app.ctrlnode.ai you can dispatch tasks, schedule recurring routines, and design multi-step workflows that trigger automatically, all without opening a single inbound port.

Works with Claude, Copilot, Gemini, Codex, Cursor, OpenClaw, or any combination. Your code and workspaces never leave your machine — CTRL NODE only sees the output you explicitly stream back.

What's new in v2.2 and 2.3

  • Hermes provider — native support for Hermes agents via ACP; each agent gets its own isolated profile
  • Binary renamed — ctrlnode-bridge is now just ctrlnode; install scripts update PATH automatically
  • Setup wizard — run ctrlnode --setup to configure workspace and pairing token interactively; config is saved and reused on every subsequent run
  • Model selection — choose the exact AI model per agent (claude-sonnet-4-6, gpt-5.5, gemini-3.1-pro, …); the Bridge reports available models on connect and the UI surfaces them as a searchable drop-down
  • 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.

How it works

  You — anywhere on the internet
  (browser, laptop, phone)
          │
          │  https://app.ctrlnode.ai
          ▼
    CTRL NODE control plane    ← hosted UI & orchestration
      ├── Task & Kanban board
      ├── Routines scheduler
      ├── Workflow designer (trigger → steps → done)
      └── Team, memory & activity dashboard
          │
          │  WebSocket (outbound from Bridge — no open ports needed)
          ▼
    Your machine / VPS
      ├── CTRL NODE Bridge   ← lightweight binary you run (open source)
      ├── Claude / Copilot / Gemini / Codex / Cursor / OpenClaw
      └── Agent workspaces (files and outputs — stay local)

The Bridge makes a single outbound WebSocket connection. No inbound ports, no VPN, no firewall rules — it works behind NAT, inside Docker, on a headless server.

Supported providers

Provider Backend Key env var
claude Anthropic @anthropic-ai/claude-agent-sdk ANTHROPIC_API_KEY
copilot GitHub Copilot (ACP protocol) (Copilot extension)
gemini Google Gemini CLI (ACP protocol) GEMINI_API_KEY
codex OpenAI @openai/codex-sdk CODEX_API_KEY
cursor Cursor @cursor/sdk CURSOR_API_KEY
hermes Hermes (ACP protocol) (Hermes CLI)
openclaw OpenClaw HTTP gateway OPENCLAW_GATEWAY_TOKEN

All providers run from the same Bridge process automatically — no configuration needed.

Features

  • Remote task launch — write a task in the web UI, run it on your machine from anywhere; no SSH, no VPN, no open ports
  • Routines — schedule recurring agent tasks (cron-style); runs are tracked and streamed like any manual task
  • Multi-agent Workflows — visual workflow designer; wire steps together, set a time or event trigger, deploy in one click
  • Live output stream — watch the agent work line by line from your browser in real time
  • Outbound-only Bridge — single lightweight binary, one outbound WebSocket; NAT, Docker, and headless VPS all work out of the box
  • Multi-provider — Claude, Copilot, Gemini, Codex, Cursor, OpenClaw from one Bridge process; mix providers across steps
  • Model selection — pick the exact model per agent; Bridge reports available models on connect
  • Kanban workflow — BACKLOG → INBOX → ACTIVE → DONE with real-time agent feedback
  • Team & dashboard — operators, roles, live activity and fleet overview
  • Memory — persistent knowledge attached to each project, accessible to agents
  • Zero-storage by design — workspaces stay on your side; CTRL NODE only sees what you stream explicitly

Get started in 3 steps

1 — Sign up

Create an account at ctrlnode.ai. You'll get a Pairing Token from Settings → Bridge.

2 — Install the Bridge

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

curl -fsSL https://raw.githubusercontent.com/ctrlnode-ai/ctrlnode/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/ctrlnode-ai/ctrlnode/main/install.ps1 | iex

Installs to /usr/local/bin/ (Linux/macOS) or %LOCALAPPDATA%\Programs\ctrlnode (Windows, added to PATH).

Manual download
Platform Binary
Linux x64 (modern CPUs, AVX2) ctrlnode-linux-x64
Linux x64 (older CPUs / cloud VMs) ctrlnode-linux-x64-baseline
macOS Apple Silicon ctrlnode-darwin-arm64
Windows x64 ctrlnode.exe

→ Download from Releases

Not sure which Linux binary? Run grep -o "avx[^ ]*" /proc/cpuinfo | head -1 — avx2 → standard, anything else → -baseline.

3 — Run it

First run — launches the setup wizard:

$ ctrlnode --setup

Where is your workspace? [/home/user]: /home/user/code
Pairing token: xxxxxxxxxx

Config saved to: /home/user/code/.ctrlnode/.env
Run ctrlnode to start the bridge.

Then start the Bridge:

$ ctrlnode
Reading config from: /home/user/code/.ctrlnode/.env
...connected

On subsequent runs the Bridge reads the saved config automatically. Run ctrlnode --setup again to change workspace or pairing token.

Your agents appear in the web UI automatically. Create a task, assign it, and watch it run live from your browser.

Multi-agent Workflows — visual automation

Multi-agent Workflows canvas

Design a workflow in the drag-and-drop canvas: drop agent nodes, wire the output of one step into the input of the next, set a trigger (schedule or event), and deploy. Each step runs on whichever agent and provider you choose — Claude for one step, Codex for the next.

  • Branching and fan-out
  • Cross-provider chains
  • Time triggers and event triggers
  • Live output stream per step

Kanban — ship tasks like a product team

Kanban board

Write a task, assign an agent, and drop it on the board. CTRL NODE automatically moves it through BACKLOG → INBOX → ACTIVE → DONE as the Bridge dispatches it to your agents and they report back in real time.

Routines — recurring scheduled tasks

Routines calendar view

Create a Routine to run a task on a repeating schedule (daily summary, nightly refactor, weekly report…). The agent receives the task exactly as if you sent it manually — same live stream, same output artifacts, same status tracking.

What's in this repository

Component Path
Bridge source (open source) src/
Provider guides doc/
Release notes Releases/

Provider guides

Contributing

PRs are welcome. For major changes, open an issue first.

git clone https://github.com/ctrlnode-ai/ctrlnode.git
cd ctrlnode
bun install
bun dev

License

Licensed under the Elastic License 2.0 (ELv2).

  • ✅ Use freely on your own machines
  • ✅ Modify and redistribute
  • ❌ Cannot be offered as a managed/hosted service to third parties

Built by CTRL NODE