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.

AgentRail integrates with Claude Code in two modes: a managed local runner where agentrail server start wakes Claude Code automatically whenever there is actionable work, and a manual debug mode where you trigger a single run yourself. In both modes, Claude Code edits code in the target repository while AgentRail owns task assignment, CI observation, review tracking, PR creation, and lifecycle state.

​
Managed mode

In managed mode you never launch Claude Code directly. agentrail server start reads managed agent env files from ~/.agentrail/agents/, starts an event-driven agentrail agent run loop for each configured local agent, and restarts those loops when they exit.
1

Initialize AgentRail

Run the interactive setup to create local config and your first agent profile.
agentrail init
If you are running in a non-interactive shell, provide explicit defaults:
agentrail init --mode server --repo /path/to/target-repo --yes
2

Create an agent profile

If agentrail init did not already create an agent, run:
agentrail agent create
The wizard creates scoped agent credentials, writes the managed agent env file, and configures starter routing for your repo.
3

Start the server

Keep this running in a dedicated terminal. The server brings up the local API, starts provider delivery, and wakes configured agents automatically.
agentrail server start
Expected output includes:
Starting AgentRail API.
✓ AgentRail API ready at http://127.0.0.1:3000
4

Verify with doctor

In a second terminal, confirm that the API is reachable, credentials are valid, and assigned work is visible.
agentrail doctor
Do not start a coding agent until doctor passes.
You do not need to run agentrail agent run yourself in managed mode. Reserve it for manual debugging or one-off validation.

​
Manual debug mode

Use this when you want to trigger a single Claude Code run outside the server supervisor — for example, to test a new agent configuration or reproduce a specific task. 
cd /path/to/target-repo
agentrail agent run --agent-id agt_runner --once
For manual runs where you need to export connection settings yourself: 
cd /path/to/target-repo
export AGENTRAIL_BASE_URL=http://127.0.0.1:3000
export AGENTRAIL_API_KEY=ar_live_replace_with_real_key
To pass AgentRail’s agent instructions to Claude interactively: 
claude --append-system-prompt-file /path/to/agentrail/docs/agent-recipes.md

​
Environment variables

AgentRail injects the following variables into the managed runner environment. Claude Code can read these at runtime — it should not attempt to discover them through other means.
VariableDescription
AGENTRAIL_RUN_REPORT_PATHPath to the local report file AgentRail reads after the child process exits.
AGENTRAIL_HANDOFF_PATHPath to the structured handoff file Claude should write before reporting completion.
AGENTRAIL_RUN_CONTEXT_PATHPath to the current run context snapshot.
AGENTRAIL_TASK_IDThe task ID AgentRail already selected before starting Claude.
AGENTRAIL_TASK_IDENTIFIERThe human-readable task identifier (for example, ENG-123).

​
Run-scoped commands

Claude Code running as a managed child process should use only these run-scoped commands. They are scoped to the current run and do not expose task lists or provider credentials. 
# Inspect the current assignment
agentrail run current

# Inspect available actions for this run
agentrail run actions
Do not ask Claude to call broad AgentRail task, CI, review, ship, rollback, provider, or operator endpoints from inside the child process. Those routes are for external harnesses, not managed child agents.

​
Reporting completion

When Claude finishes its work, it must write the handoff file and report back to AgentRail before exiting. 
agentrail agent report \
  --status completed \
  --summary "short completion summary" \
  --handoff-file "$AGENTRAIL_HANDOFF_PATH"
To report a progress update without finishing: 
agentrail agent report --status progress --summary "short update"
Use --status completed with a handoff file when work is done. Use --status progress for intermediate updates during long-running tasks.
Run the smallest relevant validation (unit tests, type checks, lint) before reporting completion. AgentRail uses the handoff file contents when deciding the next lifecycle action.

​
What AgentRail owns

Claude Code edits files and reports back. Everything else belongs to AgentRail:
  • Task assignment and lifecycle state
  • CI and review observation
  • Provider PR creation, shipping, and rollback
  • Relaunching Claude only when CI or review feedback requires further code changes