Sandbox 接入与验证

aster-box-sdk 提供类型化 Rust 客户端。默认实现直接调用 runtime 的状态存储与 socket 客户端，不启动 aster-box CLI。

Rust SDK 快速开始

use aster_box_sdk::Sandbox;

# async fn example() -> Result<(), aster_box_sdk::ClientError> {
let sandbox = Sandbox::create("python:3.12-alpine").await?;
let result = sandbox
    .commands
    .run("python -c 'print(6 * 7)'")
    .await?;
println!("{}", result.stdout);

sandbox.files.write("/workspace/note.txt", "hello").await?;
let text = sandbox.files.read_text("/workspace/note.txt").await?;
assert_eq!(text, "hello");

sandbox.kill().await?;
# Ok(()) }

Sandbox::create 默认选择 MicroVM，并使用长期保活命令维持 Sandbox。需要自定义初始进程时，使用 SandboxCreateOptions 设置 entrypoint 与 command。

kill 组合停止与删除。只需要停止时，使用 stop。需要保留记录供后续检查时，不要在检查前调用 kill 或 remove。

隔离与资源选项

use aster_box_sdk::{ExecutionIsolation, Sandbox, SandboxCreateOptions};

# async fn example() -> Result<(), aster_box_sdk::ClientError> {
let sandbox = Sandbox::create_with_options(
    SandboxCreateOptions::new("python:3.12-alpine")
        .isolation(ExecutionIsolation::Sandbox)
        .cpus(2)
        .memory_mb(1024),
)
.await?;

sandbox.kill().await?;
# Ok(()) }

ExecutionIsolation::Sandbox 显式选择共享内核后端。省略隔离选项时保留 MicroVM 默认。

需要类型化镜像、卷、网络和快照管理时，使用 AsterBoxClient。需要创建后启动的原子组合时，使用 run_box。

SDK 能力边界

aster-box-sdk 的主要接口
接口	用途	注意事项
Sandbox	命令、文件、日志、统计、事件与生命周期	事件与观测绑定当前代际
AsterBoxClient	镜像、卷、网络、快照和低层管理	默认不通过 CLI 执行生命周期命令
ArtifactExportOptions	限制导出大小并选择宿主目标	单文件上限 8 MiB，目标不能已存在
OperationId	标识重启与资源更新操作	结果未知前保留原 ID
sdk_capabilities	查询当前 runtime 支持的操作清单	使用前检查，不按名称猜测支持

stop、restart 和 remove 不是同一操作。暂停中的 Sandbox 支持日志、进程与事件读取。资源更新要求 Sandbox 正在运行。

SDK 导出入口见 Sandbox exports L26 ↗。

构建边界

根工作区包含 aster-sandbox、aster-box-core 和 aster-box-runtime。根目录可以构建这些包：

cargo build --locked -p aster-sandbox
cargo build --locked -p aster-box-runtime

aster-box-cli 与 aster-box-sdk 位于 crates/box 的独立工作区。完整清单保留为 crates/box/Cargo.toml.box-workspace。不要从根目录用不存在的包成员关系推断 CLI 构建方式。

使用已安装的 CLI 时，先检查版本与后端：

aster-box version
aster-box info

验收清单

aster-sandbox

运行 aster-sandbox probe。
运行 aster-sandbox capabilities。
验证默认网络拒绝与工作区外写入拒绝。
验证超时终止完整进程树。
验证输出截断和退出状态。

aster-box

运行 aster-box info，核对虚拟化后端。
创建一次性 Sandbox，核对标准输出和退出状态。
启动后台 Sandbox，核对 ps、exec、logs 和 stats。
停止并删除 Sandbox，核对记录不再运行。
测试不支持的隔离、网络或挂载配置，确认在执行前拒绝。
测试超限导出与已存在的目标文件，确认导出被拒绝且原文件不变。