English | 简体中文

Kuasar Sandbox

Kuasar Sandbox is a production-ready MicroVM sandbox platform for AI agents, serverless workloads, and reinforcement-learning environments.

It provides independent guest-kernel isolation, snapshot-template instantiation, stateful pause and resume, on-demand data loading, high-density resource governance, and a deployment path from a single node to a multi-node cluster.

The Stable channel resolves to the current non-prerelease aggregate; select that Release once and pin its exact tag, assets, and checksums for an installation. Preview releases remain available for development and evaluation. Production readiness describes the system's deployment and operational capabilities; the Stable/Preview label describes the stability of a public release channel. Production deployments should still validate capacity against their own workloads and configure production TLS, durable storage, network policy, and credentials.

Start here

• Quick Start — download one aggregate release, verify it, and run a real MicroVM through the unmodified E2B SDK;
• Workbench:recommended environment for first use, native builds and private system validation;
• Architecture — system capabilities, component boundaries, and lifecycle semantics;
• Deployment — standalone and cluster topologies, processes, and dependencies;
• Releases — component versions, aggregate versions, asset contracts, and release transactions;
• Demo — the complete local demonstration environment;
• Full validation — aggregate-release validation and all owner E2E suites;
• Security — supported versions and private vulnerability reporting;
• Contributing — project-repository contribution rules and the organization-wide guide.

Why MicroVM sandboxes

Agent workloads may execute model-generated commands, user-provided programs, third-party repositories, downloaded tools, and temporary dependencies. The platform therefore cannot assume that code running inside a sandbox is trusted.

Kuasar Sandbox uses KVM MicroVMs as the compute boundary. Each sandbox has its own guest kernel, while the host exposes only controlled lifecycle, storage, networking, and execution interfaces. The platform keeps the security boundary of a virtual machine while specializing the surrounding system for short-lived, highly concurrent, and stateful agent workloads.

Core capabilities

• Independent kernel isolation — each sandbox runs with its own guest kernel behind a KVM MicroVM boundary.
• Snapshot-template instantiation — build and initialize an environment once, then create multiple independent instances from the same read-only parent state.
• Stateful pause and resume — preserve the memory, processes, and filesystem changes of one logical sandbox and resume it later, potentially on another node when its artifacts are portable.
• On-demand loading — memory pages and disk blocks are loaded when the workload actually accesses them, so startup and restore costs follow the working set rather than the full logical image size.
• Flexible data paths — images, snapshots, and sparse artifacts can use local files, shared filesystems such as NAS/NFS, or Manifest-backed object storage with tiered caches.
• High-density resource governance — idle CPU and inactive memory can be returned to the node pool, while admission, dynamic budgets, watermarks, active reclaim, and safety reserves protect concurrently active work.
• Sandbox-level networking — the network layer allocates and releases connectivity quickly, forwards in the kernel, isolates sandboxes by default, and supplies trusted sandbox identity to external policy gateways.
• Multi-tenant security — platform identity, scoped data-plane capabilities, content-protection keys, network identity, and node resource budgets remain separate security boundaries.
• E2B-compatible entry point — an unmodified E2B SDK can create, execute, pause, reconnect to, and terminate sandboxes.
• Standalone and cluster deployment — the same components can run on one node or be assembled into a Registry/Router/Placer multi-node control plane.

Snapshot lifecycle

Kuasar Sandbox exposes one snapshot infrastructure through two user-facing workflows:

Create instances from a snapshot template (1:N)

A template can contain an initialized operating system, language runtime, dependencies, tools, and warmed services. Multiple new sandboxes share its immutable parent state while keeping independent identity and writable changes.

Pause and resume one logical instance (1:1)

A running sandbox can be paused with its process, memory, and filesystem state preserved. Reconnecting to the same stable sandbox identity resumes that logical instance. This supports long-running agents, human approval steps, idle sessions, node maintenance, and migration.

These workflows use explicit parent/child snapshot relationships. Storage efficiency comes first from sharing the known parent layer and recording only instance-specific changes; it does not depend on independently running virtual machines accidentally producing highly identical memory snapshots.

Data and storage model

Kuasar Sandbox does not require every artifact to use one storage backend:

accelerator provides the common data capabilities behind these choices: sparse-data representation, local artifacts, integrity and encryption, references, Manifest organization, filesystem and S3-compatible stores, caches, OCI retrieval, EROFS image flattening, fetch, and prefetch. Content addressing and deduplication are available where they fit the data and security domain; they are not the only storage model and are not assumed to be effective for every independently captured VM snapshot.

High-density resource governance

Agent sandbox load is highly non-linear: sandboxes often spend most of their lifetime waiting for a model, a tool, external I/O, or human input, then become active in short bursts.

Kuasar Sandbox treats density as an outcome of safe resource utilization:

1. idle sandboxes release CPU and inactive memory;
2. long-idle sandboxes can be paused into durable state;
3. reclaimed capacity returns to the node-wide pool;
4. node admission, dynamic grants, watermarks, active reclaim, and safety reserves protect simultaneous bursts;
5. platform-level sharing must not turn node pressure into sandbox OOMs or lost valid work within the declared resource model.

The sandboxer runtime executes per-sandbox cgroup, balloon, and VMM lifecycle actions. The node-ctl reservation controller owns node-wide admission, resource-pool accounting, grants, inventory reconciliation, and recovery. High density therefore means maximizing useful node utilization without using OOM as a scheduling mechanism, not merely maximizing a raw VM count.

For a synthetic sparse coding-Agent workload, the 2026-10-08 matched BMS experiment completed all 48 agents on each architecture: fixed three-concurrent versus Kuasar sixteen-concurrent took 851s versus 380s on x86_64, and 802s versus 333s on ARM64 (outer case wall time including setup and cleanup). Plans disabled business retries and each Agent had one observed business start; one HTTP polling error in the x86 dynamic run did not prevent correct completion. This is a fixed-concurrency Kuasar baseline, not a separate static memory manager. Hardware was 8C16G with a 12GiB node pool, 1C4G sandbox capacity, 256MiB allocatable and 512MiB startup. Results are workload-specific, not universal capacity guarantees. See performance methodology and Agent evidence checker.

Networking and policy integration

connector provides a high-density eBPF/TC data path for MicroVM networking. It creates and releases sandbox network resources quickly, keeps sandbox-to-sandbox forwarding absent by default, validates platform-assigned network identity, and forwards established traffic without requiring a user-space process on every packet.

Deployments can carry trusted sandbox identity to a centralized external policy gateway, where sandbox-level public-network, private-network, DNS, proxy, audit, and traffic-governance policy can be enforced. A node-local lightweight Egress plane is tracked as a proposed extension; it is not presented as an already delivered part of the base vSwitch.

Architecture

Agent / E2B SDK / Platform API
                │
           orchestrator
                │
        sandboxer runtime
        ├── accelerator
        ├── connector
        └── guest-runtime
                │
KVM / Local Files / NAS / Object Storage / Network

kuasar-sandbox/kuasar-sandbox is the canonical project repository. It owns the system-level design, shared CI infrastructure, cross-component validation, demos, aggregate version selection, and aggregate releases.

The implementation is maintained in five loosely coupled component repositories:

The five components form the complete platform together, but each component can evolve, build, deploy, and release independently. guest-runtime produces two release units, Runtime and VMLinux, while remaining one component repository.

Release status and support scope

• Stable channel: the GitHub Latest non-prerelease aggregate; resolve it once and retain its exact tag for every asset and checksum in one installation.
• Preview channel: GitHub prereleases for development and evaluation; Preview does not replace the current Stable release.
• Prebuilt architecture: new aggregate releases provide native Linux x86_64 and aarch64 assets; historical releases retain their declared architecture set.
• Source-build architectures: the Makefiles support TARGET_ARCH=x86_64 and TARGET_ARCH=aarch64; workbench supplies the native toolchain for either architecture.
• Version relationship: components release independently; an aggregate release selects exact component versions and validates the combined system on real KVM infrastructure.

Stable means a non-prerelease aggregate release. Preview means a prerelease aggregate release for development and evaluation. Proposed means a design or issue that must not be treated as delivered functionality.

See GitHub Releases for the authoritative asset list and prerelease state.

Continue from the Demo to your own application,
minimal cluster client acceptance,
production qualification and recovery,
independent storage roundtrip,
and gateway acceptance.

Quick Start

For first use, prefer the matching release and workbench; the host needs no product
libraries or Demo SDK. The Demo tears down its node services at completion.
Use --pause inside the same workbench for interactive exploration; container
localhost addresses and temporary credentials do not configure a host SDK. See
Quick Start and Demo.

The Quick Start downloads every explicit asset from one aggregate release, verifies SHA256SUMS, prepares a standalone node, and builds a ready snapshot template with the upstream E2B Python SDK. The Demo reads its published template ID from the exact build's ready status; the SDK's registration handle is not that ID. With the node running and the documented SDK connection settings in place, set TEMPLATE_ID to that published ID for the lifecycle below:

import os
from e2b import Sandbox

sandbox = Sandbox.create(os.environ["TEMPLATE_ID"], timeout=300)
sandbox_id = sandbox.sandbox_id
print(sandbox.commands.run("uname -sm").stdout)
sandbox.pause()
sandbox = Sandbox.connect(sandbox_id)  # reconnect and auto-resume
print(sandbox.commands.run("echo resumed").stdout)
sandbox.kill()

For the complete local environment, template fan-out, network access, and migration flow, see the Demo.

Source workspace

The standard development workspace places the project repository and five component repositories next to one another:

<workspace>/
├── kuasar-sandbox/
├── accelerator/
├── connector/
├── sandboxer/
├── guest-runtime/
└── orchestrator/

The project repository contains:

docs/              System design, deployment, performance, CI, and release documents
test/e2e/          Shared runner, flat suite cases and prepared-input helpers
test/perf|demo/    Platform performance and demonstration scripts
ci/integration/    CI helpers and source-cache maintenance
ci/native-cache/   VMLinux, EROFS, Envd, RocksDB, and Cloud Hypervisor cache support
ci/runner/         Self-hosted CI runner deployment
release/           Version resolution, packaging, aggregation, and publishing
releases/          Stable and daily Preview aggregate selections
.github/workflows/ Reusable CI, aggregate-release, and daily-Preview workflows

Build and test

Builds use environment-provided Go and inherit its GOROOT and GOTOOLCHAIN selection. Release automation requires a working gh on PATH; the project does not install, replace, or authenticate these environment tools against fixed binary digests. EROFS tools remain built from the project-selected sources, patches, and recipes.

A complete source build is driven from this project repository and consumes the five sibling component repositories:

make -C kuasar-sandbox build
make -C kuasar-sandbox test
make -C kuasar-sandbox test-e2e RELEASE_DIR=/release E2E_WORKDIR=/tmp/kuasar-prepared
make -C kuasar-sandbox perf E2E_WORKDIR=/absolute/path/to/prepared-inputs
make -C kuasar-sandbox demo PYTHON_BIN=/absolute/path/to/pinned-venv/bin/python

Runtime files are collected into bin/<arch>/ according to release/inputs/bin-inputs.yaml. Each component also supports its documented standalone build. For example:

GOWORK=off make -C sandboxer build

Product E2E consumes prebuilt products through test/e2e/e2e prepare and run. Full <suite>.<case>.sh filenames identify cases across nine suites; component ownership only determines where source cases are maintained. Preparation acquires immutable images and the pinned Demo SDK; execution uses prepared products, helpers and images without source discovery, compilation or automatic pulls. Unit/race/vet, UFFD and performance gates stay independent. See test organization and the release validation guide.

Release-tool tests do not contact GitHub or build the real native dependencies:

make -C kuasar-sandbox test-release-tools
make -C kuasar-sandbox test-ci-tools
make -C kuasar-sandbox test-perf-tools

Tests requiring KVM, root, eBPF, systemd, external storage, or the complete source workspace document those prerequisites separately. A skipped privileged suite must not be interpreted as a completed integration validation.

Release model

The component repositories publish independent version lines:

• accelerator, connector, sandboxer, and orchestrator: vX.Y.Z;
• guest runtime: runtime-vX.Y.Z;
• guest kernel: vmlinux-vX.Y.Z.

The project repository publishes aggregate versions named release-vX.Y.Z. An aggregate version may select different version numbers for different components. releases/release.yaml selects the next Stable aggregate, while releases/daily-preview.yaml selects the current daily Preview. The aggregate workflow resolves exact component tags, verifies the declared assets and checksums, assembles the platform archive, and runs cross-component validation before publishing.

New workbench-v1 aggregates contain one platform archive with user guides, Demo and tests, six unchanged release-unit archives per architecture, both workbench images and aggregate SHA256SUMS. Extract only the selected native products plus platform-release. Import workbench separately with docker load, or acquire the matching multi-architecture registry tag. See the workbench instructions for ordinary UID builds and offline tests. The source repositories remain independent; all assets share one aggregate version.

See docs/release.md for the full asset contract, trust boundaries, failure recovery, and Preview state machine.

Documentation

• Documentation index — reading paths and component contracts;

• Architecture — system goals, architecture, lifecycle, storage, resource, network, and security semantics;

• Deployment — standalone and cluster topology, processes, ports, persistent paths, and startup dependencies;

• Performance — performance baselines with test context, regression gates, and tuning methods;

• CI — Integration E2E, source selection, native caches, and release asset validation;

• Releases — component versions, aggregate selection, assets, and release transactions;

• Quick Start — the shortest path from an aggregate release to a real MicroVM;

• Demo — the complete local demonstration and SDK flow;

• Full validation — aggregate package validation and all E2E owners;

• Security — supported versions and private vulnerability reporting.

Maintained design and reference documents have complete English/Chinese editions. English uses the default filename; Chinese counterparts use _zh.md and reciprocal language selectors. Follow the documentation contribution policy.

Contributing and security

Read the organization-wide contribution guide before opening a change. Choose the repository that owns the behavior, keep pull requests focused, and link companion pull requests in both directions when a change spans repositories.

Do not report security vulnerabilities in public issues or discussions. Follow the Security Policy and use GitHub private vulnerability reporting.

License

Original project content in this repository is licensed under the Apache License 2.0. Third-party and differently licensed content retains its own declarations and obligations. See CONTRIBUTING.md for contribution licensing.