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

# Use AgentRail with OpenAI Codex as your coding agent

> Run Codex as a managed AgentRail agent or trigger single debug runs. Covers environment setup, run-scoped commands, and progress and completion reporting.

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.

<Steps>
  <Step title="Initialize AgentRail">
    Run the interactive setup to create local config and your first agent profile.

    ```bash theme={null}
    agentrail init
    ```

    For non-interactive environments:

    ```bash theme={null}
    agentrail init --mode server --repo /path/to/target-repo --yes
    ```
  </Step>

  <Step title="Create an agent profile">
    If `agentrail init` did not already create an agent, run the agent wizard:

    ```bash theme={null}
    agentrail agent create
    ```

    This creates scoped agent credentials, writes the managed agent env file, and configures starter routing for your repo.
  </Step>

  <Step title="Start the server">
    Keep this running in a dedicated terminal.

    ```bash theme={null}
    agentrail server start
    ```

    The server brings up the local API, starts provider delivery, and wakes configured Codex agents automatically. Expected output includes:

    ```text theme={null}
    Starting AgentRail API.
    ✓ AgentRail API ready at http://127.0.0.1:3000
    ```
  </Step>

  <Step title="Load the agent env and verify">
    In a second terminal, load the generated agent env file and run doctor.

    ```bash theme={null}
    source ~/.agentrail/agent.env
    agentrail doctor
    ```

    Do not start a coding agent until `doctor` passes.
  </Step>
</Steps>

<Note>
  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.
</Note>

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

```bash theme={null}
cd /path/to/target-repo
agentrail agent run --agent-id agt_runner --once
```

To load connection settings manually before running:

```bash theme={null}
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:

```bash theme={null}
# 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.

<Warning>
  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.
</Warning>

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

<CodeGroup>
  ```bash Progress update theme={null}
  agentrail agent report --status progress --summary "short update"
  ```

  ```bash Completion report theme={null}
  agentrail agent report \
    --status completed \
    --summary "short completion summary" \
    --handoff-file "$AGENTRAIL_HANDOFF_PATH"
  ```
</CodeGroup>

<Tip>
  Run the smallest relevant validation (unit tests, type checks, lint) before reporting completion. Commit locally if code changed.
</Tip>

## 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