opensandbox-rs

OpenSandbox execd 的 Rust 实现

---

本仓库是 opensandbox-group/OpenSandbox 项目中 execd 组件（Go 实现）的 Rust 重写，目标是在保持逐比特 API 兼容的前提下提升性能与资源效率。

execd 运行在沙箱容器内部，对外提供 HTTP API：

• Shell 命令 — 进程池加速，SSE 流式输出
• 代码执行 — Jupyter / Shell 回退
• 文件系统 — 读写、glob、打包、权限管理
• PTY 终端 — WebSocket 交互式终端
• 指标采集 — OTLP 导出 + 本地端点

与上游的关系

	OpenSandbox（上游）	opensandbox-rs（本仓库）
范围	完整沙箱平台（server/sdk/cli/execd/ingress/egress）	仅 execd 组件
语言	Go	Rust
适用场景	部署完整的 OpenSandbox 平台	替换现有 OpenSandbox 中的 execd，或独立嵌入沙箱
SDK	Python/Java/JS/C#/Go	直接复用上游 SDK（API 兼容）
CLI	osb	复用上游 osb CLI

快速开始

cargo build -p execd
cargo run -p execd

# 验证
curl http://localhost:44772/ping

完整操作指南见 QUICKSTART.md。

性能概览

与上游 Go execd 的基准对比（macOS arm64）：

维度	Rust	Go	差距
常规延迟	~11ms	~11ms	≈持平
失败命令延迟	~12ms	~1025ms	快 82 倍
并发 SSE 吞吐	488 req/s	47 req/s	快 10 倍
RSS 内存	~10 MB	~19.5 MB	省 50%
二进制体积	7.5 MB	31 MB	小 4 倍

详细报告：docs/bench-exec-comparison.md

文档

文档	说明
QUICKSTART.md	编译、运行、API 调用示例
docs/api.md	完整 API 端点、CLI 参数、SSE 格式
docs/architecture.md	项目结构、依赖关系、设计原则
docs/pty.md	PTY 交互式终端协议
docs/bench-exec-comparison.md	跨语言基准测试报告
docs/dev-environment.md	开发环境（本地 + Docker Linux）

兼容性

这是上游 Go execd 的即插即用替代品。API 格式通过 golden fixture 测试验证：

EXECD_BIN=target/debug/execd cargo test -p compact-harness --test golden_tests

可直接复用上游 Python/Java/JS/C#/Go SDK。

构建与安装

# Release 二进制（Linux musl / macOS）
cargo build --release -p execd
# 产物：target/release/execd

# 或通过 Docker
docker pull ghcr.io/yjhmelody/opensandbox-execd:latest

# Release 页面下载预编译二进制
# https://github.com/yjhmelody/opensandbox-rs/releases

许可证

MIT