Install the Bridge

Install ctrlnode (Windows, Linux, macOS), BASE_PATH workspace, pairing token, verify connection

Install the open-source Bridge binary (ctrlnode) from github.com/ctrlnode-ai/ctrlnode, pair it with CtrlNode, and confirm the app shows connected.

Before you start

• A CtrlNode account at app.ctrlnode.ai
• A pairing token from System → Bridge Setup or the setup wizard Token step
• Network egress to wss://api.ctrlnode.ai (default control plane)

One-line installers

Windows (PowerShell)

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

The script:

• Downloads the latest ctrlnode.exe from GitHub Releases
• Installs to %LOCALAPPDATA%\Programs\ctrlnode (or a path you choose)
• Adds that folder to your user PATH (command name: ctrlnode)
• Sets BASE_PATH to your chosen workspace parent (where {BASE_PATH}/.ctrlnode lives)
• Optionally starts the Bridge when you answer y at the end

Linux / macOS

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

Custom install directory:

curl -fsSL https://raw.githubusercontent.com/ctrlnode-ai/ctrlnode/main/install.sh | sh -s -- --dir ~/.local/bin

The script installs ctrlnode (Linux x64 or x64-baseline by CPU features, or ctrlnode-darwin-arm64 on Apple Silicon) and sets BASE_PATH in your shell profile.

Manual download

Platform	Release asset	Command on PATH
Windows x64	ctrlnode.exe	ctrlnode
Linux x64 (AVX2)	ctrlnode-linux-x64	ctrlnode
Linux x64 (older CPUs / many VMs)	ctrlnode-linux-x64-baseline	ctrlnode
macOS Apple Silicon	ctrlnode-darwin-arm64	ctrlnode

Download from GitHub Releases. On Linux:

grep -o "avx[^ ]*" /proc/cpuinfo | head -1

avx2 → standard binary; otherwise use -baseline.

Start the Bridge

Copy the pairing token when generated — you cannot view it again. Regenerate from Bridge Setup if you lose it.

Windows

$env:PAIRING_TOKEN="<paste-token>"
ctrlnode

Linux / macOS

PAIRING_TOKEN=<paste-token> ctrlnode

Installers also write ~/.ctrlnode/.env with PAIRING_TOKEN, SAAS_URL, and BASE_PATH when you use the interactive flow.

Token and BASE_PATH precedence

Source	Wins?
Shell ($env:PAIRING_TOKEN, $env:BASE_PATH, etc.)	Yes — overrides .env for most keys
~/.ctrlnode/.env from installer	Authoritative for PAIRING_TOKEN, SAAS_URL, BASE_PATH when present
First-run prompts	Used when keys are missing

If pairing fails after a new token, unset stale shell variables:

Remove-Item Env:PAIRING_TOKEN -ErrorAction SilentlyContinue

unset PAIRING_TOKEN

Verify in CtrlNode

1. Open System → Bridge Setup — status Connected (green).
2. Open Team — agents appear after sync_*_agents on connect.
3. Dispatch a test task — moves to In progress with live activity.

Run as a service (optional)

Run ctrlnode as a long-lived process under the same user that owns BASE_PATH and ~/.ctrlnode/.env (systemd, Windows Task Scheduler, or a supervisor).

Next steps

• Bridge configuration — BASE_PATH, API keys, timeouts
• Providers — CLIs including Hermes
• Bridge overview — routing (no PROVIDERS env needed)