sandboxed.sh · 智能体框架与编排

🌐 sandboxed.sh — 自托管 AI 编码智能体编排平台

一、项目起源与背景

凌晨三点，你突然想到一个产品 idea，想立刻让 AI 帮你把代码框架搭好、跑通测试、提一个 PR——但 ChatGPT 的上下文窗口不够、Claude.ai 没有本地文件权限、在线 IDE 无法访问你内网的 GPU 服务器。大多数 AI 编程工具都在云端，数据安全与本地基础设施之间始终存在一道鸿沟。

sandboxed.sh 正是为了解决这个痛点而生。这是一个完全自托管的云端编排平台（Self-hosted Cloud Orchestrator），可以让 Claude Code、OpenCode、Codex、Gemini、Grok 等多种 AI 编程智能体运行在你自己的 Linux 服务器上，在隔离的 workspace 中完成真实的代码开发任务。与其让 AI 在沙盒里模拟编程，不如给它一个真实的系统环境——让它能真正执行 git 操作、构建项目、跑测试，甚至自动化桌面应用。

该项目前身为 Open Agent，由 Th0rgal（Thomas）于 2025 年 12 月发起，目前已有 456 个 GitHub Stars，获得了 Claude Code、OpenCode、MCP 生态的广泛集成。

sandboxed.sh 核心界面 图1：sandboxed.sh Dashboard 核心界面

二、核心架构设计

sandboxed.sh 采用微服务架构，后端使用 Rust（Axum 框架）构建，前端为 Next.js Web 控制台，同时提供 iOS（SwiftUI）和 Android（Kotlin）原生移动端应用，架构层次清晰、功能模块解耦。

后端核心模块：

Rust + Axum + Tokio：异步 Web 框架，提供高性能 REST API 和 WebSocket 实时通信，支持 Agent 事件流推送、任务状态监控。
SQLite 持久化存储：轻量级数据库存储 agent 配置、mission 状态、OAuth token 等数据，无需额外部署数据库服务。
JWT 鉴权 + AES-GCM 加密：内置加密 secrets 管理功能，保障 API 密钥、数据库凭证等敏感信息的安全存储与传输。
portable-pty + sysinfo：支持真实终端（PTY）创建和系统资源监控，为 GUI 自动化提供底层能力。

前端与移动端：

Next.js Web Dashboard：实时监控 CPU、内存、网络指标，展示 mission 时间线和执行状态，支持技能库（Library）在线编辑、MCP 服务管理。
iOS App（SwiftUI）：提供画中画（PiP）支持，随时随地查看任务进度。
Android App（Kotlin）：与 iOS 功能对等的 Android 客户端。

代码结构亮点： 项目采用 monorepo 管理，包含 dashboard（Next.js）、src（Rust 后端）、ios_dashboard、android_dashboard、docs-site（文档站点）六大子目录，总计 919 个文件，代码总量超过 15MB，体现了成熟的多平台协作开发能力。

Dashboard 监控界面 图2：Dashboard 实时监控界面（CPU、内存、网络、任务时间线）

三、AI Agent 编排机制

这是 sandboxed.sh 最核心的创新所在——per-workspace Harness System（工具架系统）。

传统 AI 编程工具的问题在于：Agent 的 bash 命令和文件操作是在宿主机上执行的，作用域模糊，容易污染开发环境。sandboxed.sh 采用了per-workspace 隔离执行模型，每个 mission（任务）拥有独立的 workspace 目录，Agent 的所有操作都精确地发生在该 workspace 内部。

两种执行模式：

Host Workspace（主机执行）：Agent 进程直接在宿主机上运行，工作目录设置为 mission 专属目录。适合快速验证和轻量任务。
Container Workspace（容器执行）：通过 systemd-nspawn 在隔离的 Linux 容器中运行 Agent，保证 bash 命令和文件操作完全隔离，不会影响宿主机环境。需要 Docker 开启 privileged: true 模式。

多 Agent 后端支持：

Claude Code：配置写入 .claude/settings.local.json 和 .claude/skills/<name>/SKILL.md，支持原生 skills 扩展。
OpenCode：通过 opencode run CLI 在 workspace 中执行，配置 opencode.json。
Codex / Gemini / Grok：各自对应的 CLI 后端，统一由 sandboxed.sh 编排调度。

Library 系统： 所有 skills、tools、rules、agents 配置以 Git 仓库形式版本化管理，通过 Library 模块同步到各 workspace，实现配置的一次编辑、全局生效。这套设计与 Hermes Agent 的 skill 体系高度相似，两者已在 MCP 层面做了集成迁移。

Library 技能编辑器 图3：Git-backed Library 技能库编辑器

四、Mission 控制与工作流

sandboxed.sh 提供了完整的 Mission 生命周期管理：

Mission 创建：指定 workspace + agent 后端 + 任务描述，系统自动准备目录并同步 Library 配置。
实时流式输出：通过 Axum WebSocket 将 Agent 执行事件实时推送至 Dashboard，用户可以像看直播一样观察 AI 的每一步操作。
自动完成检测：内置任务完成检测逻辑（Claude Code 的 /complete 等），无需人工判断 Agent 何时结束。
定时任务（Automations）：基于 croner 实现的 cron 表达式调度，支持周期性 Agent 运行。
OpenAI 兼容代理模式：可选的 /v1/chat/completions 代理队列模式，当所有 AI 提供商临时限速时自动排队等待。

五、部署体验与上手门槛

sandboxed.sh 提供了两种安装路径，适合不同技术背景的用户：

Docker 一键部署（推荐）：

git clone https://github.com/Th0rgal/sandboxed.sh.git
cd sandboxed.sh
cp .env.example .env
# 编辑 .env 填入 API Key 和配置
docker compose up -d
# 打开 http://localhost:3000

整个过程约 5 分钟，无需深入了解 Linux 系统。

Ubuntu 24.04 原生安装： 适合生产环境部署，性能最优，支持完整的 systemd-nspawn 容器隔离，配置相对复杂，约需 30 分钟。

硬件需求：

资源	最低要求	推荐配置
内存	4GB	8GB+
磁盘	10GB	20GB+
GPU	不需要	如需本地推理则按需配置
操作系统	Linux (Docker)	Ubuntu 24.04 LTS（原生）

桌面自动化支持： 支持 X11/Xvfb 下的 GUI 应用自动化测试，Docker 模式下通过 headless Xvfb 实现，native 模式下支持原生 X11 或 Xvfb。

MCP 服务管理 图4：MCP Server 注册与管理界面

六、Telegram 集成与 Assistant Gateway

sandboxed.sh 还支持通过 Telegram Bot 与 AI Agent 交互，配合 Hermes Assistant 的 MCP 桥接，可以在 Telegram 中直接向 Agent 发送指令、接收执行结果。这使得用户无需打开浏览器，通过手机即可随时管理 AI 编程任务。

Assistant Gateway 模块负责 Telegram 兼容性和 MCP 运行时接管，实现了"用 Telegram 控制 AI Agent"的独特体验——这在同类型开源项目中较为罕见。

七、技术局限与已知问题

系统要求严格：Container workspace 隔离模式需要 privileged: true 的 Docker 容器或完整的 systemd-nspawn 支持，Windows/macOS 用户仅能使用 Host workspace 模式。
多 Agent 协作尚未成熟：虽然支持多 runtime 并存，但多 Agent 协作（multi-agent collaboration）场景下的冲突处理和资源调度仍在探索中。
文档存在碎片化：除 README 外，还有 docs-site 文档站点和 docs/ 目录中的多篇设计文档，内容丰富但入口分散，初次上手需要一定时间定位。
MIT 许可证无专利授权：LICENSE 为标准 MIT，未包含专利授权条款，企业使用需注意。

八、行业意义与生态价值

sandboxed.sh 代表的趋势是 AI Agent 的本地化与自主可控。随着 Claude Code、Copilot 等编程工具逐步普及，如何在保证数据隐私和基础设施可控的前提下规模化使用 AI Agent，成为企业和个人开发者的核心诉求。

sandboxed.sh 通过以下方式回应这一诉求：

零供应商锁定：不依赖任何云端 AI 服务，自托管意味着完全掌控数据流向。
多 runtime 统一编排：一次配置，多个 AI 引擎可切换，降低单一供应商依赖。
开发者工作流深度集成：git-backed Library 机制让团队可以像管理代码一样管理 AI 技能。

该项目与 Hermes Agent 生态存在天然的协同潜力——sandboxed.sh 的 Library 技能体系、skill authoring 规范与 Hermes 的 skill 机制高度一致，文档中已记录了 Hermes Assistant 的迁移集成方案，未来两者有望在 multi-agent 协作场景下进一步融合。

九、快速开始

前提条件： Docker + Docker Compose

# 1. 克隆
git clone https://github.com/Th0rgal/sandboxed.sh
cd sandboxed.sh

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env：填入 CLAUDE_API_KEY / OPENAI_API_KEY 等

# 3. 一键启动
docker compose up -d

# 4. 访问 Web 控制台
open http://localhost:3000

# 5. 创建第一个 Mission
# Dashboard → New Mission → 选择 Agent（Claude Code/OpenCode）→ 描述任务 → Start

生产环境推荐 Ubuntu 24.04 原生部署，获得完整容器隔离和最优性能，详见官方文档。

本报告由 PIFS 系统自动生成，基于 GitHub 仓库公开数据。

🌐 sandboxed.sh — 自托管 AI 编码智能体编排平台

一、项目起源与背景

该项目前身为 Open Agent，由 Th0rgal（Thomas）于 2025 年 12 月发起，目前已有 456 个 GitHub Stars，获得了 Claude Code、OpenCode、MCP 生态的广泛集成。

sandboxed.sh 核心界面 图1：sandboxed.sh Dashboard 核心界面

二、核心架构设计

后端核心模块：

Rust + Axum + Tokio：异步 Web 框架，提供高性能 REST API 和 WebSocket 实时通信，支持 Agent 事件流推送、任务状态监控。
SQLite 持久化存储：轻量级数据库存储 agent 配置、mission 状态、OAuth token 等数据，无需额外部署数据库服务。
JWT 鉴权 + AES-GCM 加密：内置加密 secrets 管理功能，保障 API 密钥、数据库凭证等敏感信息的安全存储与传输。
portable-pty + sysinfo：支持真实终端（PTY）创建和系统资源监控，为 GUI 自动化提供底层能力。

前端与移动端：

Next.js Web Dashboard：实时监控 CPU、内存、网络指标，展示 mission 时间线和执行状态，支持技能库（Library）在线编辑、MCP 服务管理。
iOS App（SwiftUI）：提供画中画（PiP）支持，随时随地查看任务进度。
Android App（Kotlin）：与 iOS 功能对等的 Android 客户端。

Dashboard 监控界面 图2：Dashboard 实时监控界面（CPU、内存、网络、任务时间线）

三、AI Agent 编排机制

这是 sandboxed.sh 最核心的创新所在——per-workspace Harness System（工具架系统）。

两种执行模式：

Host Workspace（主机执行）：Agent 进程直接在宿主机上运行，工作目录设置为 mission 专属目录。适合快速验证和轻量任务。
Container Workspace（容器执行）：通过 systemd-nspawn 在隔离的 Linux 容器中运行 Agent，保证 bash 命令和文件操作完全隔离，不会影响宿主机环境。需要 Docker 开启 privileged: true 模式。

多 Agent 后端支持：

Claude Code：配置写入 .claude/settings.local.json 和 .claude/skills/<name>/SKILL.md，支持原生 skills 扩展。
OpenCode：通过 opencode run CLI 在 workspace 中执行，配置 opencode.json。
Codex / Gemini / Grok：各自对应的 CLI 后端，统一由 sandboxed.sh 编排调度。

Library 技能编辑器 图3：Git-backed Library 技能库编辑器

四、Mission 控制与工作流

sandboxed.sh 提供了完整的 Mission 生命周期管理：

Mission 创建：指定 workspace + agent 后端 + 任务描述，系统自动准备目录并同步 Library 配置。
实时流式输出：通过 Axum WebSocket 将 Agent 执行事件实时推送至 Dashboard，用户可以像看直播一样观察 AI 的每一步操作。
自动完成检测：内置任务完成检测逻辑（Claude Code 的 /complete 等），无需人工判断 Agent 何时结束。
定时任务（Automations）：基于 croner 实现的 cron 表达式调度，支持周期性 Agent 运行。
OpenAI 兼容代理模式：可选的 /v1/chat/completions 代理队列模式，当所有 AI 提供商临时限速时自动排队等待。

五、部署体验与上手门槛

sandboxed.sh 提供了两种安装路径，适合不同技术背景的用户：

Docker 一键部署（推荐）：

git clone https://github.com/Th0rgal/sandboxed.sh.git
cd sandboxed.sh
cp .env.example .env
# 编辑 .env 填入 API Key 和配置
docker compose up -d
# 打开 http://localhost:3000

整个过程约 5 分钟，无需深入了解 Linux 系统。

Ubuntu 24.04 原生安装： 适合生产环境部署，性能最优，支持完整的 systemd-nspawn 容器隔离，配置相对复杂，约需 30 分钟。

硬件需求：

资源	最低要求	推荐配置
内存	4GB	8GB+
磁盘	10GB	20GB+
GPU	不需要	如需本地推理则按需配置
操作系统	Linux (Docker)	Ubuntu 24.04 LTS（原生）

桌面自动化支持： 支持 X11/Xvfb 下的 GUI 应用自动化测试，Docker 模式下通过 headless Xvfb 实现，native 模式下支持原生 X11 或 Xvfb。

MCP 服务管理 图4：MCP Server 注册与管理界面

六、Telegram 集成与 Assistant Gateway

Assistant Gateway 模块负责 Telegram 兼容性和 MCP 运行时接管，实现了"用 Telegram 控制 AI Agent"的独特体验——这在同类型开源项目中较为罕见。

七、技术局限与已知问题

系统要求严格：Container workspace 隔离模式需要 privileged: true 的 Docker 容器或完整的 systemd-nspawn 支持，Windows/macOS 用户仅能使用 Host workspace 模式。
多 Agent 协作尚未成熟：虽然支持多 runtime 并存，但多 Agent 协作（multi-agent collaboration）场景下的冲突处理和资源调度仍在探索中。
文档存在碎片化：除 README 外，还有 docs-site 文档站点和 docs/ 目录中的多篇设计文档，内容丰富但入口分散，初次上手需要一定时间定位。
MIT 许可证无专利授权：LICENSE 为标准 MIT，未包含专利授权条款，企业使用需注意。

八、行业意义与生态价值

sandboxed.sh 通过以下方式回应这一诉求：

零供应商锁定：不依赖任何云端 AI 服务，自托管意味着完全掌控数据流向。
多 runtime 统一编排：一次配置，多个 AI 引擎可切换，降低单一供应商依赖。
开发者工作流深度集成：git-backed Library 机制让团队可以像管理代码一样管理 AI 技能。

九、快速开始

前提条件： Docker + Docker Compose

# 1. 克隆
git clone https://github.com/Th0rgal/sandboxed.sh
cd sandboxed.sh

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env：填入 CLAUDE_API_KEY / OPENAI_API_KEY 等

# 3. 一键启动
docker compose up -d

# 4. 访问 Web 控制台
open http://localhost:3000

# 5. 创建第一个 Mission
# Dashboard → New Mission → 选择 Agent（Claude Code/OpenCode）→ 描述任务 → Start

生产环境推荐 Ubuntu 24.04 原生部署，获得完整容器隔离和最优性能，详见官方文档。

本报告由 PIFS 系统自动生成，基于 GitHub 仓库公开数据。