A3S Box

核心实现

独立内核要多付启动成本；暖池让任务不用等待。

共享内核进程启动更轻，但保留宿主内核攻击面。A3S Box 默认使用独立来宾内核；CoW 和暖池减少重复启动成本，符合条件的 SEV-SNP 主机还可在证明通过后注入密钥。

01 / 内核边界

共享内核更轻；独立内核多一道硬件边界

Sandbox 用 namespace、seccomp、从属 ID 和 cgroup v2 隔离进程，因此不必启动来宾内核；但 Agent 与宿主机仍共用 Linux 内核。如果有效的宿主内核漏洞被利用，进程隔离可能失效。默认 MicroVM 为任务启动独立来宾内核，即使 Agent 取得来宾内核，仍需再跨过硬件 VM 边界。

创建 MicroVM 还要启动 VMM、来宾内核和 guest init，耗时和内存开销高于共享内核进程。暖池和 snapshot-fork 可提前支付这部分成本；Hypervisor、硬件、挂载、网络和侧信道仍需审查。a3s-box run --rm alpine:3.20 -- uname -a

同一个 Agent，两种隔离路径启动开销与攻击路径

SANDBOX共享内核

创建路径READY

进程创建 · 较低开销

AGENT

NAMESPACE + SECCOMP

共享宿主 Linux 内核

宿主机数据

可能影响宿主机

MICROVM独立内核

创建路径READY

VMM → 内核 → INIT · 较高开销

AGENT

来宾 Linux 内核

硬件 VM 边界

HOST · 共享宿主 Linux 内核

在 VM 边界停下

02 / 写时复制

只为修改过的数据分配新页

Linux 文件系统恢复把同一份快照作为只读 lower，每个 Box 只保存自己的 upper。启用 Linux/KVM snapshot-fork 后，来宾 RAM 也从同一模板按 MAP_PRIVATE 恢复；未修改页继续共享，脏页才进入分叉副本。

文件系统 CoW 依赖 Linux overlay；RAM CoW 需要支持原生快照的 Linux/KVM 主机，其他情况会使用完整复制或冷启动。a3s-box snapshot restore checkpoint-1 --name test-2

03 / 暖池

任务到来时直接领取已就绪的 MicroVM

pool daemon 按镜像、CPU、内存和卷配置维护空闲实例。pool run 优先领取已启动的 VM；没有空闲实例时按需启动，后台再补到 min_idle。Linux/KVM 还可用 snapshot-fork 加快池填充。

一次特定 /dev/kvm 主机实测中，预热池约 73 ms，冷启动约 1688 ms；这是历史实测，不是跨机器性能承诺。

查看实测条件查看平台支持范围

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

04 / 机密计算

先验证来宾，再把密钥送进去

在符合条件的 AMD SEV-SNP 主机上，来宾先生成硬件证明。客户端或密钥服务按策略验证工作负载度量后，才通过 RA-TLS 把密钥送入来宾的受保护内存；该流程用于降低宿主侧直接读取来宾明文内存的风险。

TEE 会增加受保护 VM 初始化、证明验证和密钥释放开销。当前仓库的单元与模拟测试只覆盖流程；没有真实 SEV-SNP 硬件证明证据就不作硬件安全声明。它也不防应用泄漏、拒绝服务或全部侧信道。

查看平台支持范围

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

平台边界

核心机制依赖宿主后端，先确认平台支持范围。

Linux 使用 KVM，Apple Silicon 使用 HVF，Windows x86_64 使用 WHPX。网络、内存快照、Sandbox 和 TEE 的支持范围并不相同。

LinuxKVMx86_64 / arm64MicroVM + 认证 Sandbox 主机

macOSHVFApple SiliconMicroVM 运行时

WindowsWHPXx86_64MicroVM 运行时（存在已记录限制）

查看完整平台矩阵

运行时工作流

明确隔离边界之后，完成整个 OCI 工作流。

从镜像构建到实例生命周期、存储、网络和可编程流水线，CLI 与 SDK 共用同一个本地运行时与状态目录。代际编号会阻止旧请求修改新实例。

01

OCI 镜像

构建与管理 OCI 镜像

支持分层拉取、仓库凭据、rootfs 缓存、多阶段构建、保存、加载和删除。

OCI构建缓存

02

生命周期

管理实例生命周期

支持运行、创建、启动、停止、重启、检查、等待、附加和删除。

状态健康检查日志

03

存储

卷与文件系统快照

支持绑定挂载、命名卷、tmpfs、文件复制、差异、导出、提交和停止态文件系统快照。

卷快照差异

04

网络

TSI、桥接网络与端口发布

支持 TSI、无网络模式、命名桥接网络、DNS 别名、节点发现和 TCP 端口发布。

TSIDNS端口

05

可编程 CI/CD

用构建者 API 组合执行环境

在代码中组合镜像、CPU、内存、环境变量、初始化脚本、卷、网络和命令步骤，并为重复任务复用快照与暖池。

Builder脚本并行任务

06

集成与运维

接入 Kubernetes 与可观测系统

提供 CRI、containerd shim、结构化日志、审计记录和 Prometheus 指标。

CRI审计Prometheus

原生 SDK

在 CLI 之外，用四种 SDK 编排同一个本地运行时。

Rust、Go、Python 和 TypeScript SDK 覆盖镜像构建、资源配置、实例启动、文件、命令、脚本和清理。本地使用不需要 endpoint 或 API key。

Rust

a3s-box-sdk

类型化 Rust API

cargo add a3s-box-sdk

Go

sdk/go/v3

Context 与并发安全 API

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

Python

a3s-box

同步和异步 API

python -m pip install a3s-box

TypeScript

@a3s-lab/box

Node.js 20+ Promise API

npm install @a3s-lab/box

SDK 示例

用 Rust、Go、Python 或 TypeScript 控制本地运行时。

先选择语言查看完整示例，再向下滚动逐步查看 TypeScript 示例中的创建、资源、文件、命令和清理。

01 / SDK选择语言

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 / TYPESCRIPT逐步查看完整生命周期

运行步骤创建 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;
});

运行步骤设置资源和网络

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;
});

运行步骤写入工作文件

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;
});

运行步骤运行命令并检查结果

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;
});

运行步骤始终清理 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;
});

打开完整快速开始 →

AGENT SKILL

为编码 Agent 安装 A3S Box Skill。

Skill 向 A3S Code、Codex 和 Claude Code 提供 A3S Box 的命令、隔离模式、生命周期和清理规则。

阅读完整 Skill 指南

a3s-box · skill installer远程副本

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

安装目标~/.a3s/skills/a3s-box

安装步骤

01 / INSTALL
选择 Agent
安装脚本会把 SKILL.md 写入对应的用户级 Skill 目录。
02 / RELOAD
重新加载 Skill
重启会话或刷新 Skill 列表，然后确认 /a3s-box 可用。
03 / RUN
提交任务
说明镜像、命令、文件和清理要求。Agent 会先检查本机能力。

示例请求/a3s-box

在隔离的 MicroVM 中构建这个仓库并运行测试，保留失败日志，完成后清理临时 Box。

工具边界

Skill 只声明 a3s-box 和 curl 的 Shell 调用。最终可用工具仍由 Agent 的 allowed-tools 和文件权限决定。

给每个任务一个独立内核。

独立内核要多付启动成本；暖池让任务不用等待。

共享内核更轻；独立内核多一道硬件边界

只为修改过的数据分配新页

任务到来时直接领取已就绪的 MicroVM

先验证来宾，再把密钥送进去

核心机制依赖宿主后端，先确认平台支持范围。

明确隔离边界之后，完成整个 OCI 工作流。

构建与管理 OCI 镜像

管理实例生命周期

卷与文件系统快照

TSI、桥接网络与端口发布

用构建者 API 组合执行环境

接入 Kubernetes 与可观测系统

在 CLI 之外，用四种 SDK 编排同一个本地运行时。

用 Rust、Go、Python 或 TypeScript 控制本地运行时。

创建 MicroVM

设置资源和网络

写入工作文件

运行命令并检查结果

始终清理 Sandbox

为编码 Agent 安装 A3S Box Skill。

选择 Agent

重新加载 Skill

提交任务

安装 A3S Box，运行第一个 OCI 工作负载。