microvm

module
v0.6.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT

README

 

AerolVM logo

Run Untrusted Code Safely.
Multi-Cloud, Self-Hosted Sandbox Infrastructure for AI Agents and Short-Lived Workloads.

Documentation · Quick Start · Report Bug · Request Feature · Sponsor

Tests Coverage Release OpenSSF Scorecard OpenSSF Best Practices

 

AerolVM is open-source sandbox infrastructure that you run yourself, on any cloud or on your own servers. Each sandbox is an isolated machine with its own files, its own network, and its own CPU and memory limits. You choose how strong the wall is for each sandbox: OCI containers on containerd (the default), gVisor, Firecracker microVMs, WASM, or V8 isolates. The fastest path creates a sandbox in about 4ms on the server.

AerolVM is one Go binary (sandboxd). It uses Caddy for HTTPS and routing and SQLite for state. It needs no outside database and installs with one command.

What the project plans to do, and not do, through October 2027 is in ROADMAP.md.

Multi-cloud and self-hosted

AerolVM runs where you run it. There is no hosted control plane you have to use, and no Aerol account is needed.

  • Any cloud. Run it on AWS, Google Cloud, Azure, DigitalOcean, Hetzner, or any other cloud. Any Linux server works. Ubuntu 22.04 or newer is the tested path.
  • Your own hardware. Run it in your data center or on bare metal. Firecracker needs KVM, so use bare metal or a VM with nested virtualization.
  • Your laptop. --local runs it on macOS or Linux with Docker. You need no domain and no cloud account.
  • No lock-in. AerolVM does not depend on any one cloud's services. You can move between clouds without changing your code. Key stores (AWS KMS, Vault, OpenBao, or an HSM) and audit sinks (S3, webhook, or file) are optional add-ons you pick.
  • Mix machines in one cluster. A hetero cluster puts each job on the hardware that suits it: small VMs for containers, bare metal for Firecracker, GPU machines for GPU work. See Architecture.
  • Your data stays with you. Sandboxes, code, secrets, and audit logs live on your machines.
  • Open source. MIT licensed, with SDKs in five languages.

Install with the script on any Linux server. For fleets, use the Ansible playbooks or the Terraform module (the Terraform module targets AWS today). Our live test suite runs on AWS.

Features

AerolVM gives you everything you need to build sandbox-backed products and agent workflows.

Sandboxes Execution Networking & Ports Storage & Secrets Platform & Cluster
Lifecycle (create / start / stop / destroy) Streaming exec & PTY HTTP public URLs External storage (S3, NFS, SSHFS, rclone) Raft-coordinated cluster
Environment & resource limits Persistent PTY sessions w/ replay TCP port exposure Encrypted sandbox secrets HA failover & durability
Images & snapshots SSH access per sandbox TLS + SNI port routing Custom domains Cluster ingress
Five runtimes (containerd / gVisor / Firecracker / WASM / Isolate) File system operations Per-sandbox egress control Sandbox tags & tenant scoping Reconciler & self-healing
GPU sandboxes MCP server & CLI for agents Per-sandbox network quotas Dashboard Operational runbooks

Architecture

The diagram shows a hetero cluster: each node has one job, and each job runs on the hardware that suits it. All nodes run the same sandboxd binary.

flowchart TB
    Users["Your apps, agents<br/>and visitors"] --> LB["One address<br/>(load balancer or DNS)"]
    LB -- "API calls and<br/>sandbox links" --> Cluster
    subgraph Cluster["AerolVM cluster: SWIM gossip and mutual TLS between all nodes"]
        direction TB
        subgraph Ingress["Ingress nodes, 2 to 10: Caddy + public route table"]
            direction LR
            I1["Ingress"] ~~~ I2["Ingress"]
        end
        subgraph Servers["Server nodes, 3 or 5: the Raft group"]
            direction LR
            S1["Server"] <-- "Raft" --> S2["Server<br/>(leader)"] <-- "Raft" --> S3["Server"]
        end
        subgraph Workers["Worker nodes: run sandboxes, keep their sealed secrets"]
            direction LR
            W1["Containers,<br/>gVisor, WASM<br/>(cloud VMs)"] ~~~ W2["Firecracker<br/>(bare metal)"] ~~~ W3["GPU sandboxes<br/>(GPU machines)"]
        end
    end
    Ingress <-- "1. which worker gets<br/>a new sandbox?<br/>where does each<br/>sandbox run?" --> Servers
    Servers <-- "2. free room on<br/>each worker,<br/>failover work" --> Workers
    Ingress -- "3. create the sandbox,<br/>then send it commands,<br/>files and web traffic" --> Workers
    subgraph Yours["Your systems (all optional)"]
        direction LR
        Keys["<b>Key store</b><br/>Vault, OpenBao,<br/>HSM or AWS KMS<br/><i>unlocks the keys<br/>to sealed secrets</i>"] ~~~ Audit["<b>Audit store</b><br/>S3 bucket or<br/>SIEM webhook<br/><i>gets hash-chained<br/>audit records</i>"] ~~~ Witness["<b>Audit witness</b><br/>S3 bucket with<br/>Object Lock<br/><i>stores audit<br/>fingerprints</i>"] ~~~ Obs["<b>Monitoring</b><br/>Prometheus, Grafana,<br/>OpenTelemetry<br/><i>gets metrics<br/>and traces</i>"]
    end
    Cluster <--> Yours

The numbers follow one new sandbox:

  1. Ingress nodes (2 to 10) take every API call and every sandbox link. For a new sandbox, the ingress node asks the server nodes which worker should run it. Ingress nodes also follow the server nodes' record of where each sandbox runs, so their public route table stays current.
  2. Server nodes (3, 5 or at most 7) form the Raft group. They keep the record of which worker runs which sandbox, and they agree on every change to it. They check how much free room each worker has, and pick a worker with room for each new sandbox. The voter count stays the same however many workers join, so adding workers does not slow down voting. They do little work, so small machines are enough.
  3. Worker nodes run the sandboxes. The ingress node sends the create to the chosen worker, then sends that worker the sandbox's commands, file calls and web traffic. Each worker reports which runtimes and GPUs it has, so a sandbox only lands on a worker that can run it. Add as many workers as you need.

Every node finds the others with SWIM gossip, protected by a shared key. Every call between nodes uses mutual TLS.

  • Secret keys. Sandbox secrets are always encrypted on disk: environment variables, registry passwords and storage credentials. Each worker keeps the sealed secrets of its sandboxes. By default, each node keeps the key in a file. You can keep it in your own key store instead: Vault, OpenBao, an HSM or AWS KMS. Each node then asks your key store to unlock the key at start, and checks again every 5 minutes. Disable the key, and every node stops using your secrets within about 15 minutes. See Secrets providers and Use your own key store.
  • Audit. Every node writes a record each time a secret is opened, an API call changes something, or a call is refused. Each record names the caller. Each record also holds a fingerprint (hash) of the one before it, so an edited or deleted record breaks the chain. Nodes ship the records to your S3 bucket or a webhook. The audit witness keeps each node's newest fingerprint in an S3 bucket with Object Lock, where no node can change it. So if someone with root on a node rewrites its log, aerolvm audit verify catches it. See Audit and compliance.
  • Failover. If a worker dies, the server nodes give its failover sandboxes to healthy workers. Each one is rebuilt with the same ID, ports, and public link. Its sealed secrets were copied to at least one backup node when it was created, so they still open on the new worker. See Durability.

You do not need a cluster to start. One server runs all three jobs on one machine. A mixed cluster of 2 to 10 alike servers gives you more room and survives a dead server. Move to a hetero cluster past 10 nodes, or when you want bare metal and GPU machines. Your code is the same in every layout. See Clusters and Reference architectures.

Inside each node, sandboxd uses three parts:

  • Caddy handles wildcard TLS via DNS-01, HTTP routing (<sandbox-id>.<domain>), and TCP SNI routing (<sandbox-id>-<port>.<domain>). The daemon drives Caddy through its admin API, so no config files are reloaded at runtime.
  • Runtimes: OCI containers (runtime: "docker" on the containerd engine by default; dockerd is optional), gVisor (runsc), Firecracker (microVM), WASM (WASI workers or a resident host), and V8 isolate (workerd).
  • SQLite (WAL mode, one writer) stores sandbox state, the TCP host-port pool, exposed-port intents, and sealed secrets. One writer means no lock fights. WAL mode means reads never block writes.

Runtimes

Runtime Status Install / enable Use case
OCI / docker API (runc via containerd) ✅ Available Default engine (SB_CONTAINER_ENGINE=containerd) Broadest OCI image compatibility.
gVisor (runsc) ✅ Available --with-gvisor User-space kernel for untrusted LLM code.
Firecracker ✅ Available --with-firecracker (bare metal / KVM) MicroVM - dedicated kernel per sandbox.
WASM ✅ Available Config / cluster wasm workers WASI modules; resident host ~22ms warm create.
Isolate (V8 / workerd) ✅ Available (off by default) --with-isolate / SB_ENABLE_ISOLATE JS/TS fetch handlers; ~4ms warm server create.

Create latency

Server-side create from Server-Timing (excludes client↔cluster WAN). Artifacts under integration-tests/reports/. Production deployments use the containerd engine for OCI sandboxes (runtime: "docker" on the wire).

Runtime / engine Server p50 Server p90 Server p99 Topology Notes
Isolate 4ms 6ms 19ms single-node-isolate · t3.medium Warm path (same tenant group); API p50 266ms is WAN
WASM (resident host) 22ms 46ms 50ms cluster-3-mixed-wasm · t3.large Flag-on resident host; no cold-compile tail
Firecracker (warm pool) 34ms 36ms 37ms single-node-fc · c5.metal Post warm-pool path; cold/template builds are higher
containerd (warm pool) 31ms 33ms 66ms cluster-mixed-benchmark-with-obs · t3.large All 10 samples came from the pool. Turn it on with SB_CONTAINERD_POOL_ENABLED=true (off by default)
containerd (OCI default, cold) 189ms 225ms 233ms cluster-3-mixed-containerd · t3.medium Default host engine, pool off; API runtime remains docker
gVisor (warm pool) 34ms 37ms 42ms cluster-mixed-benchmark-with-obs · t3.large Same containerd pool, with runsc. 8 of 10 samples came from the pool; the 2 misses were full creates and set the p90 and p99
gVisor (cold) 284ms 330ms 346ms cluster-3-mixed-gvisor · t3.medium User-space kernel boot cost, pool off

The warm-pool rows come from one 10-sample run (2026-10-04) with the pool on for alpine:3.20. Only plain creates use the pool: no environment variables, mounts, custom command, private registry or GPUs, running as root, with a warm slot ready for that image. Every other create takes the cold path.

Reproduce: make integration-benchmark-isolate, integration-benchmark-wasm, integration-benchmark-containerd, integration-benchmark-fc, integration-benchmark-gvisor, and integration-cluster-mixed-obs for the warm-pool rows.

SDKs

AerolVM ships first-party SDKs for five languages. Install the one that matches your stack:

# TypeScript / Node.js
npm install @aerol-ai/aerolvm-sdk

# Python
pip install aerolvm-sdk

# Go
go get github.com/aerol-ai/microvm/sdk/go/pkg/microvm@latest

# Rust
cargo add aerolvm-sdk

# Java: from GitHub Packages, see the SDK Setup docs
# <dependency><groupId>ai.aerol</groupId><artifactId>aerolvm-sdk</artifactId></dependency>

Quick Start

Every SDK reads the server address and token from two settings:

export SB_API_URL=http://localhost:21212
export SB_PAT_TOKEN=your-secret-pat
TypeScript
import { MicroVM } from "@aerol-ai/aerolvm-sdk";

const client = new MicroVM(); // reads SB_API_URL and SB_PAT_TOKEN

const sandbox = await client.create({ image: "python:3.12-slim" });
const result = await sandbox.exec(`python3 -c "print('Hello from AerolVM!')"`);
console.log(result.stdout);

await sandbox.destroy();
Python
from microvm import MicroVM

client = MicroVM()  # reads SB_API_URL and SB_PAT_TOKEN

sandbox = client.create(image="python:3.12-slim")
result = sandbox.exec("python3 -c \"print('Hello from AerolVM!')\"")
print(result["stdout"])

sandbox.destroy()
Go
package main

import (
    "context"
    "fmt"
    "log"

    microvm "github.com/aerol-ai/microvm/sdk/go/pkg/microvm"
    sdktypes "github.com/aerol-ai/microvm/sdk/go/pkg/types"
)

func main() {
    ctx := context.Background()

    client, err := microvm.NewClient() // reads SB_API_URL and SB_PAT_TOKEN
    if err != nil {
        log.Fatal(err)
    }

    sandbox, err := client.Create(ctx, sdktypes.CreateSandboxOptions{Image: "python:3.12-slim"})
    if err != nil {
        log.Fatal(err)
    }
    defer sandbox.Destroy(ctx)

    result, err := sandbox.ExecCommand(ctx, `python3 -c "print('Hello from AerolVM!')"`)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(result.Stdout)
}
Rust
use aerolvm_sdk::{Client, CreateOptions};

fn main() -> Result<(), aerolvm_sdk::Error> {
    let client = Client::new(None, None)?; // reads SB_API_URL and SB_PAT_TOKEN

    let sandbox = client.create(CreateOptions {
        image: "python:3.12-slim".into(),
        ..Default::default()
    })?;
    let result = sandbox.exec(r#"python3 -c "print('Hello from AerolVM!')""#)?;
    print!("{}", result.stdout);

    sandbox.destroy()?;
    Ok(())
}
Java
import ai.aerol.microvm.MicroVMClient;
import ai.aerol.microvm.Sandbox;
import ai.aerol.microvm.model.CreateOptions;
import ai.aerol.microvm.model.ExecResult;

public class Hello {
    public static void main(String[] args) {
        MicroVMClient client = new MicroVMClient(); // reads SB_API_URL and SB_PAT_TOKEN

        Sandbox sandbox = client.create(new CreateOptions().setImage("python:3.12-slim"));
        ExecResult result = sandbox.exec("python3 -c \"print('Hello from AerolVM!')\"");
        System.out.print(result.stdout);

        sandbox.destroy();
    }
}

To give a port in the sandbox a public URL, see Public URLs. More setup detail is in SDK Setup.

Drop-in SDK Compatibility

If your code already uses the e2b, Daytona, or Runloop SDK, AerolVM has API facades that accept their wire format unchanged:

Existing SDK AerolVM facade endpoint Migration
e2b Python / TypeScript /e2b/... Set E2B_API_URL=https://your-aerolvm-host
daytona Python / TypeScript /daytona/... Set DAYTONA_API_URL=https://your-aerolvm-host
Runloop Python / TypeScript /runloop/... Set RUNLOOP_BASE_URL=https://your-aerolvm-host/runloop

Using the e2b SDK → · Using the Daytona SDK → · Using the Runloop SDK →

Installation

Pick where you want to run it. The SDK code is the same in all three.

Where You need Guide
Your computer macOS or Linux with Docker Install on your computer
One server on any cloud, or your own One Ubuntu or Debian server and a domain on Cloudflare Install on a server
A cluster Several Linux servers. The step-by-step guide uses AWS with Terraform. Clusters

The installer gets HTTPS certificates through Cloudflare DNS, which is the only DNS provider it supports today. All installer flags are in Installer options.

Use Cases

Use Case Description
AI Code Execution Run LLM-generated code safely in kernel-isolated environments. Handle untrusted Python, JS, and shell from agent workflows without risking the host.
Ephemeral CI / Build Agents Spin up a fresh environment per job, run tests, collect artifacts, destroy. No persistent state, no environment drift.
Customer-Facing Products Ship interactive code runners, coding interview sandboxes, and per-user compute environments backed by AerolVM's isolation and port exposure.
Data Processing Pipelines Attach S3 or NFS storage, run transforms in parallel across sandboxes, extract results - with per-sandbox network quotas to prevent runaway egress.

Documentation

Guide Description
Quick Start Spin up a sandbox and run a command in under five minutes.
Server Setup Install AerolVM on your computer, one server, or a cluster.
SDK Setup Connect an SDK to your AerolVM server.
Sandboxes Lifecycle states, runtimes, resource limits, and configuration.
Sessions Persistent PTY sessions that survive reconnects with output replay.
Snapshots Stop a sandbox, snapshot its state, restart it later exactly where it left off.
Clusters Mixed and hetero clusters with Raft placement and SWIM gossip.
Reference architectures Single server, mixed cluster, and hetero cluster, with diagrams.
Actors and actions Who acts on a released node, and which component carries out each action.
Security assessment The most likely and most severe problems for a released node, and where the 0.6.3 review left each one.
Releasing How the maintainer publishes a release and keeps the changelog in sync.

Dependencies

A released version's dependencies are the ones recorded in the committed manifests and lockfiles. A new dependency is added only in a reviewed pull request that names the package, the version, and why it is needed. Builds obtain those dependencies with the standard tool for that language, from the lockfile, so a release does not resolve an unpinned range.

Component Recorded in Obtained with
Go daemon and Go SDK go.mod, go.sum Go modules (go build, go test)
TypeScript SDK sdk/typescript/package-lock.json npm ci
Docs site docs/package-lock.json npm ci
Release npm CLI .github/npm-cli/package-lock.json npm ci
Python SDK sdk/python/pyproject.toml, sdk/python/requirements-ci.txt pip install --require-hashes
Java SDK sdk/java/pom.xml Maven (mvn)
Rust SDK sdk/rust/Cargo.lock cargo test --locked / cargo publish

Dependabot opens a weekly pull request for Go modules, GitHub Actions, npm (the docs site and the TypeScript SDK), pip, Maven, and Cargo. Dependabot security updates are enabled on the repository. The pinned npm CLI under .github/npm-cli is outside that schedule; it changes only when its lockfile is updated in a pull request. The Go CI job also runs govulncheck against the module graph.

Access to sensitive resources

These GitHub accounts can reach the repository's sensitive resources. Registry publish tokens (npm, PyPI, Maven, crates.io) are GitHub Actions secrets. They are not in the git tree. The release workflow and the SDK publish workflow are what read them.

GitHub account Access
sumansaurabh Organization owner and repository admin. Can change branch rules, Actions secrets, security settings, and publish a release.
akanshasinha19 Write. Can push branches, open pull requests, publish a GitHub release, and dispatch the SDK publish workflow.

Merges to the default branch still require a reviewed pull request. Code owners are the review list, separate from this access list. How the project keeps creating issues, accepting changes, and publishing releases if one person is unavailable, and why the bus factor is 2, is in CONTINUITY.md.

Roles and responsibilities

How these roles make decisions is in GOVERNANCE.md.

Role Members Responsibilities
Maintainer sumansaurabh Approve pull requests. Publish official releases and the SDK packages. Change branch rules, Actions secrets, and security settings. Triage reports sent to security@aerol.ai and GitHub private advisories.
Code owner sumansaurabh, akanshasinha19 Review pull requests. A code owner other than the pull request author approves changes to the default branch.
Write collaborator akanshasinha19 Push branches and open pull requests. Official releases stay with the maintainer.
Contributor Anyone else Open issues and pull requests. No access to Actions secrets, branch rules, or release publishing.

Contributing

AerolVM is open source under the MIT License. The contributor guide states what an acceptable change must include: a reviewed pull request, a filled pull request description, tests, and no secrets in the diff. Open an issue first for a non-trivial change. Community spaces follow the code of conduct.

make fmt      # format Go code
make test     # run tests
make build    # build sandboxd + toolboxd into bin/

License

MIT · © Aerol AI, Inc.

Directories

Path Synopsis
Terraform
validate
Package validate mirrors Terraform locals.tf node-arch derivation and the homogeneous-cluster precondition so mixed-arch tfvars fail in offline tests without a live AWS plan.
Package validate mirrors Terraform locals.tf node-arch derivation and the homogeneous-cluster precondition so mixed-arch tfvars fail in offline tests without a live AWS plan.
caddymod module
cmd
aerolvm command
Command aerolvm drives AerolVM sandboxes from a terminal, a script or an AI agent: the agent-friendly CLI and, as `aerolvm mcp`, an MCP server over stdio (plans/mcp-server-and-agent-cli.md).
Command aerolvm drives AerolVM sandboxes from a terminal, a script or an AI agent: the agent-friendly CLI and, as `aerolvm mcp`, an MCP server over stdio (plans/mcp-server-and-agent-cli.md).
aerolvm-bench command
Command aerolvm-bench measures how fast an AerolVM server creates sandboxes: creates per second, and how long each create takes at p50, p90 and p99 (plans/agent-sandbox-feature-parity.md, O3).
Command aerolvm-bench measures how fast an AerolVM server creates sandboxes: creates per second, and how long each create takes at p50, p90 and p99 (plans/agent-sandbox-feature-parity.md, O3).
sandboxd command
toolboxd command
toolboxd/loginshell
Package loginshell keeps an image's PATH in the login shells toolboxd runs.
Package loginshell keeps an image's PATH in the login shells toolboxd runs.
toolboxd/sandboxenv
Package sandboxenv holds the environment a sandbox was created with, for a guest whose agent cannot inherit it.
Package sandboxenv holds the environment a sandbox was created with, for a guest whose agent cannot inherit it.
toolboxd/sessions
Package sessions implements long-running command sessions inside a sandbox container: PTY or pipes, in-memory replay buffer, fan-out to multiple attached clients, and asciinema recording.
Package sessions implements long-running command sessions inside a sandbox container: PTY or pipes, in-memory replay buffer, fan-out to multiple attached clients, and asciinema recording.
Package images holds AerolVM's ready-made sandbox images, one folder per image with a Dockerfile in it.
Package images holds AerolVM's ready-made sandbox images, one folder per image with a Dockerfile in it.
integration-tests
agenteval
Package agenteval checks that a model can actually use the aerolvm MCP tools (plans/mcp-server-and-agent-cli.md §8, eng review D13).
Package agenteval checks that a model can actually use the aerolvm MCP tools (plans/mcp-server-and-agent-cli.md §8, eng review D13).
catalogue
Package catalogue holds shared helpers for the investor benchmark catalogue artifact: cross-process atomic JSON merge (soak loops) and Pushgateway push.
Package catalogue holds shared helpers for the investor benchmark catalogue artifact: cross-process atomic JSON merge (soak loops) and Pushgateway push.
catalogue/cmd/gen command
Command gen renders reports/<scenario>-catalogue.md from catalogue JSON.
Command gen renders reports/<scenario>-catalogue.md from catalogue JSON.
cmd/audit-receiver command
audit-receiver is the off-node sink the security scenarios export to (plans/integration-test-security.md §6.4).
audit-receiver is the off-node sink the security scenarios export to (plans/integration-test-security.md §6.4).
report command
Command gen turns `go test -json` output into the use-case coverage report: a per-scenario JSON + Markdown file and an aggregate matrix.
Command gen turns `go test -json` output into the use-case coverage report: a per-scenario JSON + Markdown file and an aggregate matrix.
suite/harness
Package harness holds the scenario/capability model, the use-case registry, and the thin SDK client wrapper shared by every integration test.
Package harness holds the scenario/capability model, the use-case registry, and the thin SDK client wrapper shared by every integration test.
internal
agentmcp
Package agentmcp is the AerolVM MCP tool registry (plans/mcp-server-and- agent-cli.md §5.3).
Package agentmcp is the AerolVM MCP tool registry (plans/mcp-server-and- agent-cli.md §5.3).
agenttools
Package agenttools is the operation layer the aerolvm CLI and the aerolvm MCP server share (plans/mcp-server-and-agent-cli.md §5.1).
Package agenttools is the operation layer the aerolvm CLI and the aerolvm MCP server share (plans/mcp-server-and-agent-cli.md §5.1).
agenttools/agenttoolstest
Package agenttoolstest is an in-memory fake of the parts of sandboxd the aerolvm CLI and MCP server use: v1 sandboxes (create, get, list by name, start, destroy, ports), the toolbox file and exec endpoints, the exec WebSocket, and sessions.
Package agenttoolstest is an in-memory fake of the parts of sandboxd the aerolvm CLI and MCP server use: v1 sandboxes (create, get, list by name, start, destroy, ports), the toolbox file and exec endpoints, the exec WebSocket, and sessions.
cloudidentity
Package cloudidentity makes sandboxd an OIDC issuer for its sandboxes (plans/sandbox-cloud-identity.md).
Package cloudidentity makes sandboxd an OIDC issuer for its sandboxes (plans/sandbox-cloud-identity.md).
cluster
Package cluster implements Phase-1 cluster mode for sandboxd.
Package cluster implements Phase-1 cluster mode for sandboxd.
createpolicy
Package createpolicy loads the operator's create policy (SB_CREATE_POLICY_FILE, plans/agent-sandbox-feature-parity.md T3): which images, registries and runtimes a create may use, how big a sandbox may be, whether its image must run as a non-root user and whether it may ask for a GPU.
Package createpolicy loads the operator's create policy (SB_CREATE_POLICY_FILE, plans/agent-sandbox-feature-parity.md T3): which images, registries and runtimes a create may use, how big a sandbox may be, whether its image must run as a non-root user and whether it may ask for a GPU.
egress
Package egress is the per-node egress gateway core for hostname-filtered ("gateway-mode") sandboxes (plans/egress-domain-filtering.md §5.3).
Package egress is the per-node egress gateway core for hostname-filtered ("gateway-mode") sandboxes (plans/egress-domain-filtering.md §5.3).
egress/dnsfilter
Package dnsfilter is the egress gateway's filtering DNS resolver (plans/egress-domain-filtering.md §5.4).
Package dnsfilter is the egress gateway's filtering DNS resolver (plans/egress-domain-filtering.md §5.4).
egress/gatewayd
Package gatewayd is the `sandboxd egress-gateway` process (plans/ egress-domain-filtering.md §5.3, D9): it owns the nft table, the filtering DNS resolver and the SNI/Host proxy, and takes orders from sandboxd over a UDS.
Package gatewayd is the `sandboxd egress-gateway` process (plans/ egress-domain-filtering.md §5.3, D9): it owns the nft table, the filtering DNS resolver and the SNI/Host proxy, and takes orders from sandboxd over a UDS.
egress/inspect
Package inspect holds the egress gateway's per-node inspection CA (plans/egress-domain-filtering.md §5.9, P3-1).
Package inspect holds the egress gateway's per-node inspection CA (plans/egress-domain-filtering.md §5.9, P3-1).
egress/operator
Package operator loads the private-cloud egress operator file (plans/egress-domain-filtering.md §5.10, SB_EGRESS_OPERATOR_FILE).
Package operator loads the private-cloud egress operator file (plans/egress-domain-filtering.md §5.10, SB_EGRESS_OPERATOR_FILE).
egress/procid
Package procid traces a sandbox's TCP connection to the executables that hold it, for per-binary egress rules (plans/egress-domain-filtering.md §5.9, P3-3).
Package procid traces a sandbox's TCP connection to the executables that hold it, for per-binary egress rules (plans/egress-domain-filtering.md §5.9, P3-3).
egress/proxy
Package proxy is the egress gateway's transparent SNI/Host proxy (plans/egress-domain-filtering.md §5.5).
Package proxy is the egress gateway's transparent SNI/Host proxy (plans/egress-domain-filtering.md §5.5).
failpoint
Package failpoint lets the live integration suite stop sandboxd at one exact point in a request, so a crash can land where a real one would do the most damage instead of wherever a SIGKILL from outside happens to fall.
Package failpoint lets the live integration suite stop sandboxd at one exact point in a request, so a crash can land where a real one would do the most damage instead of wherever a SIGKILL from outside happens to fall.
identity
Package identity is sandboxd's own named-credential layer (plans/identity-and-access.md §5.4, §5.5): the server-side half of identity that the CLI never imports.
Package identity is sandboxd's own named-credential layer (plans/identity-and-access.md §5.4, §5.5): the server-side half of identity that the CLI never imports.
identity/identitytest
Package identitytest is an in-process OIDC identity provider for tests: an httptest TLS server publishing a discovery document and a JWKS, and a minting helper.
Package identitytest is an in-process OIDC identity provider for tests: an httptest TLS server publishing a discovery document and a JWKS, and a minting helper.
netsplice
Package netsplice is the raw-TCP proxy core shared by sandboxd's proxies: a bidirectional splice that replays bytes already read into a bufio.Reader, and a per-key plus global connection limiter.
Package netsplice is the raw-TCP proxy core shared by sandboxd's proxies: a bidirectional splice that replays bytes already read into a bufio.Reader, and a per-key plus global connection limiter.
network/cni
Package cni wraps the bridge+host-local CNI plugin for containerd sandboxes.
Package cni wraps the bridge+host-local CNI plugin for containerd sandboxes.
network/hostport
Package hostport forwards raw-TCP host ports in the kernel (plans/ingress-proxy-routing.md §3.5, task T7, decision "kernel DNAT").
Package hostport forwards raw-TCP host ports in the kernel (plans/ingress-proxy-routing.md §3.5, task T7, decision "kernel DNAT").
network/ipv6fence
Package ipv6fence keeps IPv6 off the node's sandbox networks.
Package ipv6fence keeps IPv6 off the node's sandbox networks.
network/netns
Package netns manages the per-host pool of prepaid network namespaces for the containerd engine.
Package netns manages the per-host pool of prepaid network namespaces for the containerd engine.
network/tap
Package tap manages the per-host pool of (TAP-device, host-IP, guest-IP, /30-CIDR, vsock-CID) slots that Firecracker microVMs claim at create time.
Package tap manages the per-host pool of (TAP-device, host-IP, guest-IP, /30-CIDR, vsock-CID) slots that Firecracker microVMs claim at create time.
pool/containerdpool
Package containerdpool is the warm-container pool for containerd sandboxes.
Package containerdpool is the warm-container pool for containerd sandboxes.
pool/dockerpool
Package dockerpool is the in-memory warm-container pool for Docker sandboxes.
Package dockerpool is the in-memory warm-container pool for Docker sandboxes.
pool/isolate
Package isolate is the blank-workerd warm pool for the V8-isolate runtime (plans/isolate-runtime.md §4 Phase 3).
Package isolate is the blank-workerd warm pool for the V8-isolate runtime (plans/isolate-runtime.md §4 Phase 3).
pool/vmm
Package vmm is the policy layer of the Firecracker warm-VMM pool described in plans/snapshot-clone-fast-boot.md Phase 4.
Package vmm is the policy layer of the Firecracker warm-VMM pool described in plans/snapshot-clone-fast-boot.md Phase 4.
pool/wasm
Package wasm is the in-memory warm-worker pool for WASM sandboxes (Phase 5).
Package wasm is the in-memory warm-worker pool for WASM sandboxes (Phase 5).
rootfstar
Package rootfstar turns a VM's root filesystem into the tar stream of a one-layer container image, and checks such a stream on its way into the image store.
Package rootfstar turns a VM's root filesystem into the tar stream of a one-layer container image, and checks such a stream on its way into the image store.
routedns
Package routedns answers "where does this sandbox hostname go?" for a static Caddy config (plans/ingress-proxy-routing.md §3.2, task T3).
Package routedns answers "where does this sandbox hostname go?" for a static Caddy config (plans/ingress-proxy-routing.md §3.2, task T3).
runtime
Package runtime defines the abstraction the service layer uses to drive a sandbox container, regardless of which OCI runtime executes it.
Package runtime defines the abstraction the service layer uses to drive a sandbox container, regardless of which OCI runtime executes it.
runtime/firecracker
Package firecracker is the native Firecracker runtime driver.
Package firecracker is the native Firecracker runtime driver.
runtime/isolate
Package isolate is the V8-isolate (Workers-model) runtime driver — the fifth implementation of internal/runtime.Runtime, after pkg/docker (docker + gvisor), internal/runtime/firecracker, and internal/runtime/wasm (plans/isolate-runtime.md).
Package isolate is the V8-isolate (Workers-model) runtime driver — the fifth implementation of internal/runtime.Runtime, after pkg/docker (docker + gvisor), internal/runtime/firecracker, and internal/runtime/wasm (plans/isolate-runtime.md).
runtime/resolvconf
Package resolvconf builds the resolv.conf a sandbox gets: the host's upstream resolvers, without loopback stubs the sandbox can't reach.
Package resolvconf builds the resolv.conf a sandbox gets: the host's upstream resolvers, without loopback stubs the sandbox can't reach.
runtime/wasm
Package wasm is the WASM/WASI runtime driver — the third implementation of internal/runtime.Runtime (after pkg/docker and internal/runtime/firecracker).
Package wasm is the WASM/WASI runtime driver — the third implementation of internal/runtime.Runtime (after pkg/docker and internal/runtime/firecracker).
runtime/wasm/statekv
Package statekv implements the host KV capability for durable WASM sandboxes (plans/wasm-runtime.md §4.6).
Package statekv implements the host KV capability for durable WASM sandboxes (plans/wasm-runtime.md §4.6).
runtime/wasm/toolhost
Package toolhost implements the host-side toolbox for WASM sandboxes (plans/wasm-runtime.md §3).
Package toolhost implements the host-side toolbox for WASM sandboxes (plans/wasm-runtime.md §3).
safetar
Package safetar unpacks a tar archive (gzip is detected) into one folder without letting any entry write outside it.
Package safetar unpacks a tar archive (gzip is detected) into one folder without letting any entry write outside it.
operator module
pkg
api
Package api wires the top-level HTTP server.
Package api wires the top-level HTTP server.
api/apihttp
Package apihttp holds HTTP helpers shared by every version of the public API (pkg/api/v1, ...).
Package apihttp holds HTTP helpers shared by every version of the public API (pkg/api/v1, ...).
api/clusterlist
Package clusterlist aggregates sandbox list reads across cluster owners.
Package clusterlist aggregates sandbox list reads across cluster owners.
api/clusterroute
Package clusterroute holds the one cluster owner-forwarding wrapper every API surface shares.
Package clusterroute holds the one cluster owner-forwarding wrapper every API surface shares.
api/ingressproxy
Package ingressproxy implements the loopback HTTP listener that fronts wake-aware Caddy port routes.
Package ingressproxy implements the loopback HTTP listener that fronts wake-aware Caddy port routes.
api/remotemcp
Package remotemcp serves the AerolVM MCP tools over Streamable HTTP at /mcp on sandboxd (plans/mcp-server-and-agent-cli.md §5.7, Phase 2b).
Package remotemcp serves the AerolVM MCP tools over Streamable HTTP at /mcp on sandboxd (plans/mcp-server-and-agent-cli.md §5.7, Phase 2b).
api/runloop
Package runloop is a compatibility facade for the official Runloop SDKs (@runloop/api-client, runloop_api_client).
Package runloop is a compatibility facade for the official Runloop SDKs (@runloop/api-client, runloop_api_client).
api/v1
Package v1 implements the v1 HTTP API for the sandbox daemon.
Package v1 implements the v1 HTTP API for the sandbox daemon.
auditexport
Package auditexport ships already-redacted, hash-chained audit records off-node through pluggable backends.
Package auditexport ships already-redacted, hash-chained audit records off-node through pluggable backends.
auditwitness
Package auditwitness supplies an off-node audit witness to the open-source build: a controlplane.Witness that writes each audit hash-chain head to an S3 bucket with Object Lock, so the node that wrote a head can never change or remove it (plans/open-audit-witness.md).
Package auditwitness supplies an off-node audit witness to the open-source build: a controlplane.Witness that writes each audit hash-chain head to an S3 bucket with Object Lock, so the node that wrote a head can never change or remove it (plans/open-audit-witness.md).
auditwitness/s3fake
Package s3fake is an in-memory S3 server for tests.
Package s3fake is an in-memory S3 server for tests.
capacity
Package capacity implements admission control for sandbox creation.
Package capacity implements admission control for sandbox creation.
clonegen
Package clonegen publishes a monotonic "clone generation" token readers can poll to detect that a sandbox was resumed from a snapshot — i.e.
Package clonegen publishes a monotonic "clone generation" token readers can poll to detect that a sandbox was resumed from a snapshot — i.e.
controlplane
Package controlplane is the neutral seam between sandboxd and an optional managed control plane.
Package controlplane is the neutral seam between sandboxd and an optional managed control plane.
createtiming
Package createtiming carries a per-request create-latency recorder on the request context so runtime drivers can attribute where a sandbox create spent its time, and the API handler can surface that attribution as Server-Timing response entries.
Package createtiming carries a per-request create-latency recorder on the request context so runtime drivers can attribute where a sandbox create spent its time, and the API handler can surface that attribution as Server-Timing response entries.
daemon
Package daemon holds the full sandboxd boot sequence as a single reusable entrypoint, Run.
Package daemon holds the full sandboxd boot sequence as a single reusable entrypoint, Run.
docker/netstats
Package netstats reads per-sandbox network byte counters from /proc/<pid>/net/dev.
Package netstats reads per-sandbox network byte counters from /proc/<pid>/net/dev.
egresspolicy
Package egresspolicy is the one grammar, matcher and enforcement toolkit for sandbox egress policy (plans/egress-domain-filtering.md §5.1, §5.6).
Package egresspolicy is the one grammar, matcher and enforcement toolkit for sandbox egress policy (plans/egress-domain-filtering.md §5.1, §5.6).
firecracker
Package firecracker is a thin Go wrapper around the Firecracker VMM's HTTP-over-Unix-socket REST API.
Package firecracker is a thin Go wrapper around the Firecracker VMM's HTTP-over-Unix-socket REST API.
gvisorpids
Package gvisorpids caps how many tasks (processes and threads) a gVisor sandbox may run, inside the sandbox's own kernel (the runsc sentry).
Package gvisorpids caps how many tasks (processes and threads) a gVisor sandbox may run, inside the sandbox's own kernel (the runsc sentry).
identitywire
Package identitywire holds the identity formats that sandboxd and the aerolvm CLI must agree on byte for byte (plans/identity-and-access.md, eng review D2): the avm_ API token format with its checksum, the names and lifetimes a token request carries, the sign-in discovery document (GET /.well-known/aerolvm-auth) the CLI and the dashboard read before they hold any credential, the team-selection header, and the answer of `whoami --explain`.
Package identitywire holds the identity formats that sandboxd and the aerolvm CLI must agree on byte for byte (plans/identity-and-access.md, eng review D2): the avm_ API token format with its checksum, the names and lifetimes a token request carries, the sign-in discovery document (GET /.well-known/aerolvm-auth) the CLI and the dashboard read before they hold any credential, the team-selection header, and the answer of `whoami --explain`.
isolate
Package isolate is the workerd engine wrapper for the V8-isolate runtime (plans/isolate-runtime.md §7, the analog of pkg/wasm for WASM).
Package isolate is the workerd engine wrapper for the V8-isolate runtime (plans/isolate-runtime.md §7, the analog of pkg/wasm for WASM).
jsbundle
Package jsbundle resolves and stores the JS/TS bundles that back runtime=isolate sandboxes (plans/isolate-runtime.md §7, the analog of pkg/wasmmod for .wasm modules).
Package jsbundle resolves and stores the JS/TS bundles that back runtime=isolate sandboxes (plans/isolate-runtime.md §7, the analog of pkg/wasmmod for .wasm modules).
mounts
Package mounts owns the host-side lifecycle of per-sandbox external-storage mounts.
Package mounts owns the host-side lifecycle of per-sandbox external-storage mounts.
mounts/adapters
Package adapters describes how to invoke external mount tools on the host for each supported storage protocol.
Package adapters describes how to invoke external mount tools on the host for each supported storage protocol.
oci
Package oci builds an ext4 root filesystem image from an OCI container reference.
Package oci builds an ext4 root filesystem image from an OCI container reference.
readyproto
Package readyproto defines the newline-delimited JSON handshake toolboxd sends to sandboxd when a Docker sandbox's agent is ready to serve.
Package readyproto defines the newline-delimited JSON handshake toolboxd sends to sandboxd when a Docker sandbox's agent is ready to serve.
sandboxtoken
Package sandboxtoken is the signed, scoped per-sandbox token (plans/agent-sandbox-feature-parity.md §5.9, A1): a credential an owner can hand to a browser or an end user that works for one sandbox only, optionally narrowed to one port, one path prefix and a set of methods, and that expires.
Package sandboxtoken is the signed, scoped per-sandbox token (plans/agent-sandbox-feature-parity.md §5.9, A1): a credential an owner can hand to a browser or an end user that works for one sandbox only, optionally narrowed to one port, one path prefix and a set of methods, and that expires.
toolboxhttp
Package toolboxhttp is the HTTP transport sandboxd uses to reach a sandbox's toolbox over the network.
Package toolboxhttp is the HTTP transport sandboxd uses to reach a sandbox's toolbox over the network.
volumes
Package volumes translates a named, tenant-scoped platform volume into a concrete mount the existing pkg/mounts pipeline already knows how to realize.
Package volumes translates a named, tenant-scoped platform volume into a concrete mount the existing pkg/mounts pipeline already knows how to realize.
wasm
Snapshot artifact layout and validation per plans/wasm-runtime.md §4.8.1.
Snapshot artifact layout and validation per plans/wasm-runtime.md §4.8.1.
wasm/worker
Package worker implements the WASM worker-subprocess pool (plans/wasm-runtime.md §2.1).
Package worker implements the WASM worker-subprocess pool (plans/wasm-runtime.md §2.1).
wasmmod
Package wasmmod — AOCR push for §4.8.1 WASM snapshot artifacts (D2).
Package wasmmod — AOCR push for §4.8.1 WASM snapshot artifacts (D2).
scripts
load command
ingress_churn is a release-gate load harness for the AerolVM cluster data-plane ingress.
ingress_churn is a release-gate load harness for the AerolVM cluster data-plane ingress.
sdk
go/internal/apiclient/v1
Package v1 holds wire-version-1 constants for the Go SDK.
Package v1 holds wire-version-1 constants for the Go SDK.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL