> ## 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.

# Quickstart

> Sign in, create a project, pair Bridge, register an agent, and run your first task

Get from zero to a **dispatched first task** in about fifteen minutes. You need an account at [app.ctrlnode.ai](https://app.ctrlnode.ai) and a machine where you can run the open-source [Bridge](https://github.com/ctrlnode-ai/ctrlnode).

## Overview

```mermaid theme={null}
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]
```

| 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).

<Warning>
  Use in-app navigation between setup steps. Avoid hard-refreshing mid-wizard or you may see a loading screen.
</Warning>

## 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/task-work-modes) 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

<Tabs>
  <Tab title="Windows">
    ```powershell theme={null}
    irm https://github.com/ctrlnode-ai/ctrlnode/releases/latest/download/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Linux / macOS">
    ```bash theme={null}
    curl -fsSL https://github.com/ctrlnode-ai/ctrlnode/releases/latest/download/install.sh | bash
    ```
  </Tab>
</Tabs>

### Pairing token

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

<Tabs>
  <Tab title="Windows">
    ```powershell theme={null}
    $env:PAIRING_TOKEN="<paste-token>"; ctrlnode
    ```
  </Tab>

  <Tab title="Linux / macOS">
    ```bash theme={null}
    PAIRING_TOKEN=<paste-token> ctrlnode
    ```
  </Tab>
</Tabs>

Installers set **`BASE_PATH`** (workspace parent) and write `~/.ctrlnode/.env`. Run **`ctrlnode`** to start the Bridge.

<Tip>
  More tokens: **System → Bridge Setup**. All providers load automatically — see [Bridge configuration](/bridge/configuration) for `BASE_PATH` and API keys.
</Tip>

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](/tasks/task-work-modes))
* 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](/getting-started/dashboard)       |
| Day-to-day work  | [Tasks](/getting-started/tasks)               |
| Tokens in the UI | [Bridge Setup](/getting-started/bridge-setup) |
| Bridge internals | [Bridge overview](/bridge/overview)           |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bridge stays disconnected">
    Confirm the process is running, the token is correct, and `SAAS_URL` matches your environment. See [Bridge configuration](/bridge/configuration).
  </Accordion>

  <Accordion title="Agent step returns Bridge not connected">
    Finish step 2 until connected. Regenerate a token from Bridge Setup if needed.
  </Accordion>

  <Accordion title="Stale PAIRING_TOKEN in the shell">
    A value in your terminal can override `~/.ctrlnode/.env`. Unset `$env:PAIRING_TOKEN` (Windows) or `unset PAIRING_TOKEN` (Unix) before starting the Bridge.
  </Accordion>
</AccordionGroup>