Skip to main content
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.
If you are running in a non-interactive shell, provide explicit defaults:
2

Create an agent profile

If agentrail init did not already create an agent, run:
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.
Expected output includes:
4

Verify with doctor

In a second terminal, confirm that the API is reachable, credentials are valid, and assigned work is visible.
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.
For manual runs where you need to export connection settings yourself:
To pass AgentRail’s agent instructions to Claude interactively:

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

​
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.
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.
To report a progress update without finishing:
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