A3S Box

CORE MECHANISMS

A dedicated kernel costs more to start; a warm pool keeps it off the request path.

A shared-kernel process starts lighter but keeps the host-kernel attack surface. A3S Box defaults to a dedicated guest kernel; CoW and warm pools reduce repeated startup work, while qualifying SEV-SNP hosts can inject secrets after attestation.

01 / KERNEL BOUNDARY

Shared kernels start lighter; MicroVMs add a hardware boundary

A Sandbox uses namespace, seccomp, subordinate IDs, and cgroup v2 process isolation, so it does not boot a guest kernel. The agent still shares the host Linux kernel: if a working host-kernel exploit succeeds, process isolation may fail with it. The default MicroVM boots a dedicated guest kernel, so taking over that guest kernel still leaves a hardware VM boundary to cross.

Creating a MicroVM has higher startup and memory cost because it starts a VMM, guest kernel, and guest init. Warm pools and snapshot-fork can pay that cost before a task arrives. The hypervisor, hardware, mounts, network exposure, and side channels still require review.a3s-box run --rm alpine:3.20 -- uname -a

ONE AGENT · TWO ISOLATION PATHSstartup cost and attack path

SANDBOXshared kernel

create pathREADY

process create · lower cost

AGENT

namespace + seccomp

shared host kernel

host data

host may be affected

MICROVMdedicated kernel

create pathREADY

VMM → kernel → init · higher cost

AGENT

guest Linux kernel

hardware VM boundary

HOST · shared host kernel

stopped at VM boundary

02 / COPY ON WRITE

Allocate new pages only for changed data

On Linux, filesystem restores share one read-only snapshot lower while each Box keeps its own upper. With Linux/KVM snapshot-fork enabled, guest RAM also restores from one MAP_PRIVATE template: untouched pages remain shared and dirty pages belong to the fork.

Filesystem CoW requires Linux overlay. RAM CoW requires a snapshot-capable Linux/KVM host; other paths use a full copy or a cold boot.a3s-box snapshot restore checkpoint-1 --name test-2

03 / WARM POOL

Lease a ready MicroVM when work arrives

The pool daemon keeps idle instances by image, CPU, memory, and volume shape. pool run takes a ready VM first, boots on demand after a miss, and replenishes min_idle in the background. Linux/KVM can also use snapshot-fork to fill the pool.

One historical /dev/kvm host measured about 73 ms from a warm pool versus about 1688 ms cold. This is host-specific evidence, not a universal performance guarantee.

Read the benchmark conditions Check platform support

a3s-box pool start --image node:24 --size 4 --snapshot-fork

04 / CONFIDENTIAL COMPUTING

Verify the guest before releasing a secret

On a qualifying AMD SEV-SNP host, the guest first produces hardware attestation evidence. A client or key service checks the workload measurement against policy, then sends secrets into protected guest memory over RA-TLS. This reduces the risk of the host directly reading guest plaintext memory.

TEE adds protected-VM initialization, attestation, and key-release work. No hardware security claim is made without evidence from a qualifying SEV-SNP host; current unit and simulation tests cover the flow only. TEE does not stop application leaks, denial of service, or every side channel.

Check platform support

a3s-box attest secure-job --ratls --policy policy.json

PLATFORM BOUNDARIES

Core mechanisms depend on the host backend. Check support first.

Linux uses KVM, Apple Silicon uses HVF, and Windows x86_64 uses WHPX. Networking, memory snapshots, Sandbox, and TEE have different support boundaries.

LinuxKVMx86_64 / arm64MicroVM + certified Sandbox hosts

macOSHVFApple SiliconMicroVM runtime

WindowsWHPXx86_64MicroVM runtime with documented limits

Read the complete platform matrix

RUNTIME WORKFLOW

With the boundary understood, run the whole OCI workflow.

From image builds through lifecycle, storage, networking, and programmable pipelines, the CLI and SDKs share one local runtime and state directory. Generations stop stale requests from modifying newer instances.

01

OCI IMAGES

Build and manage OCI images

Pull layers, use registry credentials, cache root filesystems, run multi-stage builds, save, load, and remove images.

OCIbuildcache

02

LIFECYCLE

Manage the instance lifecycle

Run, create, start, stop, restart, inspect, wait, attach, and remove instances.

statehealthlogs

03

STORAGE

Volumes and filesystem snapshots

Use bind mounts, named volumes, tmpfs, file copy, diff, export, commit, and stopped-filesystem snapshots.

volumessnapshotdiff

04

NETWORK

TSI, bridge networks, and published ports

Use TSI, no-network mode, named bridge networks, DNS aliases, peer discovery, and TCP port publishing.

TSIDNSports

05

PROGRAMMABLE CI/CD

Compose execution environments with builder APIs

Combine images, CPU, memory, environment variables, init scripts, volumes, networks, and command steps in code, then reuse snapshots and warm pools for repeated work.

Builderscriptsparallel jobs

06

INTEGRATION & OPS

Connect Kubernetes and observability systems

Use the CRI, containerd shim, structured logs, audit records, and Prometheus metrics.

CRIauditPrometheus

NATIVE SDKs

Beyond the CLI, orchestrate the same local runtime from four SDKs.

Rust, Go, Python, and TypeScript cover image builds, resources, instance startup, files, commands, scripts, and cleanup. Local use needs no endpoint or API key.

Rust

a3s-box-sdk

Typed Rust API

cargo add a3s-box-sdk

Go

sdk/go/v3

Context and concurrency-safe API

go get github.com/A3S-Lab/Box/sdk/go/v3

Python

a3s-box

Synchronous and asynchronous API

python -m pip install a3s-box

TypeScript

@a3s-lab/box

Node.js 20+ Promise API

npm install @a3s-lab/box

SDK EXAMPLES

Control the local runtime from Rust, Go, Python, or TypeScript.

Choose a language for a complete example, then scroll through creation, resources, files, commands, and cleanup in TypeScript.

01 / SDKChoose a language

Rust

Go

Python

TypeScript

use a3s_box_sdk::Sandbox;

#[tokio::main]
async fn main() -> Result<(), a3s_box_sdk::ClientError> {
    let sandbox = Sandbox::create("alpine:3.20").await?;
    let result = sandbox.commands.run("printf ready").await?;

    println!("{}", result.stdout);
    sandbox.kill().await?;
    Ok(())
}

package main

import (
    "context"
    "fmt"
    "log"

    box "github.com/A3S-Lab/Box/sdk/go/v3"
)

func main() {
    ctx := context.Background()
    sandbox, err := box.Create(ctx, "alpine:3.20")
    if err != nil {
        log.Fatal(err)
    }
    defer sandbox.Close(context.Background())

    result, err := sandbox.Run(ctx, box.Argv("printf", "ready"))
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.StdoutString())
}

import asyncio

from a3s_box import AsyncSandbox


async def main() -> None:
    async with await AsyncSandbox.create("alpine:3.20") as sandbox:
        result = await sandbox.commands.run("printf ready")
        print(result.stdout)


if __name__ == "__main__":
    asyncio.run(main())

import { Sandbox } from '@a3s-lab/box';

async function main(): Promise<void> {
  const sandbox = await Sandbox.create('alpine:3.20');

  try {
    const result = await sandbox.commands.run('printf ready');
    console.log(result.stdout);
  } finally {
    await sandbox.kill();
  }
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

02 / TYPESCRIPTReview the complete lifecycle

RUN STEPSCreate a MicroVM

sandbox.tsTYPESCRIPT

import { Sandbox } from '@a3s-lab/box';

async function main(): Promise<void> {
  const sandbox = await Sandbox.create('alpine:3.20');
  await sandbox.kill();
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

RUN STEPSSet resources and networking

sandbox.tsTYPESCRIPT

import { Sandbox } from '@a3s-lab/box';

async function main(): Promise<void> {
  const sandbox = await Sandbox.create('alpine:3.20', {
    cpus: 2,
    memoryMb: 1024,
    network: { mode: 'none' },
  });

  await sandbox.kill();
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

RUN STEPSWrite a workspace file

sandbox.tsTYPESCRIPT

import { Sandbox } from '@a3s-lab/box';

async function main(): Promise<void> {
  const sandbox = await Sandbox.create('alpine:3.20', {
    cpus: 2,
    memoryMb: 1024,
    network: { mode: 'none' },
  });

  try {
    await sandbox.files.write('/workspace/status.txt', 'ready\n');
    console.log(await sandbox.files.read('/workspace/status.txt'));
  } finally {
    await sandbox.kill();
  }
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

RUN STEPSRun a command and check the result

sandbox.tsTYPESCRIPT

import { Sandbox } from '@a3s-lab/box';

async function main(): Promise<void> {
  const sandbox = await Sandbox.create('alpine:3.20', {
    cpus: 2,
    memoryMb: 1024,
    network: { mode: 'none' },
  });

  try {
    await sandbox.files.write('/workspace/status.txt', 'ready\n');

    const result = await sandbox.commands.run(
      ['test', '-s', '/workspace/status.txt'],
      { timeoutMs: 30_000 },
    );
    if (result.exitCode !== 0) {
      throw new Error(result.stderr);
    }
    console.log(result.stdout);
  } finally {
    await sandbox.kill();
  }
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

RUN STEPSAlways clean up the Sandbox

sandbox.tsTYPESCRIPT

import { Sandbox } from '@a3s-lab/box';

async function main(): Promise<void> {
  const sandbox = await Sandbox.create('alpine:3.20', {
    cpus: 2,
    memoryMb: 1024,
    network: { mode: 'none' },
  });

  try {
    await sandbox.files.write('/workspace/status.txt', 'ready\n');

    const result = await sandbox.commands.run(
      ['test', '-s', '/workspace/status.txt'],
      { timeoutMs: 30_000 },
    );
    if (result.exitCode !== 0) {
      throw new Error(result.stderr);
    }
    console.log(result.stdout);
  } finally {
    await sandbox.kill();
  }
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

Open the complete quick start →

AGENT SKILL

Install the A3S Box Skill for coding agents.

The Skill gives A3S Code, Codex, and Claude Code the A3S Box commands, isolation modes, lifecycle, and cleanup rules.

Read the complete Skill guide

a3s-box · skill installerremote copy

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/A3S-Lab/Box/main/integrations/skills/install.sh | sh -s -- --home a3s-code

INSTALL TARGET~/.a3s/skills/a3s-box

INSTALLATION

01 / INSTALL
Choose an agent
The installer writes SKILL.md to the selected user-level Skill directory.
02 / RELOAD
Reload Skills
Restart the session or refresh the Skill list, then confirm that /a3s-box is available.
03 / RUN
Submit a task
State the image, command, files, and cleanup requirements. The agent checks the local host first.

EXAMPLE REQUEST/a3s-box

Build this repository and run its tests in an isolated MicroVM. Preserve failing logs and clean up the temporary Box.

TOOL BOUNDARY

The Skill declares only a3s-box and curl shell calls. The agent allowed-tools and file policy still decide what is available.

Give every taska dedicated kernel.

A dedicated kernel costs more to start; a warm pool keeps it off the request path.

Shared kernels start lighter; MicroVMs add a hardware boundary

Allocate new pages only for changed data

Lease a ready MicroVM when work arrives

Verify the guest before releasing a secret

Core mechanisms depend on the host backend. Check support first.

With the boundary understood, run the whole OCI workflow.

Build and manage OCI images

Manage the instance lifecycle

Volumes and filesystem snapshots

TSI, bridge networks, and published ports

Compose execution environments with builder APIs

Connect Kubernetes and observability systems

Beyond the CLI, orchestrate the same local runtime from four SDKs.

Control the local runtime from Rust, Go, Python, or TypeScript.

Create a MicroVM

Set resources and networking

Write a workspace file

Run a command and check the result

Always clean up the Sandbox

Install the A3S Box Skill for coding agents.

Choose an agent

Reload Skills

Submit a task

Install A3S Box and run your first OCI workload.