Secure, fast Linux sandboxes for AI agents. Each sandbox is its own Firecracker microVM with its own kernel, so code you didn't write runs isolated from your machine and from everyone else's.
This repository is the server side of CreateOS Sandbox: the control plane, the host service that runs the microVMs, the agent inside every sandbox, and the tools that build sandbox images. It's written in Go and licensed under Apache-2.0.
- Hardware isolation. One microVM per sandbox. On the host, each one runs as its own unprivileged user, in its own cgroup, behind a seccomp filter.
- Fast starts. Sandboxes restore from pre-booted snapshots instead of booting a kernel. A warm pool keeps ready sandboxes waiting.
- Pause, resume, and fork. Pausing saves memory and disk to object storage. Resuming picks up where it left off, on any host. Forking clones a paused sandbox.
- Run anything. Run commands and stream their output, start long-running processes and terminals (PTYs), and upload or download files.
- Egress control. Allow only the domains and IPs a sandbox needs. Domain rules are matched on TLS SNI and HTTP Host.
- Public URLs and SSH. Expose any port at
https://<id>-<port>.<your-domain>, or forward ports withssh -L. - Private networks. Connect sandboxes to each other across hosts over an encrypted WireGuard mesh, with eBPF enforcing which sandboxes can talk.
- Templates and disks. Build sandbox images from a Dockerfile, and mount S3-compatible buckets as disks.
The quickest way to use CreateOS Sandbox is the hosted service. Get an API key at createos.sh/app/profile, then use an SDK or the CLI:
import { CreateosSandboxClient } from "@nodeops-createos/sandbox";
const client = new CreateosSandboxClient(); // reads CREATEOS_SANDBOX_API_KEY
const sandbox = await client.createSandbox({ shape: "s-1vcpu-1gb", rootfs: "devbox:1" });
try {
const { result } = await sandbox.runCommand("python3", ["-c", "print(6 * 7)"]);
console.log(result.stdout); // "42\n"
} finally {
await sandbox.destroy();
}| Client | Install | Source |
|---|---|---|
| TypeScript SDK | npm install @nodeops-createos/sandbox |
createos-typescript-sdk |
| Python SDK | pip install createos-sandbox |
createos-python-sdk |
| Go SDK | go get github.com/NodeOps-app/createos-go-sdk |
createos-go-sdk |
| Rust SDK | cargo add createos |
createos-rust-sdk |
| C# SDK | dotnet add package CreateOS.Sandbox |
createos-csharp-sdk |
| Java SDK | Maven sh.createos:createos-java-sdk |
createos-java-sdk |
| CLI | brew install nodeops-app/tap/createos |
createos-cli |
The HTTP API is described in openapi.yaml. Every other
guide, reference and integration is listed under Links.
SDK / CLI ──HTTPS──▶ control ──────────────▶ machine (one per host) ──▶ Firecracker microVM
│ API, scheduler, │ runs microVMs, egress └─ agent (PID 1)
│ gateway, ingress │ proxy, eBPF policy exec, files,
│ │ processes, PTY
├── PostgreSQL ├── WireGuard mesh to other hosts
└── object storage ◀──────┘ (snapshots, templates)
browser ──https://<id>-<port>.<domain>──▶ ingress ──▶ owning host ──▶ agent ──▶ your port
ssh -L ─────────────────────────────────▶ gateway ──▶ owning host ──▶ agent ──▶ your port
One source tree builds five binaries, picked with Go build tags:
| Binary | Runs on | Job |
|---|---|---|
control |
control plane | Public API, scheduler, SSH gateway, ingress, template builder, background workers |
machine |
every sandbox host | Runs the microVMs, their networking, and the egress proxy |
agent |
inside every sandbox | PID 1: exec, files, processes and PTYs, port tunnels. Standard library only |
image |
build machines | Turns a Docker or OCI image into a root filesystem, and builds the guest initrd |
admin |
operator laptop | Short-lived admin tasks such as issuing and revoking certificates |
Services talk to each other over mutual TLS. The control plane runs its own small certificate authority for this.
You need Go (the version in go.mod). The code targets Linux, so
set GOOS=linux when you build on another OS:
GOOS=linux CGO_ENABLED=0 go build -tags=control -o bin/control ./cmd/control
GOOS=linux CGO_ENABLED=0 go build -tags=machine -o bin/machine ./cmd/machine
GOOS=linux CGO_ENABLED=0 go build -tags=agent -o bin/agent ./cmd/agent
GOOS=linux CGO_ENABLED=0 go build -tags=image -o bin/image ./cmd/image
GOOS=linux CGO_ENABLED=0 go build -tags=admin -o bin/admin ./cmd/adminRunning the machine binary needs a Linux host with KVM (/dev/kvm).
Running sandboxes on your own hardware or cloud account is offered to
enterprise customers: see Run on your own infrastructure
or contact business@nodeops.xyz.
| Path | What's there |
|---|---|
cmd/ |
Entry points for the five binaries |
internal/apiserver/ |
Public HTTP API |
internal/scheduler/ |
Placement: picks a host for each sandbox |
internal/hosts/ |
Host service: microVM lifecycle, networking, snapshots |
internal/agent/ |
The in-sandbox agent |
internal/hosts/vm/bpf/ |
eBPF programs for network policy and bandwidth metering |
database/ |
PostgreSQL queries and migrations |
images/ |
Dockerfiles for the built-in sandbox images |
kernel-build/ |
Guest kernel config and build script |
resources/ |
Seccomp filter for Firecracker |
Docs
- Overview · Quickstart · Concepts · Security · Limits and defaults
- SDK guide: quickstart, examples, reference
- CLI: command reference
- REST API
- Bring your own storage · Run on your own infrastructure · Claude Managed Agents
- For AI tools: llms.txt
Agent and tool integrations (all integrations)
| Tool | Guide | Source |
|---|---|---|
| Claude Code | docs | createos-plugin |
| Codex | docs | createos-plugin |
| OpenCode | docs | createos-plugin |
| Pi | docs | createos-plugin |
| Herdr | docs | createos-plugin |
| Orca | docs | createos-orca-plugin |
| DeepSeek Harness | docs | createos-plugin |
| Langflow | docs | createos-plugin |
| Amp | docs | createos-cli |
| AgentBox | docs | |
| n8n | docs | |
| Omnara | docs |
More
- 40+ runnable examples: code interpreter, AI code agents, dev-server previews, browsers, MCP servers, S3 disks and more
- createos-sandbox-ghar: throwaway GitHub Actions runners, one sandbox per job
- awesome-ai-sandboxes: a list of cloud sandbox providers for AI agents
- Packages: npm · PyPI · pkg.go.dev · crates.io · NuGet
- Community: Discord · X · createos.sh
Issues are open to everyone. Pull requests are open to maintainers only. The code here is synced weekly from the maintainers' development repository, so outside pull requests can't be merged. See CONTRIBUTING.md.
Found a security problem? Don't open an issue. Report it privately as described in SECURITY.md.
Everyone taking part follows the Code of Conduct.
Apache License 2.0. The eBPF programs in
internal/hosts/vm/bpf/*.bpf.c are licensed GPL-2.0, as the Linux kernel
requires.