Skip to main content

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.

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

Install the CLI

Install the AgentRail CLI globally with npm:
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:
agentrail --help
2

Initialize AgentRail

Run the interactive setup wizard:
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:
agentrail init --mode server --repo /path/to/target-repo --yes
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.
3

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.
agentrail server start
Expected output:
Starting AgentRail API.
✓ AgentRail API ready at http://127.0.0.1:3000
4

Create your first agent

If agentrail init already created your first agent, skip this step.In a second terminal, run the agent creation wizard:
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:
agentrail agent update --agent-id agt_example
5

Verify setup with doctor

Run the health check:
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.
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.

​
What’s next

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

Connect providers

Add GitHub, CircleCI, or Linear credentials so AgentRail can handle real issue intake, PR submission, and CI status.

Understand task lifecycle

Learn how tasks flow from intake through routing, agent work, CI, review, and ship — and how availableActions guides each step.

Configure routing

Understand how AgentRail routes incoming issues to the right agent using rules-only or AI-assisted routing.

Installation details

Full prerequisites, Docker setup, and environment variable reference.