Deploy Codex on Cloud - BoxLite Documentation

Codex runs inside the box with access to its files and shell. Submit a task directly through boxlite exec. Complete the workstation setup. Run all commands below on your workstation.

Create the box and install Codex

Save create.py. Before running it, replace <YOUR_MODEL_HOST> with your model endpoint’s hostname, without the scheme or path. The prompt reads the real model key on your workstation; only BoxLite’s Secret configuration receives it.

create.py

import asyncio
from getpass import getpass
import boxlite

async def main():
    runtime = boxlite.Boxlite.rest(boxlite.BoxliteRestOptions.from_env())
    try:
        box = await runtime.create(
            boxlite.BoxOptions(
                image="node",
                cpus=1, memory_mib=2048, disk_size_gb=10,
                auto_stop=0, auto_delete=0, detach=True,
                env=[
                    ("SSL_CERT_FILE", "/etc/ssl/certs/ca-certificates.crt"),
                    ("CODEX_API_KEY", "<BOXLITE_SECRET:openai>"),
                ],
                secrets=[boxlite.Secret(
                    name="openai",
                    value=getpass("Model provider API key: "),
                    hosts=["<YOUR_MODEL_HOST>"],
                )],
            ),
            name="codex-agent",
        )
        print(box.id)
        await box.start()
    except Exception as exc:
        raise SystemExit(f"{type(exc).__name__}: inspect codex-agent before retrying creation.") from None
    finally:
        runtime.close()

asyncio.run(main())

python3 create.py

Install the agent:

boxlite exec codex-agent -- \
  npm install -g --prefix /workspace/tools @openai/codex
boxlite exec codex-agent -- mkdir -p /workspace/codex

The node image includes glibc and system CA certificates, which the native Codex binary needs.

Connect your model

Use an existing Responses-compatible endpoint that supports tool calls. Set Secret.hosts in create.py to its hostname. Save this native Codex configuration as config.toml, replacing the API base URL and model ID:

config.toml

model = "<MODEL_ID>"
model_provider = "endpoint"

[model_providers.endpoint]
name = "Model endpoint"
base_url = "https://<YOUR_MODEL_HOST>/v1"
wire_api = "responses"
env_key = "CODEX_API_KEY"

Keep the Secret placeholder unchanged. The real provider key stays outside the box. Upload the configuration:

boxlite cp config.toml codex-agent:/workspace/codex/config.toml

Run a task

boxlite exec -e CODEX_HOME=/workspace/codex -w /workspace codex-agent -- sh -c '
  exec /workspace/tools/bin/codex exec --skip-git-repo-check \
    --dangerously-bypass-approvals-and-sandbox --json \
    "Run this exact shell command with your terminal tool: echo CODEX_READY > /workspace/proof.txt && cat /workspace/proof.txt" < /dev/null
'
boxlite exec codex-agent -- cat /workspace/proof.txt
# CODEX_READY

Codex’s internal sandbox and approval prompts are disabled for this trusted task inside the Cloud box. Its files, local service credentials, and allowed network remain accessible to the agent. Codex is ready. Check for turn.failed events and verify the file before treating a task as successful.

Optional: wake on a request

This walkthrough creates a separate codex-http box with an authenticated POST /tasks endpoint. After two idle minutes, the box stops. Sending another task to the same URL starts the box and runs Codex again. Run every command below on your workstation, in one directory. You will create two source files and a local caller token. The token’s hash goes into the box; the real model key stays in BoxLite’s Secret.

1. Create the HTTP box

Save this as create-http.py. Its startup command waits for the files installed in step 3, then starts the service on every boot.

create-http.py

import asyncio
from getpass import getpass
import boxlite

async def main():
    runtime = boxlite.Boxlite.rest(boxlite.BoxliteRestOptions.from_env())
    try:
        box = await runtime.create(
            boxlite.BoxOptions(
                image="node",
                cpus=1, memory_mib=2048, disk_size_gb=10,
                auto_stop=120, auto_resume=True, auto_delete=0, detach=True,
                network=boxlite.NetworkSpec(inbound=boxlite.InboundNetworkSpec(mode="enabled")),
                entrypoint=["/bin/sh", "-c"],
                cmd=["""
until test -x /workspace/tools/bin/codex && test -s /workspace/codex/config.toml &&
      test -s /workspace/server.mjs && test -s /workspace/http-token.sha256; do sleep 1; done
exec node /workspace/server.mjs >> /workspace/http.log 2>&1
"""],
                env=[
                    ("SSL_CERT_FILE", "/etc/ssl/certs/ca-certificates.crt"),
                    ("CODEX_API_KEY", "<BOXLITE_SECRET:openai>"),
                ],
                secrets=[boxlite.Secret(
                    name="openai",
                    value=getpass("Model provider API key: "),
                    hosts=["<YOUR_MODEL_HOST>"],
                )],
            ),
            name="codex-http",
        )
        print(box.id)
        await box.start()
    except Exception as exc:
        raise SystemExit(f"{type(exc).__name__}: inspect codex-http before retrying creation.") from None
    finally:
        runtime.close()

asyncio.run(main())

python3 create-http.py

Use auto_stop=0 instead if you want this HTTP service to stay running. Keep the value shown to try automatic stop and wake. Use the same model endpoint and Secret settings as the CLI deployment above.

2. Save the HTTP service

Save the complete code below as server.mjs. The service accepts {"prompt":"..."}, runs one Codex task at a time with a three-minute limit, and returns Codex’s JSON result. POST /tasks is this example’s application API.

server.mjs — complete source

server.mjs

import http from 'node:http';
import { readFileSync } from 'node:fs';
import { createHash, timingSafeEqual } from 'node:crypto';
import { execFile } from 'node:child_process';

const tokenHash = Buffer.from(readFileSync('/workspace/http-token.sha256', 'utf8').trim(), 'hex');
if (tokenHash.length !== 32) throw new Error('Invalid HTTP token hash');
let busy = false;

function reply(res, status, body) {
  res.writeHead(status, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(body));
}

const server = http.createServer(async (req, res) => {
  const authorization = req.headers.authorization ?? '';
  const token = authorization.slice(7);
  const suppliedHash = createHash('sha256').update(token).digest();
  if (!authorization.startsWith('Bearer ') || !timingSafeEqual(suppliedHash, tokenHash)) {
    return reply(res, 401, { error: 'Unauthorized' });
  }
  if (req.method === 'GET' && req.url === '/health') {
    return reply(res, 200, { ready: true, busy });
  }
  if (req.method !== 'POST' || req.url !== '/tasks') {
    return reply(res, 404, { error: 'Use POST /tasks' });
  }

  let prompt;
  try {
    req.setEncoding('utf8');
    let body = '';
    for await (const chunk of req) {
      body += chunk;
      if (Buffer.byteLength(body) > 65536) {
        return reply(res, 413, { error: 'Request too large' });
      }
    }
    ({ prompt } = JSON.parse(body));
    if (typeof prompt !== 'string' || !prompt.trim()) throw new Error('Invalid prompt');
  } catch {
    return reply(res, 400, { error: 'Send JSON with a nonempty prompt string' });
  }
  if (busy) return reply(res, 409, { error: 'A task is already running' });
  busy = true;

  const abort = new AbortController();
  res.on('close', () => { if (!res.writableEnded) abort.abort(); });
  const child = execFile('/workspace/tools/bin/codex', [
    'exec', '--skip-git-repo-check', '--dangerously-bypass-approvals-and-sandbox', '--json', prompt,
  ], {
    env: { ...process.env, CODEX_HOME: '/workspace/codex' },
    cwd: '/workspace', detached: true, timeout: 180000, killSignal: 'SIGKILL',
    maxBuffer: 2 * 1024 * 1024, signal: abort.signal,
  }, (error, stdout) => {
    busy = false;
    if (error && child.pid) {
      try { process.kill(-child.pid, 'SIGKILL'); } catch {}
    }
    if (res.destroyed) return;
    try {
      const events = stdout.trim().split('\n').filter(Boolean).map(line => JSON.parse(line));
      const failed = Boolean(error) || events.some(event => event.type === 'turn.failed');
      return reply(res, failed ? 502 : 200, { ok: !failed, events });
    } catch {
      return reply(res, error?.killed ? 504 : 502, { error: 'Codex did not return a result' });
    }
  });
  child.stdin.end();
});

server.requestTimeout = 30000;
server.listen(8080, '0.0.0.0');

Only give the caller token to clients allowed to run tasks in this box. Tasks have access to the files and network available to this box.

3. Install and start the service

Generate the caller token and its hash locally:

python3 - <<'PYTOKEN'
import hashlib
import os
import secrets
from pathlib import Path

os.umask(0o077)
token = secrets.token_hex(32)
Path("http-token").write_text(token)
Path("http-token.sha256").write_text(hashlib.sha256(token.encode()).hexdigest())
PYTOKEN

Keep http-token on your workstation and out of Git. Keep config.toml from the model setup above. Install Codex, upload the model configuration, service and token hash, then register port 8080:

boxlite exec codex-http -- \
  npm install -g --prefix /workspace/tools @openai/codex
boxlite exec codex-http -- mkdir -p /workspace/codex
boxlite cp config.toml codex-http:/workspace/codex/config.toml
boxlite cp server.mjs codex-http:/workspace/server.mjs
boxlite cp http-token.sha256 codex-http:/workspace/http-token.sha256
boxlite exec codex-http -- chmod 600 /workspace/http-token.sha256
boxlite network tunnel codex-http 8080

The saved startup command starts the service as soon as these files exist. It starts it again after every wake; no attached terminal is required.

4. Send the first task

Set CODEX_URL to the HTTPS URL returned by the last command. Keep this shell open for the wake-up check.

CODEX_URL='<YOUR_TUNNEL_URL>'
curl --fail-with-body --max-time 30 "$CODEX_URL/health" \
  -H "Authorization: Bearer $(cat http-token)"
# {"ready":true,"busy":false}

If the service is still starting, retry this health request after a few seconds. Then ask Codex to create a file:

curl --fail-with-body --max-time 240 "$CODEX_URL/tasks" \
  -H "Authorization: Bearer $(cat http-token)" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Run this exact shell command with your terminal tool: echo CODEX_HTTP_READY > /workspace/proof.txt && cat /workspace/proof.txt"}'
boxlite exec codex-http -- cat /workspace/proof.txt
# CODEX_HTTP_READY

Success means the response contains "ok": true and the independent file check prints CODEX_HTTP_READY.

5. Wait for automatic stop

Stop sending HTTP requests, including health checks. Run only this control-plane check until Status is stopped:

boxlite inspect codex-http

Allow two idle minutes. Do not use start, exec, or cp before the next request: the HTTP request should be the action that wakes the box.

6. Wake Codex with another task

Send a new task to the same URL:

curl --fail-with-body --max-time 240 "$CODEX_URL/tasks" \
  -H "Authorization: Bearer $(cat http-token)" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Run this exact shell command with your terminal tool: echo CODEX_HTTP_AWAKE > /workspace/awake.txt && cat /workspace/awake.txt"}'

Cloud starts the box; its saved command starts the HTTP service, which runs Codex. After the response, check both files:

boxlite exec codex-http -- cat /workspace/proof.txt /workspace/awake.txt
# CODEX_HTTP_READY
# CODEX_HTTP_AWAKE

The first file checks retained work; the second checks that Codex ran tools after wake. Leave the box idle again and it stops automatically. The file checks verify real tool execution and retained work across a stop and wake. If Cloud returns 503 BOX_STARTING, wait for Retry-After before retrying. The service returns 401 for a wrong caller token and 409 while another task is running. A timed-out request can have partial effects: inspect its output before resubmitting it.

7. Clean up the HTTP box

boxlite rm --force codex-http

For applications that already use Cloud exec, the CLI command above also supports wake on access; this HTTP service is optional.

When you are finished

boxlite stop codex-agent
# To delete the box and its files:
boxlite rm --force codex-agent

​Create the box and install Codex

​Connect your model

​Run a task

​Optional: wake on a request

​1. Create the HTTP box

​2. Save the HTTP service

​3. Install and start the service

​4. Send the first task

​5. Wait for automatic stop

​6. Wake Codex with another task

​7. Clean up the HTTP box

​When you are finished