Skip to content

quickstart.mdx

Latest commit

 

History

History
124 lines (94 loc) · 4.02 KB

quickstart.mdx

File metadata and controls

124 lines (94 loc) · 4.02 KB
Raw
title Quickstart
description Sign in, create a project, pair Bridge, register an agent, and run your first task
icon rocket
sidebarTitle Quickstart

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

flowchart LR
  A[Sign in] --> B[Setup wizard]
  B --> C[Project]
  C --> D[Token + Bridge]
  D --> E[Agent]
  E --> F[First task]
  F --> G[Dashboard]
Loading
Step Route What you do
1 /setup/project Name the project and pick default agent type (CLI)
2 /setup/token Install Bridge, generate pairing token, wait until connected
3 /setup/agent Create your first agent (requires Bridge online)
4 /setup/task Create and dispatch a task to the agent

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

```powershell irm https://github.com/ctrlnode-ai/ctrlnode/releases/latest/download/install.ps1 | iex ``` ```bash curl -fsSL https://github.com/ctrlnode-ai/ctrlnode/releases/latest/download/install.sh | bash ```

Pairing token

On the token step, click GENERATE TOKEN →, copy it once, then run:

```powershell $env:PAIRING_TOKEN=""; ctrlnode ``` ```bash PAIRING_TOKEN= ctrlnode ```

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](/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

Goal Doc
Mission overview Dashboard
Day-to-day work Tasks
Tokens in the UI Bridge Setup
Bridge internals Bridge overview

Troubleshooting

Confirm the process is running, the token is correct, and `SAAS_URL` matches your environment. See [Bridge configuration](/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.