# Run OpenAI Codex on Maritime

Codex is OpenAI's command-line coding agent: it reads and edits files, runs commands, and works through a task on its own. Maritime gives it what a laptop session can't: its own micro-VM in the cloud that sleeps when idle and wakes on the next message, a persistent workspace, and chat from the dashboard, the CLI, the API, or Telegram. The template wraps the [Codex CLI](https://learn.chatgpt.com/docs/codex/cli) in Maritime's [bring-your-own-framework contract](/content/docs/frameworks/custom/index.html).

> **Note:** **Fastest path:** pick the **Codex** template in the dashboard (or `maritime create my-agent --template codex`) and deploy. No key is required: the agent uses Maritime's metered LLM access by default. Bring your own OpenAI key or sign in with your ChatGPT plan if you prefer (see below).

## How it fits together

- A small Node server speaks Maritime's contract: `GET /health` and `POST /chat` on `$PORT`.
- Each chat message becomes one `codex exec` run: full Codex with shell and file tools, running unattended inside the VM. Approvals and Codex's own sandbox are off because the micro-VM is the sandbox.
- The workspace, Codex's sessions, sign-in, and config all live under `/data`, so context survives restarts, redeploys, and sleep/wake.
- Each `conversation_id` resumes its own Codex thread: real memory across messages, per conversation.
- The terminal tab runs the interactive `codex` TUI against the same workspace and the same sign-in.

## Three ways to reach the model

The server picks the mode on every message, in this order:

1. **ChatGPT sign-in.** Open the agent's Terminal tab and run `codex login --device-auth`. Codex prints a link and a one-time code; finish in your browser. The sign-in is stored at `/data/.codex/auth.json` and survives redeploys. It wins over a key when both exist; `codex logout` removes it.
2. **Your own OpenAI key.** Set `OPENAI_API_KEY` in the agent's Settings under Environment variables and restart the agent. The key passes through Maritime's proxy untouched and you pay OpenAI directly.
3. **Maritime metered access (default).** With no key set, Maritime injects a per-agent proxy token. Codex talks to the proxy over the Responses API and usage is billed to your AI budget per agent. The default model here is `gpt-5.5`; set `CODEX_MODEL` to change it in any mode.

Treat `auth.json` like a password: it holds access tokens for your account. It stays on the agent's volume and is never included in a reply.

## Using the terminal

The template writes `/data/.codex/config.toml` so the interactive TUI reaches the model the same way chat does. The first line of that file is a marker; while it is there the file is regenerated at boot. Delete the marker line to keep your own edits.

```bash
# in the agent's Terminal tab
cd /data/workspace
codex                         # interactive Codex, same workspace as chat
codex login --device-auth     # sign in with your ChatGPT plan (optional)
codex login status
```

## Talk to it

```bash
maritime chat my-agent "Clone https://github.com/org/repo into the workspace and run the tests"
maritime chat my-agent "Now fix the failing test and show me the diff"
```

Or use the dashboard chat, the API, or Telegram: every channel lands on the same `POST /chat`. A task that needs more than a few seconds keeps running in the background; message the agent again and it hands you the finished answer.

## Keep in mind

- Codex runs with `--dangerously-bypass-approvals-and-sandbox`. That is deliberate: the micro-VM is the sandbox, so Codex can only change its own machine, and approval prompts would hang a headless run.
- Workspace is `/data/workspace`. Anything written elsewhere can vanish on a redeploy.
- The image pins one Codex CLI version. Newer Codex releases arrive through a new image tag, not through `codex update`.
- Want to change the server? The template lives at `backend/templates/codex` in the Maritime repo; deploy your fork with [a custom image](/content/docs/frameworks/custom/index.html).