Codex in Run9

Run Codex in a box when you want the agent, repo, tools, and generated files inside one forkable run9 environment. This works well when you want to prepare one baseline once, then open parallel task boxes that all start from the same repo and toolchain.

Prepare the box

⌘Copysys9 run box create codex-lab --image docker.io/library/node:22-bookworm
sys9 run box exec codex-lab -it bash

Inside that shell:

⌘Copy# inside the shell:
apt-get update
apt-get install -y git
npm install -g @openai/codex
mkdir -p /work
git clone <your-repo-url> /work/your-repo
ls /work/your-repo
exit

Replace <your-repo-url> with the repo URL you actually use. For the smoothest first setup, start with the HTTPS URL for that repo. If the repo is private, or you prefer an SSH repo URL, prepare the Git credential you need inside codex-lab first. Product SSH only gets you into the box: it does not forward your laptop SSH agent, and the Profile / SSH Keys entry only authenticates box login.

If git clone succeeds and ls /work/your-repo shows your files, later task boxes will inherit that checkout path.

Treat codex-lab as the reusable baseline box. Put your repo, language toolchain, and project dependencies here before you fork, so later task boxes all start from the same prepared state.

That baseline is what lets you Fork & Scale naturally: one snap can become codex-fix-login, codex-write-tests, codex-upgrade-sdk, or any other isolated task branch you need.

Configure OpenAI

Before starting Codex, create a Project Secret in the project that owns your box:

⌘Copyprintf '%s' "$REAL_OPENAI_API_KEY" | sys9 run project secrets create \
  --name openai \
  --value-file - \
  --allowed-host api.openai.com \
  --header-name Authorization

Copy the generated Placeholder; you will use it as OPENAI_API_KEY inside the box. You can also create the same rule in Portal from Project Settings -> Secrets. To keep the rule limited to one task box, use sys9 run box secrets create <box-id> or create it from that box’s Secrets tab.

Project Secrets only run on boxes with Network = Managed. Create the Codex task box with --network managed, or choose Managed in Portal before starting the Codex exec.

Fork a task box from the prepared baseline

When codex-lab has the repo and tools you want every task to inherit, freeze that state and branch from it:

⌘Copysys9 run box stop codex-lab
sys9 run snap fork --from-box codex-lab
sys9 run box create codex-fix-login --snap <forked-snap-id> --network managed
sys9 run box create codex-write-tests --snap <forked-snap-id> --network managed
sys9 run box create codex-repro-bug --snap <forked-snap-id> --network managed

Keep codex-lab as the reusable baseline. Use codex-fix-login for the real Codex session below so later forks still start from the clean prepared state.

Start Codex with a Project Secret

⌘Copysys9 run box exec codex-fix-login -it bash

Then move into the repo checkout you prepared in codex-lab before you start Codex.

Inside that shell:

⌘Copy# inside the shell:
cd /work/your-repo
export OPENAI_API_KEY=<project-secret-placeholder>
codex

Replace /work/your-repo with the path you prepared in codex-lab. Start Codex from that checkout so the task session opens on the inherited repo instead of the shell’s default directory.

The OPENAI_API_KEY export is shell-local, so re-export it in each new shell unless you save it in the shell profile you use for Codex.

Inside the box, Codex still talks to the normal OpenAI endpoint. The placeholder only appears in the Authorization header; run9 replaces it with the real Project Secret when the request leaves the managed box for api.openai.com.

If Codex fails before the first prompt, check the box is Managed, the Project Secret allows api.openai.com, and this shell still has OPENAI_API_KEY=<project-secret-placeholder>.

codex-fix-login starts with Codex, Git, and anything else you prepared in the parent box. Create more boxes from the same snap when you want parallel Codex task branches.