Get Started
AI AGENT TUTORIAL

Codex in Run9

Run Codex CLI inside a box and route OpenAI traffic through the org AI Gateway.

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

run9 box create codex-lab --image docker.io/library/node:22-bookworm
run9 box exec codex-lab -it bash

Inside that shell:

# 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 in Portal

Before starting Codex, configure the org-level gateway:

  1. Open Portal.
  2. If you are on My Orgs, click Settings on the org that owns codex-lab.
  3. If you are already inside that org workspace, use the left sidebar Org Settings.
  4. Open AI Integrations.
  5. Open the OpenAI card.
  6. Paste your real provider secret into Upstream API Key.
  7. Leave Custom Endpoint empty unless you intentionally want a custom upstream.
  8. Turn Enabled on.
  9. Click Save.

If you are not an org owner, ask an owner to do this once for the org.

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:

run9 box stop codex-lab
run9 snap fork --from-box codex-lab
run9 box create codex-fix-login --snap <forked-snap-id>
run9 box create codex-write-tests --snap <forked-snap-id>
run9 box create codex-repro-bug --snap <forked-snap-id>

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 through AI Gateway

run9 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:

# inside the shell:
cd /work/your-repo
mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
openai_base_url = "http://10.0.2.2:1000/run9/ai/openai/v1/"
EOF

export OPENAI_API_KEY=run9-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.

~/.codex/config.toml stays in the box file system, so later shells can reuse the gateway base URL. The OPENAI_API_KEY export is still 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, the only OpenAI-specific settings are the gateway base URL and the placeholder key. The literal run9-placeholder is only a client-side stand-in, and the org gateway keeps the real upstream secret outside the box.

If Codex fails before the first prompt, check the org OpenAI card is still Enabled, then confirm this shell still uses the gateway URL and OPENAI_API_KEY=run9-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.