Skip to content

About

Firecracker microVM sandboxes for AI agents: the open-source core of CreateOS Sandbox

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

49 stars

Watchers

0 watching

Forks

CreateOS Sandbox

License: Apache-2.0 Go Docs

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.

What you get

  • 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 with ssh -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.

Use it

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.

How it fits together

 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.

Build from source

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/admin

Running 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.

Repository layout

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

Links

Docs

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

Contributing

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.

License

Apache License 2.0. The eBPF programs in internal/hosts/vm/bpf/*.bpf.c are licensed GPL-2.0, as the Linux kernel requires.

About

Firecracker microVM sandboxes for AI agents: the open-source core of CreateOS Sandbox

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

49 stars

Watchers

0 watching

Forks

Used by

Contributors

Languages