Codex

The CreateOS plugin for Codex teaches the agent to drive the createos CLI. There are no custom tools to learn, the plugin ships a skill that tells Codex when a sandbox is the right answer and which commands to run, and Codex uses its ordinary shell access to do it.

At a glance

Marketplace: createos
Auth: createos login, or CREATEOS_API_KEY
Shape of the integration: a skill plus the cos driver, no custom tools

Prerequisites

Install the createos CLI:

curl -sfL https://raw.githubusercontent.com/NodeOps-app/createos-cli/main/install.sh | sh -

The plugin installs it for you the first time it is needed, so this step is optional.

Then authenticate. At a terminal, sign in:

createos login

Browser sign-in needs a real terminal, so the agent cannot do it for you. For CI or headless use, set an API key instead:

export CREATEOS_API_KEY=<key>

Never paste an API key into the conversation, export it in your shell and let the CLI pick it up. cos auth reports which method is in effect.

Install

codex plugin marketplace add NodeOps-app/createos-claude-plugins
codex plugin add @createos/codex@createos

What the plugin adds

A skill. using-createos-sandbox triggers on sandbox-shaped requests, offloading a heavy build, running untrusted code, needing a disposable Linux box, setting up a multi-node cluster. It teaches the underlying CLI verbs directly: creating and removing sandboxes, running commands, moving files, opening tunnels, and managing networks and disks.

A session hook. At session start the plugin resolves the cos driver, checks it is usable, and puts its path into context along with guidance on which verb to reach for. If the driver is missing it says so rather than letting the agent improvise with raw CLI primitives and quietly lose auto-destroy and egress restriction.

The cos driver. The same execution engine the Claude Code plugin uses. It wraps the CLI with the things that are tedious to get right by hand: staging a directory, restricting egress, surviving a dropped connection on a long build, and destroying the box afterwards.

cos offload . "npm ci && npm test"     # one-shot: stage, run, pull, destroy
cos up && cos run "cargo build"        # reusable box, state persists
cos pause                              # park it at zero compute cost
cos down                               # destroy it

cos auth reports which authentication method is in effect.

Choosing a verb

Use cos offload when the work has a finish line, a build, a test run, a one-off script. The box exists for that command and is destroyed when it ends.

Use cos up and cos run when the session spans many commands and state needs to survive between them. That box persists until cos down destroys it or cos pause parks it.

Egress

Egress is unrestricted by default. Restrict it with a preset, and add individual hosts on top:

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

Presets cover python-uv, rust-cargo, npm, and github.

IP and CIDR rules apply immediately; domain rules take about 30 seconds. A domain allowlist is a strong control for HTTPS and a weak one for cleartext HTTP, when the point is to stop exfiltration, write IP or CIDR rules.

Limits

Bandwidth: 5 GiB of outbound traffic per box by default, extendable.
Clusters: up to 8 boxes.
Environment variables: declared at box creation; 64 entries, 4 KiB per value, 64 KiB total.
File transfer: the API accepts uploads up to 10 GiB. Account for CLI buffering, available memory, and transfer timeouts when moving large files.
Templates: single-stage Dockerfiles only, no COPY or ADD, 64 KiB of source, 2 concurrent builds per account.
Concurrency: your account caps how many boxes run at once and how many you can create per day.

CreateOS Sandbox is in alpha and carries no SLA.