Guide

Run OpenAI Codex on RunBerth

Codex is OpenAI's command-line coding agent: it reads and edits files, runs commands, and works through a task on its own. RunBerth 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 in RunBerth's bring-your-own-framework contract.

Fastest path: pick the Codex template in the dashboard (or runberth create my-agent --template codex) and deploy. No key is required: the agent uses RunBerth'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 RunBerth'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 RunBerth's proxy untouched and you pay OpenAI directly.
  3. RunBerth metered access (default). With no key set, RunBerth 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.

# 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

runberth chat my-agent "Clone https://github.com/org/repo into the workspace and run the tests"
runberth 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 RunBerth repo; deploy your fork with a custom image.