sandstorm README

项目的 README,来自 github.com/deeplethe/sandstorm。合并为一个 markdown 文件:README.md。

Sandstorm

Sandbox lifecycle · Key features · Latency · Quick start · Status

CI Rust gVisor Firecracker License DeepLethe 中文

One machine, thousands of sandboxes. Sandstorm pauses idle sandboxes and snapshots them to disk, then restores them quickly when a request arrives, so one machine can hold far more sandboxes than it could run at once. It supports two sandbox backends, gVisor containers and Firecracker microVMs. Every sandbox has its own network namespace, and both backends can run in one fleet, each forming a resource pool of its own. The master serves a web console for viewing and managing sandboxes and scheduling across the fleet.

Start time, memory and clone time of a 64 MiB app, by runtime: on a cloud VM, Sandstorm on Firecracker from a warm template 84 ms and CubeSandbox 87 ms; on a KVM machine 100 ms and 129 ms, in 11 and 12 MiB, and 938 ms and 1.1 s to clone into 20; Docker with gVisor 685 ms, microsandbox 1.1 s and Kata 3.4 s.

The 64 MiB app, p50 of 20 started one at a time, log scales. Each panel is ranked on its own, best first, in gold; Sandstorm's other rows are in blue. FC: Firecracker. Cube: CubeSandbox. Also shown: microsandbox, Kata, Docker, Podman, bubblewrap. Warm: restored from an image of the app already started. Cloud VM: six 2-core, 2 GB nodes for gVisor and containers; one 2-core, 3.6 GB VM under PVM for Firecracker and CubeSandbox. KVM machine: 2 × Xeon E5-2637 v2, 31 GB. Clones are of a running app, until all 20 answer (microsandbox: until running).

Adaptive Sandbox Lifecycle

Agents spend much of their time waiting. Sandstorm is designed around this behavior, with four sandbox tiers that progressively suspend idle sandboxes and quickly wake them when requests arrive.

Tier State Memory Back to hot
hot Running Held —
frozen Paused, cold pages in zswap Partly held ~0.1 s
snapshot Checkpointed to disk Freed ~0.2 s
detached Only the volume remains Freed Cold start

Key Features

The master's web console shows sandbox states, tier transitions, and node headroom.

The Sandstorm console: counts of sandboxes, awake ones, nodes, creates per minute and API p99 across the top; the tier flow between awake, frozen, on disk and detached; sandboxes by tier over time, lifecycle rates, node headroom and latency.

Latency

Measured 2026-10-31, with requests from each node to its own gateway, so no network is in the path. gVisor needs no KVM and ran on six cloud nodes. Firecracker ran on one machine with KVM and one cloud VM under PVM. The hosts differ, so read each column on its own.

gVisor Firecracker, KVM Firecracker, PVM
Host 2 cores, 2 GB 16 threads, 31 GB 2 vCPU, 3.8 GB
Wake from frozen, 64 MiB app 100 ms 165 ms 78 ms
Wake from disk, 16 / 64 / 256 MiB app 130 / 150 / 720 ms 150 / 150 / 500 ms 80 / 135 / 450 ms
Wake from disk, 512 MiB / 1 GiB app 1.1 / 3.3 s 0.7 / 1.4 s 0.4 s / not run
Kept in memory per node: web / 64 MiB / 256 MiB app 76 / 18 / 6 293 / 160 / 85 45 / 34 / 18
Refused at 1, 2, 4, 8 requests a second per node 2.1 / 0.2 / 0.1 / 1.6% 0.2 / 0 / 0 / 0% 0 / 0 / 0 / 0%
Answered, of 10 / 40 woken at the same instant 6 / 6 10 / 28 5.5 of 8

Traffic is 40 sandboxes per node with a few getting most requests; about 12 fit awake on a gVisor node. p50 is 6-10 ms on gVisor, 7-50 ms on KVM and 4-14 ms on PVM; p99 is about 2 s, 0.8-1.9 s and 1.8-3.6 s, the requests that had to wait for a restore. A wake that cannot start within 2 s is refused rather than queued. A gVisor node here restores two at a time and queues four, so of 10 or more woken at once, six are answered and the rest get a 503 at once.

The "kept in memory" metric counts sandboxes that remained running with swap enabled; it does not indicate how quickly they can respond to requests.

Without swap, the PVM host could accommodate only about eight instances of the 64 MiB app. As a result, the traffic test used a smaller fleet of 20 sandboxes, and the 1 GiB app was not tested.

Firecracker's results for the 512 MiB and 1 GiB configurations are based on a single sample each.

See the full results and testing methodology.

Method

The figure at the top: every runtime started one at a time, polled every 5 ms, p50 of 20 (compare.py). Sandstorm's time includes the master placing the sandbox and the node setting up its network. The cloud column is the median of six 2-core, 2 GB nodes, and for Firecracker and CubeSandbox one 2-core, 3.6 GB VM with CubeSandbox's PVM host kernel, which gives a VM without KVM a /dev/kvm.

A warm template restores an image of the app already started, as CubeSandbox always does; it is opt-in here, because every sandbox starts from the same memory and the template has to say how to reseed. CubeSandbox's API always restores a snapshot, so its cold figure comes from its own cubemastercli multirun, with a template's create request minus the snapshot annotations and a 5 ms probe: from the client's call until the program answers, as for the rest.

Under PVM the two warm starts are level: Sandstorm 52 / 83 ms, CubeSandbox 53 / 87 ms for web and the 64 MiB app. On the KVM machine Sandstorm's is ahead: 67 / 100 ms against 78 / 129 ms. Cold, Sandstorm leads on both: 545 / 921 ms against 828 / 999 ms on the KVM machine, 667 / 869 ms against 845 / 1,094 ms under PVM, where a guest boots without a serial console unless --fc-serial-console says otherwise. The 64 MiB app was 74 ms and 78 ms on the same machine a day earlier, with the same binary, so take that column as relative. A snapshot of a running sandbox took Sandstorm 30 ms and CubeSandbox 304 ms. Clones into 1, 10 and 20 took Sandstorm 126, 214 and 361 ms, and CubeSandbox 494, 1,046 and 1,064 ms; Sandstorm's 100 took 1.7 s, and CubeSandbox was not run past 20. E2B self-hosted was not set up, and memory under PVM was not measured. Raw rows: bench/baremetal/results/2026-10-30, bench/fleet/results/2026-10-30; Sandstorm's clones, a day later with parallel creates: bench/baremetal/results/2026-10-31-parallel.

Quick start

You need Linux with cgroup v2, runsc on the PATH, Rust, and Node 22.12 or later for the console.

git clone https://github.com/deeplethe/sandstorm.git && cd sandstorm
npm --prefix web/console ci && npm --prefix web/console run build
cargo build --release -p sandstorm-core
sudo ./target/release/sandstormd serve --master --node

That runs a master and a node in one process. Open the console at https://127.0.0.1:8080, past the browser's warning about its private CA, sign in with the token in /var/lib/sandstorm/pki/api-token, make a template with + From an image, and start a sandbox from it.

A fleet of machines you can ssh to:

scripts/fleet.sh up --master m1 --nodes n1,n2,n3 --listen 80
scripts/fleet.sh seed     # put a template on each node
scripts/fleet.sh verify   # start one sandbox and check it runs

A client on another machine connects by a name the master's certificate has to list: add it with --tls-san. Nodes that are already installed, or that only reach the master from behind NAT, join as the API describes. Everything the console does is in the HTTP API, and bench/fleet load-tests a fleet.

Status

v0.6 is the current release, and it changes a lot: gVisor becomes the default backend, so a node needs no KVM, Firecracker stays as a second backend chosen node by node, and one host becomes a fleet. The release before it, v0.5.3, is the Firecracker fork runtime; its README is at that tag. The design decisions are recorded in docs/adr.

Next, from what the fleet runs found:

License

Apache-2.0

sandstorm (deeplethe/sandstorm)

正在搜索数据库…

这是什么?Sandstorm 让一台机器能够低成本地运行成千上万个 AI 智能体沙箱:它会把空闲的沙箱暂停并快照保存到磁盘,当有请求到来时再快速恢复。
这是托管的沙箱 API,还是需要我自己运行的软件?这是自托管的基础设施软件:单个二进制文件(sandstormd)同时充当 master、node 和 Web 控制台,并通过 HTTP API 驱动沙箱集群。它不是第三方托管服务。
我该怎样让它运行起来?运行 sandstormd,在同一个进程中启动 master 和 node,然后打开 Web 控制台,用 /var/lib/sandstorm/pki/api-token 中的令牌登录,再创建一个“From an image”模板,用它启动沙箱。
运行前需要先安装哪些东西?一台带有 cgroup v2 的 Linux 主机、位于 PATH 中的 runsc(gVisor 的运行时)、Rust,以及用于构建 Web 控制台的 Node 22.12 或更高版本。
现在有什么不足之处?v0.6 尚未发布。该版本将 gVisor 设为默认后端,并取消了对 KVM 的依赖;而目前最近一次打标签的正式版 v0.5.3 只支持较早的 Firecracker 分支运行时。另外,如果沙箱无法在 2 秒内完成唤醒,请求会被直接拒绝,而不会排队等待。
除了 Linux,它还能在其他系统上运行吗?不能。gVisor 后端要求使用带有 cgroup v2 的 Linux 主机;Firecracker 后端还需要 KVM(或者可以在不依赖 KVM 的半虚拟化虚拟机中运行,但会增加延迟)。
沙箱的生命周期分为哪几个层级?共有四个层级,逐步暂停空闲沙箱:hot(完全运行)、frozen(暂停,冷页面保存在 zswap 中,约 0.1 秒唤醒)、snapshot(检查点保存到磁盘,约 0.2 秒恢复)、detached(仅保留卷,需要冷启动)。
它与 CubeSandbox 或直接使用 Firecracker 等其他沙箱运行时相比如何?Sandstorm 的基准测试显示,在 KVM 和 PVM 主机上,它的冷启动都比 CubeSandbox 更快(在 KVM 上,小型应用为 545 毫秒,CubeSandbox 为 828 毫秒),快照和克隆操作也快得多(单次快照为 30 毫秒,CubeSandbox 为 304 毫秒)。
多台机器之间的调度是如何工作的?单个 master 将期望状态保存在 SQLite 中,并负责把沙箱分配到各个 node 上。节点通过地址和配对码加入,或在位于 NAT 之后时主动向外连接;每个节点都运行一个网关,在有流量到达时唤醒沙箱。
它支持哪些隔离后端?两种后端:gVisor 容器和 Firecracker 微虚拟机。它们各自作为独立的资源池运行在同一集群中,并分别进行了各自的优化。
有哪些类似的项目?smolvm, SPACE, CubeSandbox, rivet, agentbox, substrate, coop, NemoClaw
作者
deeplethe
大小
10.4 MB
星标
6.1K
时长
6个月
提交 · 90 天