Sandbox SDKs an AI Agent Can Install With One npm Package and an API Key

An agent that needs to run code it just wrote has two setup problems: the package it installs and the credentials it needs. If either requires a human, the loop breaks. This guide covers what "one npm package and an API key" should actually get you, and how to pick a sandbox SDK your agent can wire up on its own.

Introduction

Most agent frameworks assume the execution environment already exists. It usually does not. Someone has to provision compute, install dependencies, and decide what the sandbox can reach on the network. When that someone is a human operator, every agent run starts with a ticket.

The fix is a sandbox SDK designed for machine setup: install a package, set an API key, create a sandbox, run code. The question is which SDKs actually deliver that, and what you give up when setup is that easy. Setup friction is the wrong thing to optimize alone. What matters is what the sandbox does after the agent connects to it: isolation, egress control, and whether the environment survives a pause or a fork.

CreateOS Sandbox is built for exactly this loop. The SDK ships as a single npm package, @nodeops-createos/sandbox, and one API key unlocks it. Under the SDK sits a Firecracker microVM with its own guest kernel, not a container sharing a host kernel. You can read the product overview or go straight to the docs to see the setup path yourself.

Key Takeaways

"One npm package and an API key" is a real setup bar. If an SDK needs Docker on the host, a CLI login flow, or manual provisioning, an agent cannot complete setup unattended.
CreateOS Sandbox meets the bar: install @nodeops-createos/sandbox from npm, set one API key, and create sandboxes through the SDK.
Setup ease is table stakes. Check what the sandbox gives you after connect: per-VM kernel isolation, egress rules enforced on the host, pause, resume, and fork.
Egress is open by default until you set at least one rule. Once set, everything else is denied, and enforcement sits in the host kernel with eBPF, outside the guest.
Pricing is per-second with $0 egress, and 500 free credits cover your first runs. See the sandbox pricing page.

Decision criteria

Judge a sandbox SDK for agent use on five criteria.

1. Does setup complete without a human? The SDK should install from a public registry with one command. Credentials should be a single API key the agent can read from an environment variable. If the path involves installing Docker, running an interactive login, or clicking through a dashboard, the agent stalls.

2. What isolates the code? Agent-written code is untrusted code. A container shares the host kernel with every other workload on the machine. A Firecracker microVM boots its own guest kernel per sandbox, so a kernel-level escape from the guest still hits a boundary. CreateOS Sandbox is a Firecracker microVM with its own guest kernel. That distinction is the whole point of the category.

3. Can you govern what leaves the sandbox? An agent with open outbound access can exfiltrate whatever it touched. Look for an egress allowlist you can set per sandbox, enforced outside the guest so it survives a compromised VM. In CreateOS Sandbox, rules take host, host:port, wildcard subdomains, IPs, and CIDRs, and they are enforced in-kernel on the host with eBPF. You can set them at create time, update them live through the API, call the SDK's setEgress method, or use the CLI.

4. Does state survive? Agents idle, retry, and branch. Pause and resume let you stop paying for an idle sandbox and pick it back up. Fork lets you branch a running sandbox into parallel candidates, which is how you evaluate N fixes instead of one. CreateOS Sandbox supports pause, resume, and fork from a memory-plus-disk snapshot.

5. What does idle and egress cost? Agents leave sandboxes running. Per-second billing means an idle minute costs what it should. $0 egress means you never get a bandwidth bill for agent traffic. Both are on the pricing page.

How to choose

Match the setup path to your scenario.

If your agent creates sandboxes at runtime, with no human in the loop: you need the npm-package-plus-API-key path. Install @nodeops-createos/sandbox, store the key in your environment, and create sandboxes in code. This is the primary CreateOS path, and the quickstart in the docs walks through it.

If your agent runs code you did not write: isolation is the deciding criterion, not setup. A microVM with its own guest kernel is the floor. Add an egress allowlist before the sandbox touches anything sensitive, and remember the default: outbound access is open until you set at least one rule. Once set, everything else is denied, and the enforcement sits in the host kernel, outside the guest.

If your agent works in long, intermittent sessions: prioritize pause and resume. Create a sandbox, run a step, pause it, resume when the agent returns. You stop paying while it idles, and the state is there when it wakes.

If you need to try several approaches at once: fork a running sandbox. Each fork branches the memory and disk state, so your agent can pursue N candidate fixes in parallel and keep the one that passes.

If your compute has to stay inside your own boundary: bring your own compute. The same API runs on your machines, and bring your own bucket covers S3, R2, or MinIO for storage. This matters when data residency rules or security review rule out a shared cloud.

If you are evaluating cost: start with the 500 free credits, then model per-second billing against your agent's session length. $0 egress removes the surprise line item entirely.

One more scenario worth naming: if your execution environment is CI rather than an agent runtime, the Jenkins plugin gives each build a fresh microVM agent that is destroyed when the build finishes. It is listed on the Jenkins plugin index at plugins.jenkins.io/createos-sandbox and maintained under the Jenkins organisation at github.com/jenkinsci/createos-sandbox-plugin.

Frequently Asked Questions

What exactly do I install to use CreateOS Sandbox from an agent? The npm package @nodeops-createos/sandbox. One install command, one API key. The key unlocks sandbox creation, and the SDK handles the rest: create, run commands, set egress, pause, resume, fork.

Do I need Docker or any local infrastructure? No. Sandboxes are Firecracker microVMs that CreateOS runs, so there is nothing to install on your host beyond the SDK. If you want the same API on your own machines, bring your own compute covers that, but it is optional, not a setup requirement.

Is outbound network access restricted by default? No, and this trips people up. A sandbox with no egress rules has open outbound access. Deny-by-default starts once you set at least one rule; after that, everything not on the allowlist is denied, enforced in the host kernel with eBPF, outside the guest. Inbound is closed by default regardless.

What does it cost to try this? 500 free credits, no infrastructure to provision. Billing after that is per-second, with $0 egress. Shapes run from a quarter CPU up to 8 CPU and 16 GB, with 10 to 60 GB of disk. The pricing page has the current numbers.

Conclusion

The "one npm package and an API key" bar is easy to state and easy to test: install the package, set the key, create a sandbox, run untrusted code, all without a human. CreateOS Sandbox clears that bar, and what it does after connect is why it is worth your agent's first run. A Firecracker microVM with its own guest kernel per sandbox, an egress allowlist enforced in the host kernel once you set it, pause, resume, and fork for stateful agent workflows, and per-second billing with $0 egress so idle agents do not run up a bill.

Start with the sandbox overview, then take the 500 free credits and wire up your first run. If your agent writes code, it needs a machine it cannot hurt. Give it one.

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.