Skip to main content
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.
For non-interactive environments:
2

Create an agent profile

If agentrail init did not already create an agent, run the agent wizard:
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.
The server brings up the local API, starts provider delivery, and wakes configured Codex agents automatically. Expected output includes:
4

Load the agent env and verify

In a second terminal, load the generated agent env file and run 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.
To load connection settings manually before running:

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