Skip to main content
Get from zero to a dispatched first task in about fifteen minutes. You need an account at app.ctrlnode.ai and a machine where you can run the open-source Bridge.

​
Overview

When step 4 succeeds, setup_completed_at is set and you land in the normal app (dashboard, Kanban, workflows).
Use in-app navigation between setup steps. Avoid hard-refreshing mid-wizard or you may see a loading screen.

​
Step 1 — Project

  • Project name and slug (auto-filled from the name)
  • Agent type — default CLI badge (Claude, Copilot, Cursor, Gemini, Codex, Hermes, OpenClaw)
  • Project work directory (optional) — full path on the Bridge machine for WORK DIRECTORY tasks
Continue to Token with ?projectId=<uuid>.

​
Step 2 — Pair the Bridge

The Bridge dials out to CtrlNode. You do not open inbound ports.

​
Install

​
Pairing token

On the token step, click GENERATE TOKEN →, copy it once, then run:
Installers set BASE_PATH (workspace parent) and write ~/.ctrlnode/.env. Run ctrlnode to start the Bridge.
More tokens: System → Bridge Setup. All providers load automatically — see Bridge configuration for BASE_PATH and API keys.
Wait until the UI shows connected, then continue.

​
Step 3 — Agent

Requires Bridge connected.
  • Name (required), optional role, model, and instructions
  • If exactly one agent is registered on the Bridge, it may auto-link

​
Step 4 — First task

  • Title and agent instructions (markdown supported)
  • MODE — OUTPUT ONLY (default) or WORK DIRECTORY (details)
  • Optional input files uploaded before dispatch
  • Submit sets status to inbox and sends work to the Bridge

​
What’s next

​
Troubleshooting

Confirm the process is running, the token is correct, and SAAS_URL matches your environment. See Bridge configuration.
Finish step 2 until connected. Regenerate a token from Bridge Setup if needed.
A value in your terminal can override ~/.ctrlnode/.env. Unset $env:PAIRING_TOKEN (Windows) or unset PAIRING_TOKEN (Unix) before starting the Bridge.