Codex Backend

The Codex backend lets workers execute tasks using your ChatGPT plan quota instead of paying per-token on the Anthropic API. When a task has backend: codex set, the runner routes it through OpenAI's Codex agent (backed by GPT-4o and o3) instead of Claude.

Use this when:

• Your team has an active ChatGPT Plus/Pro/Team/Enterprise plan and wants to use that quota for engineering tasks
• You want to reduce Anthropic API costs by routing some workloads through your existing OpenAI subscription
• Tasks are suitable for GPT-4o or o3 (research, code generation, analysis)

One-Time Setup

Connecting your Codex account takes about two minutes and happens entirely in the Buildd UI — no file management or server configuration needed.

1. Get your auth.json

On any machine with the Codex CLI installed, run the device-code login flow:

codex login --device-auth

Follow the prompted URL, sign in with the account that holds your ChatGPT plan, and approve the device. The CLI writes credentials to ~/.codex/auth.json. Copy the full contents of that file (it's a JSON object with access_token, refresh_token, account_id, and expires_in).

2. Paste into Settings

1. Open Buildd → Settings → Connections → Runners
2. Find your runner and click Add Credential
3. Select Codex from the provider dropdown
4. Paste the auth.json contents into the text field
5. Click Connect

Buildd stores the tokens encrypted in its database. The status indicator changes to Connected immediately.

That's it. No CODEX_HOME to configure, no files to mount. Runners receive the credential automatically at task claim time and clean it up after the task exits.

Token Refresh

Buildd refreshes your Codex tokens automatically before they expire. The refresh runs server-side using a rotation guard that prevents concurrent refresh races. If a refresh fails, the status changes to Expired and a banner appears in the runner's credential panel — paste a fresh auth.json to reconnect.

You can also trigger a manual refresh by clicking Refresh token next to the Codex credential in Settings → Connections → Runners.

Disconnecting

To remove the credential, click Disconnect next to the Codex credential in Settings → Connections → Runners. This deletes the encrypted tokens from the database immediately. Any in-flight Codex tasks will complete using the tokens they received at claim time.

Security

Buildd encrypts tokens at rest using AES-256-GCM (the same key used for all other workspace secrets). Tokens are:

• Never logged — only the workspace ID and last-refreshed timestamp appear in server logs
• Scoped to your workspace — no other workspace can access your credential, even within the same team
• Short-lived in the runner — the runner writes tokens to a temp directory (mode 0700, auth.json mode 0600) for the duration of one task, then deletes it in a finally block

You do not need to manually handle auth.json files on your runner machines.

Concurrent Execution

Codex tasks are automatically serialized — only one Codex task runs at a time per workspace. This is enforced by the runner and requires no configuration.

The limit exists because ChatGPT plans have a 5-hour rolling usage window. Running multiple tasks in parallel would exhaust the window faster without completing more work. Serializing tasks keeps throughput predictable and avoids mid-task quota failures.

If multiple Codex tasks are pending, they queue behind the active one and start as soon as it finishes.

Sandbox Modes

The Codex backend applies a sandbox policy based on task type:

The sandbox mode is chosen automatically from the task's category. You can override it by setting sandboxMode in the task's metadata if your workflow requires a different policy.

Read-only mode is appropriate for tasks that only need to inspect the codebase or external data. Workspace-write mode is required for tasks that modify files, run builds, or apply patches.