> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex on boxd

> Pre-installed. Same primitives, AGENTS.md aware.

Type `codex` from any directory on any boxd VM. The CLI is already on the image, already briefed on the environment via `AGENTS.md`, and runs against the same in-VM `boxd` CLI Claude Code uses. Same fork/sandbox patterns, same delegation flow.

## How it works

Codex ships pre-installed at image build time, so every fresh VM and every fork has it. The image also drops an `AGENTS.md` at `~/.codex/AGENTS.md` covering the boxd environment: how to create siblings with `boxd new`, manage proxies, exec across VMs, and clean up. Codex picks it up automatically from any working directory.

The in-VM `boxd` CLI is pre-authenticated. Codex can drive it the same way Claude Code does, no token or key setup.

Auth for the model itself is not yet persisted across resets, so first run on a fresh VM means signing in. Claude Code already persists auth across resets and forks ([how](/agents/claude-code#how-it-works)); the same UX is on the roadmap for Codex.

## Use it

Interactive session:

```bash theme={"theme":"github-dark"}
ssh myapp.boxd
cd my-project
codex
```

Non-interactive delegation through `boxd machine exec`:

```bash theme={"theme":"github-dark"}
boxd machine exec myvm 'codex exec "Add a /health endpoint to the Flask app"'
```

Combined with `boxd new` and `boxd machine fork`, you get the same sandbox patterns documented for Claude Code: fork before risky ops, fan out across VMs, destroy when done. See [Agent sandboxes](/agents/agent-sandboxes).

## Patterns

### Fan-out across VMs

```bash theme={"theme":"github-dark"}
for i in 1 2 3; do boxd machine new try-$i --json & done; wait

boxd machine exec try-1 'codex exec "Use FastAPI" &'
boxd machine exec try-2 'codex exec "Use Flask" &'
boxd machine exec try-3 'codex exec "Use Starlette" &'

# Results: https://try-1.boxd.sh, try-2, try-3
```

### Fork before risky ops

Snapshot a working VM before letting Codex run a migration or a destructive refactor. If the run goes wrong, destroy the fork and fork again from the parent.

```bash theme={"theme":"github-dark"}
boxd machine fork myvm myvm-migrate --json
boxd machine exec myvm-migrate 'codex exec "Apply the schema migration"'
```

### Bias with AGENTS.md

Add a project-level `AGENTS.md` in your repo. Codex merges it with the boxd-provided one, so you keep the platform context for free and bolt your conventions on top.

<Note color="#E05A6D">
  Auth doesn't persist across resets for Codex yet. Plan to sign in once per VM, or use Claude Code on boxd for the persistent-auth UX.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="Where is AGENTS.md picked up from?">
    `~/.codex/AGENTS.md` is the global file the image ships with. Any `AGENTS.md` in the repo working directory is merged on top.
  </Accordion>

  <Accordion title="Can I use Codex non-interactively for CI-style jobs?">
    Yes. `codex exec "..."` is the non-interactive form. Pair with `boxd machine exec` to run it inside a VM remotely.
  </Accordion>

  <Accordion title="Is there a Codex version of the fix-on-issue skill?">
    Not yet. The slash-command skill targets Claude Code today. Email `contact@boxd.sh` and we'll prioritize a Codex packaging.
  </Accordion>

  <Accordion title="Can Codex drive other boxd VMs?">
    Yes. The in-VM `boxd` CLI works from any agent. Codex can `boxd new` siblings, `boxd machine exec` into them, and `boxd machine remove` when done.
  </Accordion>
</AccordionGroup>

## Next

<Columns cols={2}>
  <Card title="Agent sandboxes" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/robot.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=e91e744c2d3cd5da053167486b6834bf" href="/agents/agent-sandboxes" width="16" height="16" data-path="images/icons/robot.svg">
    Give Codex its own VM. Fork to recover.
  </Card>

  <Card title="Claude Code on boxd" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/claude.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=03286da259893b6993db73a8e038c20b" href="/agents/claude-code" width="16" height="16" data-path="images/icons/claude.svg">
    Same primitives, persistent auth, ships with slash-command skills.
  </Card>
</Columns>