Newshot

基于 S3 的 Linux 沙箱:为 AI Agent 提供比常开方案便宜 93–99% 的成本

Translation(model translation, not the source's own text)

exec-sandbox

Coverage
Coverage
PyPI
PyPI
Python
Python
License
License

exec-sandbox 在你自己的 Linux 或 macOS 主机上的 QEMU microVM 中运行不受信任的 Python、JavaScript 或 shell 代码,例如 AI agent 编写的代码。它是一个带命令行(sbx)的 Python asyncio 库。无需云账户,也无需 API 密钥。


        import asyncio

from exec_sandbox import Language, Scheduler, VmSpec

async def main() -> None:
    async with Scheduler() as scheduler:
        # Language.PYTHON, Language.JAVASCRIPT or Language.RAW
        async with await scheduler.new(VmSpec(language=Language.PYTHON)) as session:
            result = await session.exec("print('Hello from a secure VM!')")
            print(result.stdout)  # Hello from a secure VM!
            print(result.exit_code)  # 0

asyncio.run(main())
      

其他 Python 示例在顶层使用 async with 和 await:请像上面的 main() 一样,在 async def 函数中运行它们。

目录

  • 开始:功能 · 安装 · 快速开始 · 关键术语
  • 使用:会话 · 文件 · 软件包 · 网络 · 已保存实例 · 配置 · 错误与恢复
  • 运维:性能 · 缓存与磁盘占用 · VM 镜像与离线使用 · Linux 主机设置 · 实例存储操作
  • 参考:CLI 参考 · API 参考 · 限制 · 来宾环境
  • 内部原理:工作原理 · 安全 · 贡献 · 许可证

功能

  • 硬件隔离。每个会话都在自己的 QEMU VM 中运行,而不是在容器中运行,并使用 KVM 或 HVF 加速。最多 8 层隔离(安全)。
  • 快速启动。从 warm pool 启动不到 1 ms,从 L1 内存快照启动约 50-60 ms。L2 磁盘快照保留已安装的软件包,L3 在 S3 中与所有主机共享它们(性能)。
  • 自托管。首次使用会从 GitHub Releases 下载 VM 镜像。对于无法访问互联网的主机,请使用 sbx prefetch。
  • Python API 和 CLI。可一次性或分多步运行代码,流式传输 stdout 和 stderr,并读写文件。
  • 已保存实例。save() 将 VM 的 RAM、进程和 /home/user 加密写入 S3 或本地文件夹。reuse() 之后可在同一主机类型的任意 worker 上继续它。
  • 网络控制。默认无网络访问。按 spec 配置,可设置域名允许列表,并通过 DNS 过滤和 TLS SNI 检查进行校验。
  • 内存密度。来宾中使用 zram。在 Linux 上,使用 KSM 页面合并,并对空闲 warm-pool VM 进行内存回收。

安装

  • Python:3.12、3.13、3.14(包括 free-threaded)。
  • 操作系统:Linux 或 macOS,x64 或 arm64。在 Windows 上,请使用 WSL2(

exec-sandbox 使用 /usr/bin/ 中的 qemu-system-x86_64 或 qemu-system-aarch64,若那里没有则从 PATH 中查找(设置 EXEC_SANDBOX_QEMU_BIN_X86 和 EXEC_SANDBOX_QEMU_BIN_ARM 可指定另一个文件),而 qemu-img 和 qemu-storage-daemon 从 PATH 中查找。缺少 QEMU 二进制文件,或该用户无法读取其版本或机器类型时,会在 Scheduler 启动时抛出 ConfigError(HOST_DEPENDENCY);缺少 qemu-img 则在首次使用它时抛出。可用 /usr/bin/qemu-system-x86_64 --version(或 qemu-system-aarch64)检查版本:Ubuntu 24.04 自带 8.2.2。已保存实例和 L1 快照需要 QEMU 11.0 或更高版本:如果发行版自带的是更旧的版本,就从其源码发布版(qemu.org/download)构建 QEMU,并把 EXEC_SANDBOX_QEMU_BIN_X86 或 EXEC_SANDBOX_QEMU_BIN_ARM 指向该二进制文件。

在 Linux 上,用 sudo usermod -aG kvm $USER 为你的用户开通 KVM 访问权限,然后重新登录。没有该权限时,exec-sandbox 会记录一条警告并使用 TCG。若要以 QEMU 自己的用户运行它,并配合 cgroup 限制和命名空间,参见 Linux host setup。

快速开始

首次运行会下载 VM 镜像(How images download)。Python 方面,参见开头的示例和 Sessions。sbx 随 cli extra 一起提供;它的所有选项都在 CLI reference 中。


        sbx run 'print("Hello from sandbox")'                                  # Python
sbx run -l javascript 'console.log("Hello from sandbox")'              # JavaScript
sbx run script.py                                                      # 一个文件:扩展名决定语言
sbx run -p pandas==3.0.1 'import pandas; print(pandas.__version__)'    # 带软件包
sbx run --network --allow-domain api.example.com fetch_data.py         # 网络,带允许列表
sbx run --instance my-vm -c 'x = 41'                                   # 保留 VM 状态(Saved instances)
sbx run --instance my-vm -c 'print(x + 1)'                             # 42
      

关键术语

术语含义
Spec一个 VmSpec:VM 由什么构成(VmSpec)
REPLVM 中运行你的代码的解释器
Session运行你的代码的一台 VM:由 new() 或 reuse() 给出,close() 结束该 VM(Sessions)
Saved instancesave() 存下的会话状态(RAM、进程、/home/user 中的文件):reuse() 可在其 host kind 的任意 worker 上继续它(Saved instances)
Warm pool在请求之前就已启动的 VM(Warm pool)
L1、L2、L3快照缓存:内存快照、装好软件包的磁盘快照,以及 L2 在 S3 中的副本(Snapshot cache)。它让新 VM 启动更快;它不保存任何 saved instance
Instance storesaved instance 存放的位置:你的 S3 存储桶(s3),或本机上的一个文件夹(local)(Choose a store)
Generation一个 instance 的保存编号:1,之后每保存一次加 1
Head存储中指明某个 instance 当前状态的对象
VM images每种语言的内核、initramfs 和基础磁盘镜像(VM images and offline use)
AssetsVM 镜像和 gvproxy-wrapper 二进制文件:即 sbx prefetch 下载的内容
Guest images一台 VM 的磁盘镜像:基础镜像,以及带软件包时的 L2 软件包镜像
Worker在其宿主机(一台机器或一个容器)上运行 Scheduler 的进程
Host kind一个 saved instance 要加载所必须匹配的条件(Rules for save and reuse)
Admission等待宿主机具备运行一台 VM 所需的内存、CPU 和磁盘(Limits)
KVM、HVF、TCGLinux(KVM)和 macOS(HVF)上的硬件加速。TCG 是 QEMU 的软件模拟

会话

scheduler.new(spec) 启动一台新 VM 并返回其会话。会话在多次 exec() 调用之间保留变量、导入、文件和后台进程(Limits),直到 close() 销毁该 VM。有些错误会关闭会话(What closes a session)。


        async with Scheduler() as scheduler:
    async with await scheduler.new(VmSpec(language=Language.PYTHON)) as session:
        await session.exec("import math")
        await session.exec("x = math.pi * 2")
        result = await session.exec("print(f'{x:.4f}')")
        print(result.stdout)  # 6.2832
        print(session.exec_count)  # 3
      

JavaScript 会话(也包括 TypeScript)会保留变量和函数。Shell 会话(raw、Bash)会保留环境变量、工作目录和函数。

会话在 session_idle_timeout_seconds(默认 300)内没有调用后关闭。对于单个会话,将 idle_timeout_seconds(10-3600)传给 new() 或 reuse();超出范围的值会抛出 InvalidInputError(ARGUMENT_INVALID)。

要在代码运行时获取输出,将 on_stdout 和 on_stderr 传给 exec():await session.exec(code, on_stdout=lambda chunk: print(chunk, end=""))。要获取内核、tiny-init 和 guest agent 的启动输出,将 on_boot_log 传给 new();此时 VM 总是冷启动(没有 warm pool,也没有 L1)。保持每个回调简短:缓慢的回调会阻塞事件循环。

文件

路径相对于 /home/user,即代码运行所在的文件夹。


        await session.write_file("input.csv", b"name,score\nAlice,95")  # From bytes, a local Path or an IO[bytes] stream
await session.write_file("run.sh", Path("./run.sh"), make_executable=True)  # Mode 0755 (default 0644)
await session.exec("open('output.csv', 'w').write(open('input.csv').read().upper())")
await session.read_file("output.csv", destination=Path("./output.csv"))  # To a local Path or an IO[bytes] stream
for f in await session.list_files(""):  # "" is /home/user
    print(f.name, f.is_dir, f.size)
      

        sbx run --upload ./local.csv:input.csv --download output.csv:./result.csv -c "open('output.csv','w').write(open('input.csv').read().upper())

- 调用 reuse() 之后,端口会重新打开:固定的宿主端口必须在本机上空闲,动态端口则可能变化(重新读取 exposed_ports)。

## 已保存的实例

save() 会把一台 VM 的状态(内存、进程、/home/user 下的文件)压缩并加密后写入 instance store。reuse() 之后可在同一种 host kind 的任意 worker 上继续它。每个 worker 都需要 QEMU 11.0 或更高版本(否则 Scheduler 启动会以 ConfigError MIGRATION_UNSUPPORTED 失败),以及一个 keyring:设置 EXEC_SANDBOX_INSTANCE_KEYRING,或在代码里传入 instance_keyring=(见 Keys)。

      

import os

from exec_sandbox import Language, Scheduler, SchedulerConfig, VmSpec

KEYRING = os.environ["MY_KEYRING"] # from your secret store: see Keys config = SchedulerConfig(instance_store="local", instance_keyring=KEYRING) # "s3" for several workers async with Scheduler(config) as scheduler: async with await scheduler.new(VmSpec(language=Language.PYTHON)) as session: await session.exec("x = 41") ref = await session.save() # InstanceRef(instance_id=..., generation=1) async with await scheduler.reuse(ref.instance_id) as session: # Later, with the same keyring result = await session.exec("x += 1; print(x)") print(result.stdout) # 42 await session.save() # generation 2


        
save() 之后 VM 仍在运行:保存之后 session 会继续。

## 密钥

用 python3 -c "import base64, secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())" 生成一个密钥。keyring 是以逗号分隔的密钥列表,最新的在前:第一个密钥用于加密新的保存,其余密钥只用于打开更早的实例。把 keyring 放在你的 secret store 里,并给每个 worker 相同的 keyring。保存过实例的每个密钥都要保留:没有它,reuse() 会抛出 ConfigError(INSTANCE_KEY_MISSING)。要更换密钥:见 Key rotation。

## 实例 id

要指定 id,就把它传给 new():scheduler.new(spec, instance_id="user-42")。id 由 1 到 64 个小写字母、数字、.、_ 或 - 组成,并以字母或数字开头。如果该 id 已存在,第一次 save() 会以 INSTANCE_CONFLICT 失败。不指定 id 时,第一次 save 会随机生成一个(ref.instance_id)。

## 以新 id 保存

session.save(instance_id="run-17") 会把 VM 保存为一个新实例的第 1 代,之后该 session 就保存到那个实例(session.instance)。session 原先所属的实例保持在其最后一次保存后的状态。使用已存在的 id 会抛出 INSTANCE_CONFLICT,且不会覆盖任何内容。传入 session 自己的 id 则等同于一次普通保存。

要从一次保存启动多个 session,就在每个 session 里调用同一实例的 reuse(),并在各自第一次保存时给每个 session 一个自己的 id:

      

children = [await scheduler.reuse(checkpoint.instance_id) for _ in range(3)] for n, child in enumerate(children): await child.exec(f"attempt({n})") await child.save(instance_id=f"attempt-{n}") # the checkpoint stays as it was


        
## 副本中的随机值

每个从同一份保存启动的 VM,都会从它的第一次 exec() 起获得新的值:内核随机源(os.urandom、/dev/urandom)、Python ssl 以及 random 的模块级函数、JavaScript crypto 与 node:crypto 的随机函数、Math.random(也包括代码创建的 node:vm 上下文中的)、node:crypto 中 Sync 系列函数的密钥(如 generateKeyPairSync),以及 bash 的 $RANDOM。Python random 在每次 reuse() 时都会拿到新种子:要重复一次带种子的运行,就在加载之后调用 random.seed()。这些在每个副本中会保留保存时的状态:保存之前生成的值、从保存之前就在运行的程序、random.Random() 对象和 NumPy 生成器。在 Bun 中,这些在每个副本里可能给出相同的值:接受回调或返回 promise 的函数的密钥、素数与签名(如 generateKeyPair、generatePrime 和 crypto.subtle)、TLS 与 fetch,以及 Workers。要让每个副本得到不同的值,就用 Sync 系列函数生成密钥,并在副本中给其他生成器设种子。

## 选择存储

本地存储(instance_store="local")是此主机上的一个文件夹,仅供一台主机使用。对于 s3 存储,先设置桶(设置 S3 桶),然后为每个 worker 提供相同的 keyring 和相同的配置:SchedulerConfig(instance_store="s3", s3_bucket="my-bucket")。启动时,Scheduler 检查桶,并记录 "Instance store ready" 及其 key id。

## 从命令行使用实例

      

sbx run --instance my-vm -c 'x = 41' # Created instance my-vm, generation 1 sbx run --instance my-vm -c 'x += 1; print(x)' # 42, then: Saved instance my-vm, generation 2 sbx instance list # One id on each line (--json for an array) sbx instance list --long # One JSON object for each instance: as describe, or its error sbx instance describe my-vm # JSON: generation, recent commits, key id, access, writer release; spec, host (with the device layout), guest and egress domains when access is full sbx instance keys # The id of each key of the keyring, newest first sbx instance check my-vm # "my-vm ok", or why this worker cannot continue it sbx worker describe # JSON: this worker's facts (WorkerFacts), for a broker sbx instance rm my-vm other-vm # In order, stops at the first error; exit code 0 when they are gone


        
- 存储。sbx 读取 SchedulerConfig 的环境变量。默认情况下,它使用 instance_store_dir(EXEC_SANDBOX_INSTANCE_STORE_DIR)中的本地存储。对于 S3,设置 EXEC_SANDBOX_INSTANCE_STORE=s3、EXEC_SANDBOX_S3_BUCKET 和 EXEC_SANDBOX_INSTANCE_KEYRING,以及按需设置其他 EXEC_SANDBOX_S3_* 变量。只有 --instance 和 sbx instance 会打开存储。

- 密钥。sbx 读取 EXEC_SANDBOX_INSTANCE_KEYRING;在没有操作系统 keyring 的主机上(例如服务器或容器)设置它。否则,对于本地存储,sbx 在首次使用时生成一个密钥,并将其保存在操作系统 keyring 中(macOS Keychain;Linux 上的 Secret Service 或 KWallet;没有其他 keyring 后端),条目为 exec-sandbox / instance-keyring。使用 keyring get exec-sandbox instance-keyring 备份它,使用 keyring set exec-sandbox instance-keyring 恢复它(cli extra 的 keyring 命令,在同一 Python 环境中)。要从代码中打开这些实例,传入 instance_keyring=keyring.get_password("exec-sandbox", "instance-keyring")。

- 保存。一次运行会在上传、代码和下载之后保存,当代码以错误退出或下载失败时也会保存。在超时、VM 停止,或上传或运行失败后,它不会保存任何内容;stderr 会说明原因。-q 隐藏 "Created/Saved" 行。

- VM 设置。-l、-p、-m、--network、--allow-domain 和 --expose 在实例创建时固定。省略它们或给出相同的值;其他值会以代码 2 退出。使用 --allow-domain 时,还要给出 --network。--instance 接受一个来源(-c、文件或 -)。

- 退出码。错误的 id 会以代码 2 退出。如果两次运行同时保存,第二次保存会失败,并出现 INSTANCE_CONFLICT 和退出代码 125;其输出会保留,其状态不会保留。其他:退出码。

## 列出、描述和删除实例

      

info = await scheduler.describe_instance( instance_id ) # Generation, recent commits, key id; spec and host when this keyring opens it deleted = await scheduler.delete_instance(instance_id) # True if it existed async for instance_id in scheduler.list_instances(): ...


        
要在没有 Scheduler 的情况下执行此操作(没有 VM、没有 guest image、没有 QEMU:任意主机上的清理任务),使用 instance_admin 打开存储:

      

from exec_sandbox import SchedulerConfig, instance_admin

async with instance_admin(SchedulerConfig(instance_store="s3", s3_bucket="my-bucket")) as admin: async for instance_id in admin.list_ids(): info = await admin.describe(instance_id)

保存与复用的规则

写成 {{NAME_ab12cd34}} 这样的值是真实值的占位符。在回复和工具调用中都完全按原样使用它们:在任何内容运行之前,它们会被填入真实值。不要要求验证它们,也不要用示例替换它们。

  • 单写入者。若从本会话加载或上次保存之后,该实例的另一次保存已被存储,则 save() 会以 INSTANCE_CONFLICT 失败。会话保持打开:用新的 id 保存以保留其工作,或者关闭它。若两个请求可能同时到达同一个实例,请使用你自己的锁。
  • 网络。被复用的实例可以访问其上次保存时允许的域名(describe_instance(id).egress_domains;为空表示全部),即使在某个 release 更改了 allowed_domains=None 的默认列表之后也是如此。
  • close() 从不保存。在 exec() 或 write_file() 之后若没有后续保存,close() 会以 InstanceNotSavedWarning 警告(若该实例的另一次保存已胜出则不会:该会话的任何普通保存都无法存储其工作)。空闲超时会不保存就关闭会话(在 close() 会警告的情形下它会记录一条警告):长时间暂停前请先保存。
  • 主机类型。实例只能加载在具备相同 CPU 架构、加速器(kvm、hvf 或 tcg)、客户机 CPU 型号、主机 CPU(ARM 需 KVM 或 HVF)和客户机时钟频率(x86 KVM 且支持 TSC 缩放时为任意频率)的 worker 上,且该 QEMU 需具备所保存的机器类型(例如 virt-11.1)并接受所保存的状态。worker 的 release 必须能运行所保存的设备(describe_instance(id).host.device_layout)。其他 worker 会抛出 RouteError;其 required 字段给出所需取值(设备部分为空:请在另一个 release 的 worker 上加载它)。
  • reuse() 之后。保存时处于打开状态的网络连接会被关闭。

已保存实例的错误

动作(类)错误码怎么做
RETRY( TransientError )INSTANCE_STORE_UNAVAILABLE , LOCAL_DISK稍后再调用。失败的保存没有存储任何内容。
ROUTE( RouteError )INSTANCE_HOST_MISMATCH使用满足 required 的 worker(见 Upgrades)。保留该实例。
RECREATE( InstanceGoneError )INSTANCE_NOT_FOUND , INSTANCE_EXPIRED , INSTANCE_INTEGRITY启动一个新实例。要再次使用同一个 id,请先调用 delete_instance(id)。抛出 INSTANCE_NOT_FOUND 的保存会让其会话保持打开:用新的 id 保存以保留其工作。
VERIFY( OutcomeUnknownError )INSTANCE_SAVE_OUTCOME_UNKNOWN会话保持打开。若 describe_instance(id).recent_commits 中包含 error.context["commit_id"] ,则保存已存储:在重新执行该工作前先检查。同一保存(同一 instance_id )的重试绝不会存储第二份副本。
VERIFY( OutcomeUnknownError )INSTANCE_CONFLICT本次保存未被存储,会话保持打开。若该会话更早的一次保存结果未知,请先在 describe_instance(id).recent_commits 中查找其 commit_id :它可能才是被存储的那次保存。否则是另一次保存占用了该实例:用新的 id 保存本会话以保留其工作,或者 reuse() 该实例(它带有另一次保存)并重新执行该工作。对于新 id,或 new(instance_id=...) 的首次保存,该 id 已被占用:请使用另一个 id。
FIX_CONFIG( ConfigError )INSTANCE_CONFIG , INSTANCE_KEY_MISSING , MIGRATION_UNSUPPORTED , IMAGE_DAMAGEDINSTANCE_CONFIG :修复 bucket、store 文件夹、权限或 keyring,或使用支持条件写入的 store。INSTANCE_KEY_MISSING :添加指定的密钥;保留该实例。MIGRATION_UNSUPPORTED :将 QEMU 升级到 11.0+。IMAGE_DAMAGED :下载或重新构建镜像。
FIX_INPUT( InvalidInputError )INSTANCE_INVALID_ID修复该 id(见 Instance ids )。

save() 和 reuse() 也可能抛出 ErrorCode 的其他错误码:见 Error codes。

配置

VmSpec

VmSpec 说明一个 VM 由什么构成。它是 frozen 且可哈希的:每个工作负载保留一个 spec。

字段默认值描述
languagerequired"python"、"javascript" 或 "raw"(shell)
memory_mb192VM 内存,最小 128 MB。参见内存和文件系统
cpu_cores1客户机 vCPU
disk_mb1024主磁盘大小( /home/user ,ext4),最小 128 MB。只有写入的块使用主机磁盘

| packages | () | 软件包,每个带版本( "pandas==3.0.1" 、 "lod

文章标题:来自 S3 的 Linux 沙箱。对 AI Agent 而言,比始终开启便宜 93-99%。

正文: 文件夹规则:instance_store_dir 必须是此用户的一个文件夹,模式为 0700,且没有 ACL 条目(当它缺失时,exec-sandbox 会创建它)。只有 root 和此用户可以写入 instance_store_dir 的父文件夹、缓存文件夹和 EXEC_SANDBOX_HOME_DISK_DIR。像 /tmp 这样的粘滞文件夹可以通过,在 Linux 上,只有此用户的私有组可写的文件夹也可以通过。对于其他人可写的根卷(例如 Kubernetes emptyDir),以 root 身份设置粘滞位(chmod +t),例如在 init 容器中。

环境变量

不是 SchedulerConfig 字段的变量:

变量默认值描述
EXEC_SANDBOX_CACHE_DIR操作系统缓存文件夹缓存文件夹的根目录(文件存放位置)
EXEC_SANDBOX_HOME_DISK_DIR<cache dir>/home-disks运行中 VM 的主磁盘,以及 save() 和 reuse() 的工作文件。此用户的一个文件夹,组和其他人不可写,没有 ACL 条目,位于磁盘上(不是 tmpfs)
EXEC_SANDBOX_INSTANCE_ASSET_DIR<cache dir>/instance-assets从实例存储下载的客户机镜像
EXEC_SANDBOX_DISK_FREE_FLOOR_MB1024准入控制保留在主磁盘文件夹所在磁盘上的可用空间
EXEC_SANDBOX_AVAILABLE_MEMORY_FLOOR_MB0准入控制保留的可用主机内存
EXEC_SANDBOX_HOST_MEMORY_MB , EXEC_SANDBOX_HOST_CPU_COUNT自动检测用于准入预算的主机大小
EXEC_SANDBOX_QEMU_BIN_X86 , EXEC_SANDBOX_QEMU_BIN_ARM/usr/bin/qemu-system-x86_64 , /usr/bin/qemu-system-aarch64QEMU 二进制文件(安装 QEMU)
EXEC_SANDBOX_FORCE_EMULATIONfalse即使 KVM 或 HVF 可用也使用 TCG
EXEC_SANDBOX_SNAPSHOT_CACHE_TTL_DAYS14L3 上传中 ttl_days 标签的值
EXEC_SANDBOX_OFFLINE未设置1 :永不下载资源(缺失的资源会失败)
EXEC_SANDBOX_ASSET_VERSION未设置使用此发布版本的资源
EXEC_SANDBOX_LOG_LEVEL未设置exec_sandbox 日志记录器的级别( DEBUG , INFO , WARNING , ERROR )
GITHUB_TOKEN未设置发送到 GitHub API 用于资源下载(更高的速率限制)

该库记录到 exec_sandbox 日志记录器,并且不添加处理器。configure_logging(level="INFO") 添加一个 stderr 处理器(CLI 会这样做)。

错误与恢复

错误类

每个运行时错误都是一个 SandboxError,带有 action(下一步做什么,来自其类)、code(一个 ErrorCode)、message、hint、instance_id 和 context。在 QEMU 崩溃或启动超时后,context["console_log"] 保存 VM 控制台。VmSpec、SchedulerConfig 或 PortMapping 中的错误值会引发 pydantic 的 ValidationError。

来自 S3 的 Linux 沙箱。对 AI Agents 而言,比常开便宜 93-99%。

名称动作时机
SandboxError—基类(本身从不抛出)
TransientErrorRETRY这次调用没有产生你所依赖的任何效果(exec:代码根本没有发送出去)。重试它,可以在本 worker 上,也可以在另一台上,重试次数要有上限(例如 3 次,带退避)。如果会话已关闭,先在新会话上重做它未保存的工作
OutcomeUnknownErrorVERIFY代码可能已经执行,或者某次 save 的结果未知,或者另一次 save 先被存入。先检查状态
SessionClosedErrorRESTART会话已关闭。用 new() 或 reuse() 打开一个新的
InvalidInputErrorFIX_INPUT这次调用本身有误,或者调度器现在无法接受它。会话保持打开
ConfigErrorFIX_CONFIG这台 worker 的配置有误:设置、keyring、store、二进制、镜像、Python extras、权限或操作系统
RouteErrorROUTE另一台 worker 可以服务这次调用:required 给出这次调用所校验的事实,found 是本 worker 的值。当每个键都按其规则成立(RouteKey.rule:equal、at_least、contains 或 equal_or_any)时,worker 即满足 required;它通过了那些引发该错误的检查。空的 required(由另一个 release 写入了该实例)不指名任何 worker:使用 describe_instance(id).writer_release 中该 release 的 worker,或者当 describe_instance 也抛出该错误、而数据指明了其 release 时,使用错误中 context["writer_release"] 里的 worker
InstanceGoneErrorRECREATE保存的实例已消失、过期或损坏。启动一个新的
InternalErrorREPORT程序缺陷或主机故障。请附上日志报告
ErrorAction上述 8 个动作
ErrorCode见 Error codes
InstanceNotSavedWarning警告:对一个已保存实例的会话调用 close(),而该会话在最后一次 save() 之后还有 exec() 或 write_file() 调用

RouteKey 命名 RouteError.required 以及 WorkerFacts.values(describe_worker()、sbx worker describe)的键;RouteRule 命名它们的规则。在 WorkerFacts.values 中,contains 键持有这台 worker 所具有的值的集合(JSON 中为排序后的列表),而 ROUTE_ANY("any")是 equal_or_any 键取遍所有值时所用的值。

键规则值
archequalx86_64 或 aarch64
acceleratorequalkvm、hvf 或 tcg
cpu_modelequal客户机 CPU 型号(QEMU -cpu 的值)
cpu_idequalARM 客户机在 KVM 或 HVF 下看到的主机 CPU;在 x86 和 ARM TCG 上不存在
counter_hzequal_or_any客户机时钟计数器的频率(Hz),在其首次启动时设定;当该主机没有精确频率时不存在。worker 的 any:带 TSC scaling 的 x86 KVM,接受任意频率
qemu_versionat_leastMAJOR.MINOR.PATCH,逐部分比较
machine_typecontains一个 QEMU 机器类型(virt-11.1、microvm)
base_imagecontainsSHA-256 摘要(64 个十六进制字符)
packages_imagecontainsSHA-256 摘要(64 个十六进制字符)
memory_mbat_least整数 MB;worker 的 null:无限制
cpuat_least核数,保留两位小数;worker 的 null:无限制

捕获你所处理的每个动作对应的类:

from exec_sandbox import ErrorCode, InvalidInputError, OutcomeUnknownError, SandboxError, TransientError

try: async with await scheduler.new(VmSpec(language=Language.PYTHON)) as session: result = await session.exec("print('hello')", timeout_seconds=5) # 超时不会抛出异常:exit_code 为 -1 except InvalidInputError as e: # FIX_INPUT:修改这次调用 if e.code is ErrorCode.PACKAGE_NOT_ALLOWED: ... except TransientError: # RETRY:同样的调用稍后可能成功 ... except OutcomeUnknownError: # VERIFY:代码可能已经执行过 ... except SandboxError as e: # 其他动作 print(f"{e.code} ({e.action}): {e}")

退出码与超时

result.exit_code 为 0 表示成功,-1 表示超时。大于 128 的值通常意味着信号 N(退出码 - 128)杀死了代码(137 = SIGKILL,139 = SIGSEGV)。其他值表示程序失败。它是一个进程状态(0-255):sys.exit(-1) 会得到 255。基础设施故障会引发错误并返回无结果。关于 sbx 的退出码,请参阅 Exit codes。

什么会关闭会话

  • 保持打开,状态保留:异常、语法错误、sys.exit(n) 且 n ≠ 137,以及 InvalidInputError(例如 OUTPUT_LIMIT,除非其消息以 "the REPL then exited with code n" 结尾:见下一行)。
  • 保持打开,下一次 exec() 在新的 REPL 中运行:超时(-1)、非 SIGKILL 的信号(128 + signal)、os._exit(n) 且 n ≠ 137(在输出超过限制后 REPL 退出或收到信号:OUTPUT_LIMIT 其消息以 "the REPL then exited with code n" 结尾),以及两次调用之间的 REPL 退出且代码不是 137。
  • 关闭,状态丢失:退出码 137(例如 SIGKILL),在两次调用之间也是如此(下一次 exec() 会引发 GUEST_UNAVAILABLE);VM 通信失败;QEMU 停止;home 磁盘下的主机磁盘已满。之后的每次调用都会引发 SessionClosedError。
  • 其他错误:在 exec() 中,它们会关闭会话。文件调用仅在取消、OutcomeUnknownError、VM 死亡或主机磁盘已满时关闭它。对于 save(),请参阅其 docstring。

错误代码

代码类别含义
VM_BOOT_TIMEOUTTransientError客户机代理在启动时未及时响应。
QEMU_CRASHEDTransientErrorQEMU 退出或未能启动。
OVERLAY_FAILEDTransientErrorqemu-img 或 qemu-storage-daemon 无法创建磁盘镜像。
GVPROXY_FAILEDTransientErrorgvproxy 未启动或未就绪。
CAPACITYTransientError在准入超时内没有资源释放。
GUEST_UNAVAILABLETransientError客户机无法接受调用或启动代码。代码未运行。
GUEST_SILENT_AFTER_RESTORETransientError客户机在内存快照恢复后未响应,或无法重新播种其内核随机源。

| LOCAL_DISK | TransientError | 本地文件缺失(你提供的路径:ARGUMENT_IN

来自 S3 的 Linux 沙箱。比 AI Agents 始终在线便宜 93-99%。

每个 warm-pool VM 占用 272 MB 的内存预算(192 MB + 80 MB 开销):warm_pool_size=5 大约占用 4.1 GB(5 个 VM × 3 种语言)。

并发吞吐量

默认的超额分配比率来自在生产 KVM 主机上的调优。要同时服务更多请求,请增加主机;不要提高比率。在桌面上,在仓库的克隆中运行 make bench-optimizer 来找到最佳值(Contributing)。

缓存和磁盘使用

文件存放位置

缓存文件夹(<cache dir>)在 macOS 上是 ~/Library/Caches/exec-sandbox/,在 Linux 上是 ~/.cache/exec-sandbox/(或者当 $XDG_CACHE_HOME 是绝对路径时,为 $XDG_CACHE_HOME/exec-sandbox/)。它包含:

  • v<version>/:下载缓存(VM 镜像和 gvproxy-wrapper)
  • memory-snapshots/(L1)和 disk-snapshots/(L2)
  • home-disks/:运行中 VM 的主磁盘
  • instance-assets/:来自实例存储的客户机镜像(当主磁盘需要空间时,最旧的先移除,绝不移除 VM 正在运行的)

EXEC_SANDBOX_CACHE_DIR 会移动所有这些(此时下载缓存就是该文件夹本身,没有 v<version>)。每个主机使用一个缓存文件夹。将主磁盘文件夹和 L1 缓存放在磁盘上,而不是 tmpfs(许多 Linux 主机上的 /tmp):在 tmpfs 上,QEMU 写入会计入 VM 的内存。

快照缓存

新 VM 来自第一个拥有它的来源(使用 KVM 或 HVF 的计时):

来源启动时间
Warm pool低于 1 ms
L1 内存快照(之前运行过的规格;QEMU 11.0 或更高版本)约 50-60 ms
L2 磁盘快照(已安装软件包)约 200 ms 启动,然后 0.1-1 s REPL 启动
L3 快照缓存(来自 S3 的 L2)下载,然后同 L2
冷启动同 L2,加上软件包安装

启动后,REPL 在第一次 exec() 时启动(计入 timing.execute_ms,而不是 startup_timing)。

L3:S3 快照缓存

L3 通过 S3 在主机之间共享 L2 条目。设置 s3_bucket 来启用它(键在 s3_snapshot_prefix 下)。它需要 s3:GetObject、s3:PutObject、s3:PutObjectTagging 和 s3:AbortMultipartUpload 权限作用于 <s3_snapshot_prefix>*。在该前缀上添加两条生命周期规则:一条使对象过期(上传带有标签 ttl_days=14,EXEC_SANDBOX_SNAPSHOT_CACHE_TTL_DAYS),以及 AbortIncompleteMultipartUpload(1 天)。L3 错误只会记录警告。

清理

L1 和 L2 没有大小限制。exec-sandbox 仅在磁盘已满或新主磁盘需要空间时移除条目(最久未使用的先移除),并且绝不移除正在运行的 VM 使用的条目。当没有 Scheduler 运行时,你可以删除 L1 和 L2 条目、旧的 v<version> 镜像文件夹以及 instance-assets 中的文件。

VM 镜像和离线使用

exec-sandbox 需要 VM 镜像(内核、initramfs、qcow2 基础镜像)和 gvproxy-wrapper 二进制文件。它在首次使用时从 GitHub Releases 下载它们。

镜像如何下载

每次 Scheduler 启动使用这些文件夹中第一个同时包含内核和 initramfs 的:

  • images_dir(SchedulerConfig)
  • EXEC_SANDBOX_IMAGES_DIR
  • 仓库克隆中的 images/dist/(本地构建)
  • 下载缓存(文件存放位置)

如果没有文件夹包含它们,exec-sandbox 会将它们下载到下载缓存(当 auto_download_assets=False 时:ConfigError ASSET_NOT_FOUND)。它会在启动文件所在的文件夹中查找 gvproxy-wrapper,然后在克隆的 gvproxy-wrapper/bin/ 中,然后在上述文件夹中查找。它会为某种语言的基础镜像,在该语言的第一个 VM 上,在启动文件所在的文件夹中查找,然后在下载缓存中查找。启用下载时,缺失的资产会下载到下载缓存。

下载通过 HTTPS 来自此版本的 GitHub release(v{__version__}),每个文件都会根据来自 GitHub API 的 SHA-256 摘要进行校验。设置 GITHUB_TOKEN 以获得更高的 GitHub API 速率限制。

离线主机和 Docker

sbx prefetch 会在使用前下载所有资产:

来自 S3 的 Linux 沙箱。对 AI Agents 而言,比始终开启便宜 93-99%。

sbx prefetch # All assets for this architecture sbx prefetch --arch aarch64 # Assets of another architecture sbx prefetch -q # No progress output (CI, Docker)


        
      

FROM ghcr.io/astral-sh/uv:python3.12-bookworm

The image also needs QEMU (see Install)

RUN uv pip install --system "exec-sandbox[cli]" RUN sbx prefetch -q ENV EXEC_SANDBOX_OFFLINE=1

A spec with packages still needs PyPI or npm for its first build (L2 cache miss).

Run the container with --device /dev/kvm for hardware acceleration.


        
## 从源码构建镜像

在仓库的克隆中,./scripts/build-images.sh 会将 python-3.14-base-{arch}.qcow2、node-1.4-base-{arch}.qcow2 和 raw-base-{arch}.qcow2 写入 ./images/dist/。

## Linux 主机设置

## 以 qemu-vm 运行 QEMU

为了在 Linux 上获得更强的隔离,exec-sandbox 可以以非特权 qemu-vm 用户运行 QEMU:

      

Create qemu-vm system user, add it to the kvm group (hardware acceleration), and add your user to its group (socket access)

sudo useradd --system --no-create-home --shell /usr/sbin/nologin qemu-vm sudo usermod -aG kvm qemu-vm sudo usermod -aG qemu-vm $USER

Let your user run commands as qemu-vm, and chown and rm as root, with no password

echo "$USER ALL=(qemu-vm) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/qemu-vm echo "$USER ALL=(root) NOPASSWD: $(command -v chown), $(command -v rm)" | sudo tee -a /etc/sudoers.d/qemu-vm sudo chmod 0440 /etc/sudoers.d/qemu-vm

setfacl gives qemu-vm access to the home disks and the L1 cache files

sudo apt install acl

Log in again, or start a shell with the new group (for a service: sg qemu-vm -c '<command>')

newgrp qemu-vm

Check: each line must print ok

sudo -n -k -u qemu-vm /bin/sh -c 'umask 007 && exec "$@"' qemu-vm true && echo ok id -nG | grep -qw qemu-vm && echo ok sudo -n -k -l chown >/dev/null && sudo -n -k -l rm >/dev/null && echo ok

the group's members, and the accounts whose primary group it is: only qemu-vm and you

gid=$(getent group qemu-vm | cut -d: -f3); { getent group qemu-vm | cut -d: -f4 | tr , '\n'; awk -F: -v g="$gid" '$4 == g {print $1}' /etc/passwd; } | grep -vx -e '' -e qemu-vm -e "$(id -un)" | grep -q . || echo ok

in the shell that starts the service, after the cgroup setup below: makes a VM-like cgroup and moves a process into it

d=/sys/fs/cgroup/code-exec/check-$$; mkdir "$d" && sh -c 'echo 0 > "$1/cgroup.procs"' sh "$d" 2>/dev/null && test -e "$d/cgroup.kill" && echo ok; rmdir "$d"


        
- 仅将这些 sudo 权限授予服务账户:以 root 身份执行 chown 和 rm 可以触及每个文件。仅限某些命令的 (qemu-vm) 规则必须允许 /bin/sh。

- qemu-vm 组除 qemu-vm 和你的用户外不得有其他成员。

- 服务必须在 qemu-vm 组中(或以 root 身份)运行,位于资源限制(cgroups)的 cgroup v2 子树内,并且运行于 Linux 5.14 或更高版本。

- exec-sandbox 会对镜像所在目录的上级文件夹、VM 文件和 L1 缓存文件(例如你的主目录)运行 chmod a+x。

每个进程在首次启动 Scheduler 时检查此设置。如果某项检查失败,其 VM 会以你的用户运行 QEMU,并且警告会指出失败的检查。

## 资源限制(cgroups)

cgroup 限制(第 6 层)需要一个你的用户拥有的 cgroup v2 子树,并且你的服务必须在该子树内启动。重启会移除此设置:

      

sudo mkdir -p /sys/fs/cgroup/code-exec/service echo "+memory +cpu +pids" | sudo tee /sys/fs/cgroup/cgroup.subtree_control echo "+memory +cpu +pids" | sudo tee /sys/fs/cgroup/code-exec/cgroup.subtree_control sudo chown -R "$USER": /sys/fs/cgroup/code-exec echo $$ | sudo tee /sys/fs/cgroup/code-exec/service/cgroup.procs # then start the service from this shell


        
不要将你的服务 cgroup 命名为 exec-sandbox、exec-sandbox-probe、exec-sandbox-watcher、warm-pool 或 l1-cache:exec-sandbox 使用这些名称。没有此设置时,exec-sandbox 会记录 "cgroup v2 unavailable, resource limits disabled",并且仅使用 ulimit。

## 命名空间

写成 {{NAME_ab12cd34}} 这样的值是真实值的占位符。在回复和工具调用中都完全按原样使用它们:它们会在任何内容运行之前被填入真实值。不要请求验证它们,也不要用示例替换它们。

Namespaces(第 7 层)需要 util-linux 2.32 或更高版本的 unshare。检查命令:/usr/bin/unshare --pid --fork --kill-child=SIGKILL -- /usr/bin/true && echo ok。缺少它时,exec-sandbox 会记录 "unshare unavailable (namespace isolation disabled)",并在没有 namespaces 的情况下启动 QEMU。

setpriv --pdeathsig(util-linux 2.33 或更高版本)会让 gvproxy、qemu-storage-daemon 以及以你的用户身份运行的 QEMU 随服务一起结束。检查命令:setpriv --pdeathsig KILL -- /bin/sh -c : && echo ok。缺少它时,exec-sandbox 会记录 "setpriv --pdeathsig unavailable",并在服务占用大量内存时更慢地启动这些进程。

## 实例存储操作

## 设置 S3 bucket

下文的 <prefix> 即 s3_instance_prefix(默认 instances/)。

- 条件写入。存储必须支持 PUT 上的 If-None-Match 和 If-Match:AWS S3、Cloudflare R2、MinIO 和 Ceph RGW 19.2.7 或更高版本支持。调度器在启动时会检查这一点。

- 凭证。标准 AWS 链(AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY、AWS_PROFILE、~/.aws/credentials 或机器角色)。对于 R2、MinIO 或 Ceph RGW,请设置 s3_endpoint_url。

- L3 缓存。s3_bucket 还会在同一 bucket 中开启 L3 快照缓存(键位于 s3_snapshot_prefix 下):也要给 worker 相应权限(L3:S3 快照缓存),否则每新增一个 L2 条目都会记录一条警告。

- 权限。对 <prefix>* 需要 s3:GetObject、s3:PutObject、s3:DeleteObject 和 s3:AbortMultipartUpload,对 bucket 需要 s3:ListBucket(缺少它时,S3 对不存在的键返回 403)。访问出错会抛出 ConfigError(INSTANCE_CONFIG)。以 instances/ 为例:{ "Version": "2012-10-17", "Statement": [ {"Effect": "Allow", "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:AbortMultipartUpload"], "Resource": "arn:aws:s3:::my-bucket/instances/*"}, {"Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::my-bucket"} ] }

权限。对 <prefix>* 需要 s3:GetObject、s3:PutObject、s3:DeleteObject 和 s3:AbortMultipartUpload,对 bucket 需要 s3:ListBucket(缺少它时,S3 对不存在的键返回 403)。访问出错会抛出 ConfigError(INSTANCE_CONFIG)。以 instances/ 为例:

      

{ "Version": "2012-10-17", "Statement": [ {"Effect": "Allow", "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:AbortMultipartUpload"], "Resource": "arn:aws:s3:::my-bucket/instances/*"}, {"Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::my-bucket"} ] }

  • 生命周期规则。在 <prefix> 上设置 AbortIncompleteMultipartUpload(1 天),并在 <prefix>probe/ 上设置 1 天的过期时间。要移除未使用的实例,可在 <prefix>s/ 上添加 X 天的过期时间(Expiration);缺少它时,实例会一直保留到调用 delete_instance()。永远不要对 <prefix>assets/ 设置过期:所有实例共享这些 guest 镜像。只有在没有任何实例使用某个镜像时才删除它(instance_admin:list_assets()、delete_asset(digest);describe(id).guest 会列出访问状态为 "full" 的实例所用的镜像:只要还有一个实例未使用,就保留每个镜像)。一次 save 会先存储其镜像,再存储其 head:保留 bucket 中 LastModified 比最长一次 save 更新的镜像。
  • 不使用版本控制。启用版本控制后,已删除的实例仍会占用存储。如果之前开启了版本控制,请暂停它,并添加一条删除非当前版本的生命周期规则。
  • 不使用归档存储类别(例如 S3 Glacier Flexible Retrieval 或 Deep Archive):load 无法读取归档对象,会以 ConfigError(INSTANCE_CONFIG)失败。
  • s3_instance_prefix 和 s3_snapshot_prefix 不得重叠。
  • 只给 worker 写访问权限:任何能写入 bucket 的人都可以放回一个更旧的 head,从而把实例回滚。

过期

文章标题:来自 S3 的 Linux 沙箱。对 AI Agent 而言,比始终开启便宜 93-99%。

正文: 对 <prefix>s/ 设置 X 天的过期规则,会在每个对象写入后 X 天将其删除(S3 可能再多花 1-2 天)。每次保存都会再次写入 head,以及一份完整副本或一个 pack(发生变化的块)。当自上一次完整副本以来的 pack 达到其大小、达到 64 个 pack 之后、或密钥轮换之后,就会产生新的完整副本。实例在最后一次完整副本之后至少可加载 X 天。

因此,每次请求都保存的实例,至少每 X / (n + 1) 天要被使用一次,其中 n = min(完整副本大小 / 典型 pack 大小, 64)。示例:X = 30 天,完整副本为 45 MiB、pack 为 1 MiB,则 n = 45:该实例至少每 15 小时使用一次。

当某个对象不存在时,reuse() 会以 INSTANCE_EXPIRED 失败(action == "RECREATE")。仍处于打开状态的会话在下一次保存时会修复已存储的实例。

密钥轮换

实例会在下一次保存时迁移到最新的密钥。要在所有 worker 上轮换密钥:

  • 在每个 worker 的 instance_keyring 末尾添加新密钥(OLD,NEW)。
  • 当每个 worker 都拥有它之后,将其移到最前面(NEW,OLD)。如果某个 worker 过早地将其放在最前面,其他 worker 将无法加载它保存的实例(INSTANCE_KEY_MISSING)。
  • 当没有实例使用旧密钥时将其移除:对 list_instances() 的每个 id,describe_instance(id).key_id 不是旧密钥的 id。再也不会被保存的实例会保留旧密钥。sbx instance keys(或 describe_worker().key_ids)会显示密钥环中每个密钥的 id,最新的在前。

升级

已保存的实例可在其他 exec-sandbox 发行版上、以及相同或更新版本的 QEMU 上加载:它会保留首次启动时的 QEMU 机器类型(describe_instance(id).host.machine_type)。在 x86 上,该类型(microvm)没有版本:请给 x86 worker 提供保存时的 QEMU 版本。如果某个发行版更改了 VM 的设备或其迁移能力(describe_instance(id).host.device_layout),它就无法加载更早发行版的实例:在任何下载之前返回 required 为空的 RouteError。某个发行版无法读取的数据(另一个发行版更改了存储格式)会返回 required 为空的 RouteError(INSTANCE_HOST_MISMATCH):请在其他发行版的 worker 上加载它。describe_instance(id).writer_release 会给出最后一次保存的发行版。旧的 L1 快照和 VM 镜像会保留在磁盘上(清理)。

存储布局与成本

  • 存储。每个实例在 <prefix>s/<instance_id>/ 下保存其完整副本及其 pack(最多约为完整副本的两倍)。存储会在 <prefix>assets/ 下为每个客户机镜像保存一份副本。
  • 加密。RAM、home 磁盘、VmSpec 和 host 值使用 AES-256-GCM。密钥名称、实例 id、generation、commit id 和密钥 id 是明文。客户机镜像不加密。
  • Worker 磁盘。已保存实例的每个打开会话,以及每次保存和加载,都会在 home 磁盘文件夹(EXEC_SANDBOX_HOME_DISK_DIR,默认为 <cache dir>/home-disks/)下的私有文件夹(权限 0700)中保留一个 RAM 文件和一个 home 磁盘副本(不加密)。exec-sandbox 在会话关闭时、或崩溃后的下次启动时删除它们。来自存储的客户机镜像会保留在 <cache dir>/instance-assets/ 中(清理)。

CLI 参考

sbx run 选项

sbx run --help 会打印相同的列表。

OptionShortDescriptionDefault
--code-c要运行的代码(可重复,替代 SOURCES)-
--language-lpython、javascript 或 raw由文件扩展名决定,否则为 python
--timeout-t超时时间(秒,1-300)30
--env-e环境变量 KEY=VALUE(可重复)-
--memory-m内存(MB,128 或更大)192
--package-p要安装的包(可重复)-
--no-validation跳过包允许列表检查false
--network出站网络。不指定 --allow-domain 时:python 仅能访问 PyPI,javascript 仅能访问 npm,raw 可访问任意主机false
--allow-domain允许的域名及其子域名(可重复;需要 --network )-
--expose暴露端口:INTERNAL[:EXTERNAL][/tcp│udp](可重复)-
--upload上传文件 LOCAL:GUEST(可重复)-
--download下载文件 GUEST:LOCAL ,或从 GUEST 下载到 ./<file name>(可重复)-
--instance要继续使用的已保存实例(在首次运行时创建),在代码运行后保存( Instance ids )-
--jsonJSON 输出( JSON output )false
--quiet-q隐藏进度输出false
--debugDEBUG 日志,以及 stderr 上的内核和 init 启动日志(跳过 warm pool 和 L1)false

Exit codes

CodeWhen
0-255代码的退出码( Exit codes and timeouts )
2用法错误(也包括未指定 --network 却使用 --allow-domain ,或无效的 VM 选项,如 -m 100 或超过 10 个 --expose ),或 action 为 FIX_INPUT 或 FIX_CONFIG 的错误
124代码超时(使用 --json 时,result.exit_code 保持为 -1),或 VM 未能及时启动( VM_BOOT_TIMEOUT )
125其他 sandbox 和实例错误
130Ctrl+C(第二次 Ctrl+C 会立即停止 VM)

有多个来源时,如果某个来源出现 FIX_INPUT 或 FIX_CONFIG 错误,运行以 2 退出;否则如果某个来源超时或未能及时启动,以 124 退出;否则以各来源中最高的退出码退出。当代码本身以 2 或 124 退出时,那只是它自己的退出码。在 JSON 数组中,超时来源的 exit_code 为 124。

JSON output

Sources--json printsFields
OneOne objectresult( stdout 、 stderr 、 exit_code 以及各项计时)、 startup 、 exposed_ports 、 instance 和 total_ms
SeveralAn array of objectsindex 、 source 、 run(上述对象,或 null )、 error 、 code 、 action 和 exit_code

单个来源在代码运行前就失败时不打印 JSON:错误会输出到 stderr。

Other commands

CommandUseExit codes
sbx instance list│describe│keys│rm从命令行使用实例成功时为 0;设置无效、id 无效或出现 FIX_INPUT 或 FIX_CONFIG 错误时为 2;其他错误为 125;Ctrl+C 之后为 130
sbx instance check从命令行使用实例每个实例都通过时为 0;有一个失败时为 1;其他情况与 sbx instance list 相同
sbx worker describe从命令行使用实例与 sbx instance list 相同
sbx prefetch离线主机和 Docker下载失败时为 1

sbx ARGS... 即 sbx run ARGS.... sbx -V 显示版本。exec-sandbox 与 sbx 是同一个命令。

API reference

每个方法的 docstring(help(Scheduler.new))列出了它的错误。

Scheduler

MemberDescription
Scheduler(config=None)用法为 async with Scheduler(config) as scheduler: ;None 表示使用默认值( SchedulerConfig )
new(spec, *, idle_timeout_seconds=None, on_boot_log=None, instance_id=None)启动一个新 VM;返回其 Session( Sessions )
reuse(instance_id, *, idle_timeout_seconds=None)从已保存的实例启动 VM;返回继续该实例的 Session( Saved instances )
wait_pool_ready(timeout=120)等待热池填满,或等待 timeout 秒后结束( Warm pool )
describe_instance(instance_id)已保存实例的 InstanceInfo( List, describe and delete instances )
list_instances()存储中实例 id 的异步迭代器
delete_instance(instance_id)删除已保存的实例;若存在则返回 True
describe_worker()本 worker 的 WorkerFacts:抛出 RouteError 的调用需要它;facts.satisfies(error.required) 表示本 worker 能否处理该调用
config代码中给出的 SchedulerConfig:仅由 EXEC_SANDBOX_* 变量设置的值不在其中(Scheduler 会使用它)

instance_admin(config) 单独打开实例存储:async with instance_admin(config) as admin:,然后调用 admin.describe(instance_id)、admin.list_ids() 和 admin.delete(instance_id),与上面三个 Scheduler 方法相同(List, describe and delete instances)。

Session

MemberDescription
exec(code, *, timeout_seconds=None, env_vars=None, on_stdout=None, on_stderr=None)运行代码;返回 ExecutionResult 。timeout_seconds 默认为 default_timeout_seconds ;env_vars 是 dict( Exit codes and timeouts )
write_file(path, content, *, make_executable=False)从 bytes、本地 Path 或 IO[bytes] 流写入文件( Files )
read_file(path, *, destination)将文件读到本地 Path 或 IO[bytes] 流
list_files(path="")列出文件夹;返回 FileInfo 条目( name 、 is_dir 、以字节为单位的 size,文件夹为 0)
save(*, instance_id=None)保存 VM 状态;返回 InstanceRef 。instance_id :以新 id 保存并继续它( Save under a new id )
close()销毁 VM;它从不保存( Rules for save and reuse )
specVmSpec :VM 由什么构成
startup_timingStartupTiming :VM 如何启动(见下文)
exposed_portslist[ExposedPort] :.internal 、 .external 、 .host 、 .protocol 、 .url
exec_countint :返回结果的 exec() 调用次数
closedbool :会话已关闭
vm_idstr :VM 的 id
instanceInstanceRef │ None :此会话继续的已保存实例,由 reuse() 和每次 save() 设置

ExecutionResult

FieldTypeDescription
stdoutstr输出(最多 1 MB)
stderrstr错误(最多 100 KB)
exit_codeint0-255(0 = 成功,128+N = 通常被信号 N 杀死),或超时为 -1
execution_time_msint │ NoneVM 报告的运行时间
external_cpu_time_msint │ None宿主机测量的 CPU 时间
external_memory_peak_mbint │ None宿主机测量的峰值内存
external_cpu_nr_throttledint │ NoneCFS 限流事件(宿主机 cgroup)
timing.execute_msint连接 + 运行 + 响应,在宿主机上测量
timing.connect_msint │ None连接到 guest agent(未测量时为 None)
spawn_msint │ None获取 REPL 进程的时间(guest)
process_msint │ None从 spawn 到进程退出的时间(guest)

StartupTiming

new() 或 reuse() 调用在宿主机上测量的毫秒时间。冷启动后,解释器在第一次 exec() 时启动,并计入其 timing.execute_ms。

字段类型描述
total_msint整个调用
admission_msint等待资源槽位
setup_msint缓存查找、overlay、cgroup;在 reuse() 之后,恢复已保存的状态
boot_msint仅冷启动
warm_pool_hitbool该 VM 来自热池
l1_cache_hitbool该 VM 来自 L1 内存快照
l1_restore_msint │ NoneL1 恢复(除非 l1_cache_hit,否则为 None)
instance_load_msint │ None仅 reuse():读取、检查并下载已保存的状态
overlay_ms、qemu_cmd_build_ms、gvproxy_start_ms、qemu_fork_ms、guest_wait_ms、boot_retriesint冷启动的各个部分

InstanceRef 与 InstanceInfo

save() 返回一个 InstanceRef(instance_id、generation);将该 id 传给 reuse()。describe_instance() 返回一个 InstanceInfo:

字段类型描述
instance_idstr传给 new(instance_id=...) 或 save(instance_id=...) 的 id,否则是首次 save 生成的那个(32 个小写十六进制字符)
generationint首次 save 后为 1;之后每次 save 加 1
recent_commitstuple[RecentCommit, ...]最近若干次 save(generation、commit_id),最新的在前,最多 16 个
key_idstr保护该实例的 keyring 密钥的 id
access"full"、"other_release" 或 "no_key""full":该 keyring 打开了 head,且本 release 读取了它。"other_release":head 已打开,但另一个 release 写入了它,本 release 无法读取。"no_key":该 keyring 没有该密钥,其他字段不做检查
writer_releasestr │ None最近一次 save 所用的 exec-sandbox release;当 access 为 "no_key",或 body 未指明任何 release 时为 None
specVmSpec │ NoneVM 的构成(除非 access 为 "full",否则为 None)
hostHostFacts │ None最近一次 save 的主机:arch、accelerator、cpu_model、cpu_id、qemu_version、machine_type、release、device_layout(guest 所见的 VM 每个部分各一行:主板、RAM、每个驱动器和设备;然后是迁移能力)(除非 access 为 "full",否则为 None)
guestGuestFacts │ Noneguest 首次启动时得到的内容:其文件的 SHA-256 摘要、base_image、packages_image(无 packages 时为 None)、kernel、initramfs,以及 counter_hz,即其时钟计数器的频率(该主机没有精确频率时为 None);每次 save 都会携带它们(除非 access 为 "full",否则为 None)
egress_domainstuple[str, ...] │ None开启网络时 VM 可访问的域名,以最近一次 save 解析的结果为准;每次 reuse 都会应用它们(空:全部;除非 access 为 "full",否则为 None)

限制

资源限制
代码大小1 MiB
stdout / stderr1 MB / 100 KB
Packages50(每个 214 字节)
环境变量100(名称:256 字节,值:4096 字节;除 tab 外不允许控制字符)
暴露端口10
文件 I/O每个文件 500 MiB;路径 4096 字节(每个组件 255 字节);等待 guest 应答最长 120 s(写入结束、每次读取的数据块、一次列表)
超时执行 1-300 s;package 安装每次尝试 300 s;VM 启动每次尝试 45 s,最多 4 次尝试
VM 内存最低 128 MB(无上限)
你的代码的进程和线程(用户 1000)1024( RLIMIT_NPROC )
并发 VM由 admission 决定(主机内存、CPU 和磁盘:SchedulerConfig、Disk admission)。等待 120 s 会以 TransientError( CAPACITY )失败;无法容纳的 home 磁盘会立即以 TransientError( LOCAL_DISK )失败
S3 中的一个已保存状态对象约 78 GiB

Guest 环境

来自 GitHub Releases 的预构建镜像,全部基于 Alpine Linux(musl libc):

镜像运行时包管理器大小
python-3.14-basePython 3.14( python-build-standalone ,musl)、cloudpickle 3.1.2uv 0.13~75 MB
node-1.4-baseBun 1.4bun~71 MB
raw-baseGNU Bash无~17 MB

来自 S3 的 Linux 沙箱。比 AI Agent 常开便宜 93-99%。

所有镜像都包含 bash;GNU coreutils、grep(带 -P 的 PCRE)、findutils、sed、gawk 和 diffutils;以及 git、curl、jq、openssl、patch、less、make、tree、tar、gzip、unzip 和 file。

  • Python。使用 uv pip install:没有 pip 命令。没有 gcc 或 musl-dev,因此需要源码构建的包无法安装(Packages)。multiprocessing.Pool 无需任何设置即可使用,对在 REPL 中定义的函数、lambda 和闭包也一样。默认 cpu_cores=1 时,CPU 密集型工作不会更快:请设置 VmSpec(cpu_cores=N) 或使用多个会话。
  • JavaScript。Bun 是与 Node.js 兼容的运行时,而非 Node.js。exec() 无需构建步骤即可运行 JavaScript 和 TypeScript,但不支持 JSX:请把 JSX 放进 .jsx 或 .tsx 文件,再用 bun run 运行。用 bun install 安装包,用 bun run 运行脚本。
  • Shell(raw)。仅含常用工具,适用于你自己安装的 shell 脚本和运行时。Language.RAW 运行 GNU Bash。以 #! 开头的代码会作为脚本文件在独立进程中运行:其变量和工作目录不会保留到下一次调用。

内存与文件系统

memory_mb 承载内核(约 20 MB)、你的进程以及 tmpfs 挂载点。tmpfs 中的文件占用 RAM:10 MB 文件约占用 10 MB。每个 tmpfs 挂载点对每个用户(UID)都有配额。

挂载点大小用途
/home/userVmSpec.disk_mb(宿主磁盘,非 RAM)可写的主目录(ext4、nosuid、nodev)
/tmpRAM 的 50%临时文件、包管理器暂存空间
/dev/shmRAM 的 40%POSIX 共享内存(Python multiprocessing 信号量)

压缩交换(zram、lz4)额外增加 40% 的 RAM:代码可用的内存比 memory_mb 多约 40%(192 MB 时约 269 MB)。压缩数据最多占用 RAM 的 20%。请使用超时而非内存上限来中止无休止分配内存的代码。

工作原理

  • Scheduler 在你的 Python 进程中运行。它从热池中取一台 VM,从快照恢复它,或启动它(Snapshot cache)。它在 Linux 上使用 KVM,在 macOS 上使用 HVF,否则使用软件模拟(TCG):因此它也能在云 VM 和无嵌套虚拟化的容器中运行。
  • 在 VM 中,tiny-init(PID 1)启动 guest agent。agent 通过 virtio-serial 接收代码,以非 root 用户在 REPL 中运行,并在代码运行期间回传 stdout 和 stderr。
  • 根文件系统是只读的(EROFS)。/home/user 是可写的 ext4 磁盘。

Linux 上的 L1 保存

  • L1 保存会将 VM 的 RAM 保留在 /dev/shm 中。在容器中,请为 /dev/shm 留出空间,以容纳同时运行的每个 L1 保存所需的 RAM(docker run --shm-size;默认是 64 MB)。否则保存会更慢。
  • 对于以普通用户(uid 1000 或更高)运行的服务,请运行 loginctl enable-linger <user>,或在 /etc/systemd/logind.conf 中设置 RemoveIPC=no。否则当该用户的最后一个登录会话结束时,L1 保存可能失败(下一次保存会重试)。

磁盘准入

主目录磁盘是稀疏的。每台 VM 预留其 disk_mb 中尚未写入的部分除以 disk_overcommit_ratio,并保持 EXEC_SANDBOX_DISK_FREE_FLOOR_MB(1024 MB)空闲。准入只统计其所属 Scheduler 的主目录磁盘;对于其他进程,它只看到它们当前使用的空间。

空间不足时,准入会先移除同一文件系统上无运行中 VM 使用的 L1 和 L2 缓存条目(最久未使用的最先移除),然后等待 VM 结束。两者都无法腾出空间时,请求立即失败,返回 TransientError(LOCAL_DISK)。

内存密度

  • 从同一 L1 内存快照恢复的 VM 共享其 RAM 页(写时复制)。
  • Linux:当宿主启用 KSM 时进行 KSM 页合并(echo 1 | sudo tee /sys/kernel/mm/ksm/run)。
  • 启用 cgroups v2 且宿主开启 zswap 的 Linux:exec-sandbox 会将空闲热池 VM 的内存移到 zswap。

安全

要报告漏洞,请遵循安全策略。

隔离层

层技术保护
1硬件虚拟化由硬件强制 CPU 隔离(KVM 或 HVF;不是 TCG)
2加固的客户机内核无模块、无 io_uring、无 eBPF,slab 和内存加固,约 530 个内核选项被关闭
3非特权 QEMUQEMU 以你的用户身份运行,或在 Linux 上以 qemu-vm 身份运行(Linux 主机设置)
4非 root REPL (UID 1000)阻止 mount、ptrace、原始套接字、内核模块
5seccompLinux,当 QEMU 支持 -sandbox 时:对 QEMU 进程的过滤器
6cgroups v2Linux,使用委托的 cgroup(Linux 主机设置):每个 VM 的内存、CPU 和进程限制
7命名空间Linux,当 unshare 对你的用户有效时(Linux 主机设置):QEMU 的 PID、网络、挂载、UTS 和 IPC 命名空间
8套接字认证 (SO_PEERCRED/LOCAL_PEERCRED)检查 QEMU 进程的身份

主机上的所有 VM 以同一用户身份运行(第 3 层):在单独的主机上运行不能共享文件的工作负载。

保证

  • 每个会话一个 VM。会话从不共享 VM,并且 close() 会销毁它。
  • 默认无网络。设置 allow_network=True 来开启。
  • 域名允许列表。DNS 不解析不允许的域名。在端口 443 上,检查 TLS SNI,也会对照 DNS 答案进行检查。
  • 包检查。默认情况下,仅允许前 10,000 个 PyPI 和 npm 包。
  • 每个 VM 中的随机输出不同,对于从一个内存快照或一个保存的实例启动的 VM 也是如此:副本中的随机值。

供应链

exec-sandbox 根据每个下载的 SHA-256 摘要进行检查(如何下载镜像)。发布资产具有来源证明:使用 gh attestation verify <file> --repo dualeai/exec-sandbox 检查文件。每个发布版本包含 Python 依赖项的 SBOM(CycloneDX 和 SPDX),而不是 VM 镜像的 SBOM。

贡献

要贡献,请先打开一个 issue 讨论更改。

make install # Set up the environment make test # Run tests make lint # Format and lint make test-sudo # Tests that need sudo (Linux: qemu-vm user, cgroups); make test does not run them

许可证

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗