Claude Code

The CreateOS Sandbox plugin gives Claude Code a skill and a set of slash commands that run work in disposable sandboxes. Claude keeps running on your machine; the build, the test suite, or the untrusted script runs on a throwaway Linux box that destroys itself when it finishes.

At a glance

• Marketplace: createos (from NodeOps-app/createos-claude-plugins)
• Plugin: createos-sandbox
• Commands: 18, namespaced /createos-sandbox:<verb>
• Auth: createos login, or CREATEOS_API_KEY
• Engine: the cos shell driver, which wraps the createos CLI

Prerequisites

Install the createos CLI:

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

The plugin installs the CLI for you the first time a command needs it, so this step is optional — but doing it yourself makes the first run faster and the failure modes clearer.

Then authenticate. At a terminal, sign in:

Bash
Copy
1createos login

Browser sign-in needs a real terminal, so Claude cannot run it for you — run it yourself. In CI, a devcontainer, or anywhere headless, set an API key instead:

Bash
Copy
1export CREATEOS_API_KEY=<key>

Both work equally well; the API key takes precedence when both are present. Never paste a 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

/plugin marketplace add NodeOps-app/createos-claude-plugins
/plugin install createos-sandbox@createos

Putting cos on your PATH

The driver lives inside the plugin directory and is not on your PATH by default. Slash commands resolve it for you, so this step is optional — it only matters if you want to run cos yourself:

Bash
Copy
1/path/to/createos-claude-plugins/packages/claude-code-plugin/scripts/cos install

That symlinks the driver to ~/.local/bin/cos.

Commands

One-shot work

offload is the one to reach for when the work has a finish line. It uploads the directory (large ones such as .git, node_modules, and target are excluded automatically), runs the command, and tears the box down whether the command passed or failed.

/createos-sandbox:offload . "npm ci && npm test"

Useful flags:

shell is interactive, so Claude hands it back to you to run in your own terminal rather than running it itself.

A reusable box

The box is keyed to your repository, so up is safe to run twice — the second call reuses the first box. State persists across run calls, which makes this the right shape for a dev loop where Claude edits locally and rebuilds remotely.

If a box already exists under the expected name but this machine has no record of it, up refuses to touch it unless you pass -a to adopt it. An adopted box is never destroyed by down.

Networking

tunnel keeps the service private to your machine. expose puts it on the public internet, where the URL is the only thing protecting it — there is no authentication in front of it. A service must bind 0.0.0.0 rather than 127.0.0.1 to be reachable either way.

Inside a cluster, boxes resolve each other by fully-qualified name (<box-name>.fc.local). A bare short name does not resolve.

Storage, images, and snapshots

pause keeps the box exactly as it was — installed dependencies, warm caches, running state — while you stop paying for compute. It tears down sync and tunnels first, since a paused box serves no traffic. resume brings it back.

A fork is independent: it gets its own ID and address, it survives down, and it counts against your running-box limit. Mounted disks do not carry over to a fork.

Defaults

If you ask for a shape your account cannot use, the error lists the shapes you can.

Egress presets

Egress is unrestricted unless you restrict it. -p selects a preset; -e adds individual hosts on top.

Two things to know about how the allowlist behaves. IP and CIDR rules take effect immediately; domain rules take about 30 seconds to propagate. And a domain allowlist is a strong control for HTTPS but a weak one for cleartext HTTP — when the goal is actually to prevent exfiltration, write IP or CIDR rules.

A blocked host still resolves in DNS. The connection fails at connect time, not at lookup, so expect a connection error rather than a name-resolution error.

What the plugin adds to a session

A skill. using-createos-sandbox teaches Claude when to offload — heavy builds, untrusted code, test matrices, clean-room reproductions — and how to choose between a one-shot offload and a reusable up/run box. It carries reference material on egress, networking, and image building that Claude loads on demand.

Two hooks. A SessionStart hook resolves the driver's absolute path and puts it into context, because the variable that normally points at a plugin's directory is not set inside the Bash tool's environment. A PreToolUse hook watches Bash commands and, when it recognises a heavy build or test invocation (npm ci, cargo build, pytest, make, and similar), adds a one-line suggestion to offload it. The hint never blocks the command, and COS_NO_HINT=1 turns it off.

Where state lives

Per-repository state is kept in ${XDG_CACHE_HOME:-$HOME/.cache}/createos-sandbox, keyed by a hash of your repository root. It records the active box, background sync and tunnel processes, forks, and cluster membership. Set COS_STATE_DIR to move it.

Long or quiet commands survive a dropped connection: the driver starts the command detached inside the box, watches it with a heartbeat, and reattaches if the stream breaks, so a flaky network does not cost you a build.

Limits

• Bandwidth — each box gets 5 GiB of outbound traffic by default, extendable. Exec, file transfer, and tunnels keep working after it runs out.
• Clusters — up to 8 boxes.
• Environment variables — must be declared when the box is created; 64 entries, 4 KiB per value, 64 KiB total.
• File transfer — 500 MiB per file for a single push or pull.
• Templates — one FROM, no COPY or ADD, 64 KiB of Dockerfile, 2 concurrent builds per account.
• Swap — -w is best-effort, and the default devbox:1 image cannot enable swap today. A build that runs out of memory needs a larger shape.
• Concurrency — your account has a cap on how many boxes run at once and how many you can create per day.

CreateOS Sandbox is in alpha and carries no SLA. Check limits against your own account rather than assuming these numbers.

See also

• CLI reference — the commands the driver wraps
• Concepts — sandboxes, networks, ingress, snapshots
• Bring Your Own Storage — S3 disk mounts in depth