Host Codex

The agent37-codex template 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:

curl

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.

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 for the terminal port:

curl

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 on the create call:

curl

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:

curl

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

Bring your own model

Codex can run against a different provider entirely: point it at any Responses-compatible endpoint with OPENAI_BASE_URL in the instance env on the create call:

curl

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

FROM ghcr.io/agent37-platform/codex-base:latest

See Build a 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 the instance to a template revision that ships Codex.

Get started

Build with Agent37

Hosting API

Agent API

Reference

Create the instance

Connect your OpenAI account

Send the first message

Models

Bring your own model

Connect apps

Custom image

Troubleshooting

​Create the instance

​Connect your OpenAI account

​Send the first message

​Models

​Bring your own model

​Connect apps

​Custom image

​Troubleshooting

Create the instance

Connect your OpenAI account

Send the first message

Models

Bring your own model

Connect apps

Custom image

Troubleshooting