Tutorial · 5 min read

Run Codex in an isolated sandbox.

A complete, copy-pasteable walkthrough: boot a sandbox on the codex template, point it at a real repository, run a fix, and pull the diff back out — six steps, no infrastructure of your own.

01 PrerequisitesAn Ovrin API key (create one) and an OpenAI API key with Codex access. Python 3.9+ and pip install ovrin.

02 Boot a sandbox on the codex templatetemplate="codex" preinstalls the Codex CLI, git, gh, and language runtimes. Pass your OpenAI key as OPENAI_API_KEY — Codex authenticates with it directly inside the sandbox.

03 Seed the repositoryA plain git clone via sandbox.run() is enough. For a private repo, clone with a scoped token or mount an SSH deploy key as a secret.

04 Run Codex against a real taskPass a natural-language instruction the same way you would on your laptop. Output streams back over stdout as Codex reads the repo, runs the suite, and edits files.

05 Collect the resultRead git diff back over the API rather than trusting Codex's own summary — it's the ground truth for what actually changed on disk.

06 Clean upCall sandbox.kill() when you're done. There is no persistent VM to forget about and no idle bill running in the background.

Full script

All six steps, one file.

run_codex.py

import os, ovrin client = ovrin.Client(api_key=os.environ["OVRIN_API_KEY"]) # 1. boot a sandbox on the codex template sandbox = client.sandboxes.create( template="codex", env={"OPENAI_API_KEY": os.environ["OPENAI_API_KEY"]}, timeout=1800, ) # 2. seed the repo sandbox.run("git clone https://github.com/acme/api /workspace/api") # 3. run codex against a real failing test result = sandbox.run( 'cd /workspace/api && codex "find and fix the failing test in tests/test_auth.py"' ) print(result.stdout) # 4. pull the diff back out diff = sandbox.run("cd /workspace/api && git diff").stdout print(diff) # 5. tear down — filesystem is gone the instant this returns sandbox.kill()

Codex environment reference

Egress policy, template contents, and the full spec for this environment.

Coding agents at scale

Fan this same pattern out across a whole backlog of tickets.

Python SDK reference

Every method used in this tutorial, documented in full.

Try it with your own repository.

Swap the clone URL and the prompt — everything else stays the same.

Create an API key See the Codex environment

$pip install ovrin

Run Codex in an isolated sandbox.

All six steps, one file.

Where to go from here.

Try it with your own repository.