Skip to main content

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.

Install the open-source Bridge binary 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

irm https://raw.githubusercontent.com/ctrlnode-ai/ctrlnode/main/install.ps1 | iex
The script:
  • Downloads the latest ctrlnode-bridge.exe from GitHub Releases
  • Installs to %LOCALAPPDATA%\Programs\ctrlnode (or a path you choose)
  • Adds the folder to your user PATH
  • Sets AGENTS_FOLDER to your profile directory (workspace parent)
  • Optionally starts the Bridge when you answer y at the end

​
Manual download

PlatformAsset
Linux x64 (AVX2)ctrlnode-bridge-linux-x64
Linux x64 (older CPUs / many cloud VMs)ctrlnode-bridge-linux-x64-baseline
macOS Apple Siliconctrlnode-bridge-darwin-arm64
Windows x64ctrlnode-bridge.exe
Download from GitHub Releases. On Linux, check CPU features: 
grep -o "avx[^ ]*" /proc/cpuinfo | head -1
avx2 → standard binary; otherwise use -baseline.

​
Pairing token

Copy the token when generated — you cannot view it again. Create a new token from Bridge Setup if you lose it.
$env:PAIRING_TOKEN="<paste-token>"
ctrlnode-bridge
Or run ctrlnode-bridge with no env vars and complete the interactive wizard — it writes ~/.ctrlnode/.env.

​
Token precedence

SourceWins?
Variable already in shell ($env:PAIRING_TOKEN / export PAIRING_TOKEN)Yes — overrides file
~/.ctrlnode/.envUsed when shell is unset
Wizard promptUsed on first interactive run
If pairing fails after copying a new token, unset the shell variable and rely on the file: 
Remove-Item Env:PAIRING_TOKEN -ErrorAction SilentlyContinue

unset PAIRING_TOKEN
Avoid pasting PAIRING_TOKEN= twice in .env (some editors duplicate the prefix). The installer normalizes common mistakes; when editing by hand, use exactly one PAIRING_TOKEN=... line.

​
Verify in CtrlNode

  1. Open System → Bridge Setup — status should show Connected (green).
  2. Complete Team or setup Agent — agents should appear when registered.
  3. Dispatch a test task — it should move to In progress and stream activity.
If the footer shows Bridge offline, see Configuration and Providers for CLI prerequisites.

​
Run as a service (optional)

The Bridge is a single long-lived process. Use your platform’s service manager (systemd, Windows Task Scheduler, or a process supervisor) to restart on boot. Point the service at the same user account that owns AGENTS_FOLDER and ~/.ctrlnode/.env.

​
Next steps