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

# Host Codex

> Run OpenAI's Codex on its own always-on instance, signed in to your own OpenAI account.

The `agent37-codex` [template](/docs/agents-api/templates) runs Codex, OpenAI's coding agent, on an Agent37 instance: an always-on computer with the same chat API, sessions, files, and URLs as every other template. The image is lean, with no browser and no desktop. Codex runs on **your own OpenAI account**: Agent37 never supplies or bills OpenAI model usage, and there is no managed-model option on this template, so connect your account before the first chat turn.

## Create the instance

One call to the hosting API at `https://api.agent37.com`:

```bash curl theme={null}
curl -X POST https://api.agent37.com/v1/instances \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "template": "agent37-codex" }'
```

The `201` response carries the instance id and its URL, `https://{instanceId}.agent37.app`, which routes to the gateway on port `3737`. The terminal is on port `7681` and the file browser on `8080`, each at `https://{instanceId}-{port}.agent37.app`; see [Instance and preview URLs](/docs/agents-api/urls).

## Connect your OpenAI account

Two ways to connect. Until one of them is done, a chat turn fails with `auth_error`, and `GET /v1/health?agent=codex` on the instance URL reports `"healthy": false`.

**Log in from the instance terminal.** Mint a [signed URL](/docs/agents-api/urls#browser-access-with-signed-urls) for the terminal port:

```bash curl theme={null}
curl -X POST https://api.agent37.com/v1/instances/ab12cd34ef/signed-url \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "port": 7681 }'
```

Open the returned `url` in a browser and run `codex login --device-auth` in the shell. It prints a URL and a one-time code: open the URL, enter the code, and approve with your ChatGPT account. The login persists on the instance volume, so it survives restarts and updates. Starting a device login logs out any API-key login on the instance, so use one method per instance.

**Set `OPENAI_API_KEY`.** The way to go when your app provisions instances headlessly. Pass your OpenAI API key (as `OPENAI_API_KEY`, or `CODEX_API_KEY`) as [instance env](/docs/agents-api/instances#environment-variables) on the create call:

```bash curl theme={null}
curl -X POST https://api.agent37.com/v1/instances \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "template": "agent37-codex", "env": { "OPENAI_API_KEY": "..." } }'
```

The image runs `codex login --with-api-key` at boot to activate the key; a bare environment variable on its own does not authenticate.

## Send the first message

Chat is the instance URL plus a path, with the same `sk_live_` key sent as the `X-Agent37-Key` header. `codex` is the template's default agent, so there is no `agent` field to pass:

```bash curl theme={null}
curl https://ab12cd34ef.agent37.app/v1/responses \
  -H "X-Agent37-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "input": "Clone github.com/expressjs/express and summarize how routing works." }'
```

Set `"stream": true` to receive the turn as Server-Sent Events instead of one JSON body, and reuse the returned `session_id` to continue the thread. Codex mints its own session ids, so start a thread by omitting `session_id`; you cannot bring an unknown id on the first turn. See [Send a message](/docs/agents-api/chat) and [Streaming](/docs/agents-api/streaming).

## Models

`GET /v1/models?agent=codex` on the instance lists Codex's own live model catalog, the `gpt-5.x` family. Pass an id as `model` on a turn, and set `reasoning_effort` per turn; `ultra` maps to Codex's multi-agent mode. Usage bills to your OpenAI account, not your Agent37 wallet. See [Models](/docs/agents-api/models).

## Bring your own model

Codex can run against a different provider entirely: point it at any [Responses](https://platform.openai.com/docs/api-reference/responses)-compatible endpoint with `OPENAI_BASE_URL` in the instance `env` on the create call:

```bash curl theme={null}
curl -X POST https://api.agent37.com/v1/instances \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template": "agent37-codex",
    "env": {
      "OPENAI_BASE_URL": "https://your-endpoint.example.com/v1",
      "OPENAI_API_KEY": "<your key>"
    }
  }'
```

No OpenAI account is needed: model usage bills the key behind the endpoint you point `OPENAI_BASE_URL` at, and health reports healthy once the instance is up. Codex is built for OpenAI models; pointing it at another family can mishandle the tool calls it edits files with.

## Connect apps

[App integrations](/docs/agents-api/integrations) work here like on every system template: drive the `/v1/integrations` endpoints to connect your users' Gmail, Slack, Notion, and hundreds of other apps, and the platform registers its Composio MCP server with Codex automatically (in `~/.codex/config.toml`).

## Custom image

To add your own tools, build on the clean base image, which ships Codex and the gateway with no managed integrations, the same pattern as `hermes-base`:

```dockerfile theme={null}
FROM ghcr.io/agent37-platform/codex-base:latest
```

See [Build a custom image](/docs/agents-api/custom-image).

## Troubleshooting

| Symptom                                                                                                | Fix                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A turn fails with `auth_error`                                                                         | No OpenAI account is connected yet: connect one of the two ways above. The `hint` tells the user to run `codex login --device-auth` or set `OPENAI_API_KEY`.                                                                                                                                               |
| `GET /v1/health?agent=codex` reports `"healthy": false`                                                | Same cause: the harness reports unhealthy until an account is connected. `ok: true` alone only means the gateway is up.                                                                                                                                                                                    |
| A first turn on a `session_id` you chose is rejected with `400 validation_error` (`param: session_id`) | Codex mints its own session ids: a client cannot bring an unknown `session_id` on the first turn. Omit it to start a thread, then reuse the id the response returns. Sessions you start in the terminal appear in `GET /v1/sessions?agent=codex` on their own.                                             |
| A turn returns `503 agent_unavailable`                                                                 | The Codex binary is not present on this instance, so a turn that has to create or resolve a session cannot run. Unlike Hermes (which returns `200` with `status: "failed"`), Codex answers `503`. Recreate or [update](/docs/agents-api/instances#update) the instance to a template revision that ships Codex. |