Codex sandbox: run builds and tests in a disposable CreateOS microVM

Codex sandbox: run builds and tests in a disposable CreateOS microVM

To give Codex a disposable sandbox, add the CreateOS plugin marketplace, install createos-sandbox-codex@createos, sign in with createos login, and ask Codex to run your tests in a CreateOS sandbox. Codex then runs cos offload . "npm ci && npm test", which stages your project into a fresh box, runs the command, pulls the results back and destroys the box.

The plugin is for Codex users who want builds, tests or untrusted scripts to run in an isolated, throwaway box. CreateOS Sandbox runs each job in a Firecracker microVM with its own guest kernel, root filesystem and network identity.

Codex is OpenAI's coding agent. The CreateOS Sandbox plugin is maintained by CreateOS and is not an OpenAI product.

Key takeaways

• The plugin gives Codex a skill, two hooks and the cos driver, and no custom tools. Codex drives cos through its own shell.
• cos offload stages a directory, runs one command, pulls the results back and destroys the box.
• Each CreateOS sandbox is a Firecracker microVM with its own guest kernel, so the job is VM-isolated.
• Outbound network access is open until you set a rule. Once any rule is set, everything not on the list is dropped.

What does the CreateOS Sandbox plugin add to Codex?

The plugin adds one skill, two hooks and the cos driver. Per the Codex plugin docs:

• The skill, using-createos-sandbox, triggers on requests such as a heavy build or untrusted code, and tells Codex which commands to run.
• A session-start hook finds the cos driver, checks that it works and puts its path into context.
• A hint hook suggests a sandbox when it sees a heavy build or test. It never blocks, and COS_NO_HINT=1 turns it off.
• The cos driver wraps the createos CLI. It stages files, restricts egress, survives a dropped connection and destroys the box afterwards.

For background, read what an AI agent sandbox is.

How do I set up the CreateOS Sandbox plugin in Codex?

Four steps take you from install to a first sandboxed test run. You need Codex, a CreateOS account and a project with a command to run. Your machine also needs jq, tar, perl and curl. Without jq, the session-start hook does nothing.

The plugin installs the createos CLI when it is first needed (see Prerequisites).

Step 1: How do I add the CreateOS marketplace to Codex?

Add the marketplace before you install the plugin. The Step 2 command names a marketplace called createos and fails until it is added. Copy the exact marketplace command from the Install section of our docs.

Step 2: How do I install the plugin?

Run one command in your terminal:

codex plugin add createos-sandbox-codex@createos

Codex confirms the plugin was added. The Codex desktop app shares ~/.codex with the CLI, so one terminal install covers both.

Step 3: How do I sign in to CreateOS?

Open a terminal and run:

createos login

Browser sign-in needs a real terminal, so Codex cannot do it for you. If tmux is installed, the session-start hook starts this sign-in for you and your browser opens the CreateOS sign-in page.

In CI or anywhere headless, export CREATEOS_API_KEY instead. Never paste a key into the Codex conversation.

Step 4: How do I run my tests in a sandbox from Codex?

Start Codex in your project and ask it to run your tests in a CreateOS sandbox. For a Node project, Codex runs:

cos offload . "npm ci && npm test"

The box exists for that one command and is destroyed when it ends. Codex runs cos through its shell, so you do not type it.

Keep Codex on cos. Raw createos sandbox create, push and exec calls drop the egress restriction, the keepalive for long builds and the automatic destroy.

How do I stop a Codex sandbox from reaching the internet?

Pass an egress preset, because outbound traffic is open until you do. With no rules, a CreateOS sandbox can reach any external host. Once any rule is set, everything not listed is dropped in-kernel on the host, outside the VM (Limits and defaults).

Add a preset with -p and hosts with -e:

cos offload -p npm -e internal.example.com . "npm ci && npm test"

• Presets: npm, python-uv, rust-cargo and github.
• Timing: IP and CIDR rules apply immediately. Domain rules take about 30 seconds.
• Exfiltration: domain rules are strong for HTTPS and weak for cleartext HTTP. To stop exfiltration, use IP or CIDR rules via the Egress API.

For the threat model, read about isolation for networked untrusted code.

When should Codex keep a box instead of offloading?

Use cos up and cos run when state must survive between commands. That box persists until cos down destroys it or cos pause parks it. Use cos offload when the work has a finish line, such as a build or a test run (Choosing a verb).

What are the limits of the CreateOS Sandbox plugin for Codex?

The main limits are local projects only, the account box cap and the per-box budgets.

• Local projects only. In the Codex app, open a thread on a local project.
• No slash commands. Those belong to the Claude Code plugin.
• Box cap. Your account caps open boxes and daily creates. Paused boxes count, and a create over the cap fails rather than queueing.
• Bandwidth. 50 GiB outbound per box by default, extendable.
• Environment variables. Set at creation: 64 entries, 4 KiB per value, 64 KiB total.
• No GPUs.

When do I not need this?

If you only want to limit which files Codex edits and whether its commands reach the network, the Codex built-in sandbox does that. It applies OS-level policies (Seatbelt on macOS, bwrap and seccomp on Linux) to commands that still run on your machine. Use the plugin when a job should run in a separate, disposable VM. For the trade-off, read when a coding agent needs a microVM.

Common questions

How do I run Codex tests in an isolated microVM?

Add the CreateOS marketplace, run codex plugin add createos-sandbox-codex@createos, sign in with createos login, then ask Codex to run your tests in a CreateOS sandbox. Codex runs cos offload, which runs them in a Firecracker microVM with its own guest kernel and destroys it afterwards.

Does Codex itself run inside the CreateOS sandbox?

No. Codex keeps running where you started it. Only the commands it hands to the cos driver run in the sandbox, and each cos offload box is destroyed afterwards.

Why does codex plugin add fail for the CreateOS plugin?

The install command names a marketplace called createos, so it fails until that marketplace is added. Run the marketplace command from the Install section of the CreateOS Codex docs, then install again.

Can a CreateOS sandbox reach the internet when Codex runs a build?

Yes, by default. Egress is open until you set a rule, so add a preset such as -p npm and extra hosts with -e. Once any rule is set, everything not on the list is dropped in-kernel on the host, outside the VM.

How do I use the CreateOS plugin with Codex in CI or a headless shell?

Export CREATEOS_API_KEY in the shell instead of using browser sign-in, which needs a real terminal. Never paste the key into the Codex conversation.

How is this different from the Codex built-in sandbox?

The Codex built-in sandbox applies OS-level policies to commands that still run on your machine. The CreateOS plugin runs the job in a separate, disposable microVM with its own guest kernel.

Next step

The docs page has the marketplace command and every default. Open the CreateOS Sandbox plugin docs for Codex, then create your CreateOS account.

About CreateOS

CreateOS runs AI agents and the code they write. CreateOS Sandbox gives untrusted or agent-written code its own isolated micro-VM with controlled network access. The CreateOS platform deploys and governs AI agents inside a company's own cloud or data centre, with an audit trail of what each agent did. Start at createos.sh.