Quickstart: Codex in Workcell

August 5, 2026 ยท View on GitHub

Use this guide to start Codex in the bounded Workcell runtime.

It assumes a supported Apple Silicon macOS host. GitHub-hosted CI and tagged-release install verification currently cover macos-26 and macos-15; the strongest local boundary claim still depends on local Colima validation.

Prerequisites

  • macOS
  • Apple Silicon host
  • Colima
  • Docker CLI
  • Workcell installed with ./scripts/install.sh

1. Create or update the injection policy

Workcell does not pass host provider homes to the session. Use the host auth commands to stage the reviewed auth file:

workcell auth init
workcell auth set \
  --agent codex \
  --credential codex_auth \
  --source /Users/example/.config/workcell/codex-auth.json

Optional reviewed host-auth reuse path:

workcell auth set \
  --agent codex \
  --credential codex_auth \
  --resolver codex-home-auth-file \
  --ack-host-resolver

The resolver reads the reviewed host ~/.codex/auth.json file. It stages the file through the same bundle flow. It does not pass the host home to the runtime.

2. Optional explicit prepare

A normal strict launch prepares the reviewed runtime image automatically when needed:

workcell --agent codex --workspace /path/to/repo

To prewarm without launching:

workcell --prepare-only --agent codex --workspace /path/to/repo

3. Check the derived state

workcell --agent codex --doctor --workspace /path/to/repo
workcell --agent codex --inspect --workspace /path/to/repo
workcell auth status --agent codex
workcell --agent codex --auth-status --workspace /path/to/repo

For direct staged codex_auth, expect provider_bootstrap_path=direct-staged. For the resolver-backed path, expect credential_resolution_states=codex_auth:host-source and provider_bootstrap_path=host-resolver.

4. Launch Codex

workcell --agent codex --workspace /path/to/repo

Important defaults:

  • strict is the default mode
  • yolo is the default autonomy posture
  • the injection policy at ~/.config/workcell/injection-policy.toml is used automatically if present

5. Optional lower-assurance paths

Prompt mode:

workcell --agent codex --agent-autonomy prompt --workspace /path/to/repo

Session-local writable rules:

workcell --agent codex --codex-rules-mutability session --workspace /path/to/repo

Build lane:

workcell --agent codex --mode build --workspace /path/to/repo

Managed development lane:

workcell --agent codex --mode development --workspace /path/to/repo -- bash -lc 'git status'

Breakglass:

workcell --agent codex --mode breakglass --ack-breakglass=YYYY-MM-DD --workspace /path/to/repo

6. Publish on the host

Prepare the PR metadata, then publish from the host:

./scripts/pre-merge.sh --profile pr-parity
./scripts/repo-publish-pr.sh \
  --workspace /path/to/repo \
  --branch feature/name \
  --title-file /tmp/pr-title.txt \
  --body-file /tmp/pr-body.md \
  --commit-message-file /tmp/commit-message.txt

Further reading