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 Codex using the same managed runner model as Claude Code. agentrail server start wakes Codex automatically when there is actionable work, passing it a compact task prompt and consuming the local report after Codex exits. You can also trigger a single Codex run manually for debugging.

​
Managed mode

In managed mode, you do not launch Codex directly. agentrail server start reads 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
For non-interactive environments:
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 the agent wizard:
agentrail agent create
This 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.
agentrail server start
The server brings up the local API, starts provider delivery, and wakes configured Codex agents automatically. Expected output includes:
Starting AgentRail API.
✓ AgentRail API ready at http://127.0.0.1:3000
4

Load the agent env and verify

In a second terminal, load the generated agent env file and run doctor.
source ~/.agentrail/agent.env
agentrail doctor
Do not start a coding agent until doctor passes.
In managed mode, agentrail server start handles waking Codex. You do not need to run agentrail agent run yourself unless you are debugging outside the supervisor.

​
Manual debug mode

Use this to trigger a single Codex run outside the server supervisor — useful when testing a new agent configuration or reproducing a specific task. 
cd /path/to/target-repo
agentrail agent run --agent-id agt_runner --once
To load connection settings manually before running: 
source ~/.agentrail/agent.env
cd /path/to/target-repo
codex

​
Run-scoped commands

The Codex child process receives a compact task prompt from AgentRail. If Codex needs to re-read the current assignment, it may use only these run-scoped commands: 
# Read the current assignment for this run
agentrail run current

# Read available actions for this run
agentrail run actions
These commands are scoped to the current run. They do not expose task lists or provider credentials.
Do not ask Codex 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 progress and completion

Codex reports back to AgentRail using agentrail agent report. Use --status progress for intermediate updates and --status completed with a handoff file when the work is done. 
agentrail agent report --status progress --summary "short update"
Run the smallest relevant validation (unit tests, type checks, lint) before reporting completion. Commit locally if code changed.

​
What AgentRail owns

Codex edits files, validates changes, commits locally, and reports. AgentRail owns everything else:
  • Task assignment and lifecycle state
  • CI and review observation
  • Provider PR creation, shipping, and rollback
  • Relaunching Codex only when CI or review feedback requires further code changes