> ## Documentation Index
> Fetch the complete documentation index at: https://agentrail.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Get AgentRail Running in Under Five Minutes

> Install the CLI, run agentrail init, start the local API, create your first agent, and confirm setup with agentrail doctor — all in five minutes.

This guide gets a working local AgentRail instance up and verified on your machine. By the end, `agentrail doctor` will pass, which means the local API is reachable, your agent credentials are valid, routing state exists, and the agent can see assigned work. That is the baseline you need before pointing any coding agent at AgentRail.

<Note>
  You need Node.js 24 or newer and `npm`. Run `node --version` to check. Provider credentials (GitHub token, CircleCI token, Linear API key) are optional — you can add them after setup.
</Note>

<Steps>
  <Step title="Install the CLI">
    Install the AgentRail CLI globally with npm:

    ```bash theme={null}
    npm install -g @agentrail-core/cli
    ```

    If you prefer not to install globally, you can prefix any command with `npx @agentrail-core/cli` instead of `agentrail`.

    Verify the install:

    ```bash theme={null}
    agentrail --help
    ```
  </Step>

  <Step title="Initialize AgentRail">
    Run the interactive setup wizard:

    ```bash theme={null}
    agentrail init
    ```

    `agentrail init` writes local setup state under `~/.agentrail`, creates a local operator bootstrap for your machine, and can create your first agent profile and agent env file in the same flow. Accept the prompt to create the first agent if you want the shortest path to a passing doctor check.

    If you are running in a non-interactive shell, provide explicit defaults:

    ```bash theme={null}
    agentrail init --mode server --repo /path/to/target-repo --yes
    ```

    <Tip>
      During `init`, you will be asked to choose a routing mode. **Rules-only** routing is deterministic and based on labels, type, or repo metadata. **AI-assisted routing** uses a local runner such as Codex or Claude Code to classify issues. Start with rules-only if you are not sure.
    </Tip>
  </Step>

  <Step title="Start the local API">
    Keep this running in one terminal. The server starts the AgentRail API, activates provider delivery for any configured webhooks or polling, and keeps managed local agents alive.

    ```bash theme={null}
    agentrail server start
    ```

    Expected output:

    ```text theme={null}
    Starting AgentRail API.
    ✓ AgentRail API ready at http://127.0.0.1:3000
    ```
  </Step>

  <Step title="Create your first agent">
    If `agentrail init` already created your first agent, skip this step.

    In a second terminal, run the agent creation wizard:

    ```bash theme={null}
    agentrail agent create
    ```

    The wizard creates scoped local agent credentials, writes the managed agent env file, creates or updates the agent profile, and can configure starter routing for your selected repo.

    You can update an agent later with:

    ```bash theme={null}
    agentrail agent update --agent-id agt_example
    ```
  </Step>

  <Step title="Verify setup with doctor">
    Run the health check:

    ```bash theme={null}
    agentrail doctor
    ```

    A passing doctor check means all of the following are true:

    * The local API is reachable.
    * The current agent env file is usable.
    * The agent profile is active.
    * Routing state exists for the current repo.
    * The agent can see assigned work via `/tasks/mine?status=in_progress&limit=1`.

    <Warning>
      Do not treat setup as complete until `agentrail doctor` passes. If it fails, fix the reported issue before pointing a coding agent at AgentRail. The output tells you exactly which check failed.
    </Warning>
  </Step>
</Steps>

## What's next

You now have a running local AgentRail instance. Here are the most common next steps:

<CardGroup cols={2}>
  <Card title="Connect providers" icon="plug" href="/docs/concepts/providers">
    Add GitHub, CircleCI, or Linear credentials so AgentRail can handle real issue intake, PR submission, and CI status.
  </Card>

  <Card title="Understand task lifecycle" icon="arrow-right" href="/docs/concepts/task-lifecycle">
    Learn how tasks flow from intake through routing, agent work, CI, review, and ship — and how `availableActions` guides each step.
  </Card>

  <Card title="Configure routing" icon="git-branch" href="/docs/concepts/routing">
    Understand how AgentRail routes incoming issues to the right agent using rules-only or AI-assisted routing.
  </Card>

  <Card title="Installation details" icon="download" href="/docs/installation">
    Full prerequisites, Docker setup, and environment variable reference.
  </Card>
</CardGroup>