Codex

The codex template supports CODEX_API_KEY or OPENAI_API_KEY.

Run Codex

Create a machine from the codex template, run Codex headlessly, and clean up. The SDK and CLI paths are equivalent — use the one that matches your workflow.

import os
from nullspace import Machine

codex_api_key = os.environ.get("CODEX_API_KEY") or os.environ["OPENAI_API_KEY"]

with Machine.create(
    template="codex",
    envs={
        "CODEX_API_KEY": codex_api_key,
        "OPENAI_API_KEY": os.environ.get("OPENAI_API_KEY", codex_api_key),
    },
    timeout=600,
) as machine:
    result = machine.commands.run(
        'codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check "Create a hello world HTTP server in Go"',
        shell=True,
        cwd="/workspace",
        timeout=600,
    )
    print(result.stdout)

nullspace machine create \
  --template codex \
  --env "CODEX_API_KEY=${CODEX_API_KEY:-${OPENAI_API_KEY:-}}" \
  --env "OPENAI_API_KEY=${OPENAI_API_KEY:-${CODEX_API_KEY:-}}" \
  --timeout 600
# machine create prints the id used below as mch_123
nullspace machine exec mch_123 \
  --cwd /workspace \
  --timeout 600 \
  --shell 'codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check "Create a hello world HTTP server in Go"'
nullspace machine kill mch_123

Interactive terminal

Open a PTY instead of a headless run to drive Codex interactively:

nullspace machine pty create mch_123 --cols 120 --rows 30
nullspace machine pty connect mch_123 --session-id ses_123
# then, inside the PTY:
codex

Use the session_id from machine pty create with --session-id.

Work on a cloned repository

import os
from nullspace import GitHttpsAuth, Machine

with Machine.create(
    template="codex",
    envs={"CODEX_API_KEY": os.environ["CODEX_API_KEY"]},
    timeout=600,
) as machine:
    machine.git.clone(
        "https://github.com/your-org/your-repo.git",
        path="/workspace/repo",
        auth=GitHttpsAuth(username="x-access-token", password=os.environ["GITHUB_TOKEN"]),
        depth=1,
    )

    machine.commands.run(
        'codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check -C /workspace/repo "Add error handling to all API endpoints"',
        shell=True,
        timeout=600,
        on_stdout=lambda data: print(data, end=""),
    )

    diff = machine.git.diff(path="/workspace/repo")
    print(diff)

Schema-validated output

schema = '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}'
machine.files.write("/workspace/schema.json", schema)

result = machine.commands.run(
    'codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --output-schema /workspace/schema.json "Summarize this repo"',
    shell=True,
    cwd="/workspace/repo",
    timeout=600,
)
print(result.stdout)

Streaming events

Use --json to emit JSONL events on stdout:

result = machine.commands.run(
    'codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --json "Find TODOs"',
    shell=True,
    cwd="/workspace/repo",
    timeout=600,
    on_stdout=lambda data: print(data, end=""),
)

Overview

Agent workspaces

Framework integrations

Local agent tooling

Run Codex

Interactive terminal

Work on a cloned repository

Schema-validated output

Streaming events

​Run Codex

​Interactive terminal

​Work on a cloned repository

​Schema-validated output

​Streaming events

​Related

Run Codex

Interactive terminal

Work on a cloned repository

Schema-validated output

Streaming events

Related