AstraBox
Claude Managed Agents 的开源、自托管替代。
体验控制台，让 Agent 在沙箱中执行任务。
演示站使用独立的模型、网络和会话限制。
开源 · 自行部署 · Apache-2.0
English · 简体中文
AstraBox 在你自己的基础设施上，把你已经在使用的 Agent 程序（Claude Code、Codex、
DeepSeek Harness、Pi 和 Hermes）变成云端 Agent，并连接所选 Agent 程序支持的模型服务。沙箱、流式输出、状态和凭证
都由它负责，你无需自己把 Agent 程序改造成服务。
```bash
curl -fsSL https://raw.githubusercontent.com/Colton-z/AstraBox/main/scripts/install.sh | bash
```
在装有 Docker 的 Linux 主机或 WSL 2 上一条命令即可完成安装。安装脚本会询问使用哪个模型服务，
并输出控制台地址 。环境要求见[快速开始](#快速开始)。
- **运行厂商自己的 Agent 程序**——每个 Agent 在沙箱里运行真正的 Claude Code、Codex
等程序，程序自带的工具和会话格式原样可用。
- **秒级启动，沙箱丢了也不丢对话**——预热沙箱让对话快速拉起；各程序的原生会话保存在平台数据库中，
下一条消息到来时恢复到新的沙箱里。确认沙箱丢失后，受影响的执行会失败；平台不会自动重放任务。
- **凭证保护**——启用受保护的凭证交付后，凭证在出口边界注入，Agent 只能看到占位符。
- **随处可达**——网页控制台、HTTP API、CLI、MCP、定时任务、签名 Webhook，以及 Slack、
Discord、Telegram、WhatsApp、LINE 等消息平台。
正在考虑 Claude Managed Agents？请看
[AstraBox 与它的对比](https://www.astrabox.ai/zh-Hans/docs/compare-claude-code-self-hosted)。
**一个平台，同时承载团队 Agent 和个人 Assistant。**[Agent](https://www.astrabox.ai/zh-Hans/docs/authoring-agents)
是面向团队和自动化的可复用云端 Agent，可以通过网页控制台、API、定时任务、Webhook、消息平台或
MCP 客户端启动任务。[Assistant](https://www.astrabox.ai/zh-Hans/docs/assistants)
是个人专属的长期云端工作区：它的所有对话都在同一个工作区中进行，并共享 Agent 程序的状态。
## 核心概念
| 概念 | 说明 | 类比 |
| --- | --- | --- |
| **Environment** | 独立的部署边界，拥有自己的 Agent、授权、凭证、对话、任务和运行资源 | “隔离的业务环境” |
| **Agent** | 由已安装 Agent 程序驱动的可复用云端 Agent 配置 | “云端同事” |
| **Assistant** | 个人工作区，所有对话共享原生记忆、Skill 和任务 | “个人云端助手” |
| **RuntimeProfile** | Environment 内的运行配方：Agent 程序、沙箱镜像、模型连接、网络访问和生命周期 | “办公桌和工具箱” |
| **Session** | Agent 的一次有状态运行，包含消息、Event 和当前状态 | “一项具体工作” |
| **Event** | Session 产生的实时输出和状态变化 | “工作进度实时播报” |
开发者可以通过这些资源运行交互任务和长时间任务，连接远程或本地 MCP 服务器、Plugin、
Skill 和代码仓库，通过定时任务、Webhook、API 和消息平台触发 Agent，并使用身份验证、
鉴权、隔离沙箱和托管凭证保护访问与数据。
[查看 AstraBox 能力 →](https://www.astrabox.ai/zh-Hans/docs/capabilities)
## 查找、分享和连接 Agent
- **Agent 详情与分享链接**——打开 `/agents/{agent_id}` 查看并分享 Agent 页面。接收者按部署要求登录，
在已有权限范围内创建自己的新对话；分享链接本身不授予权限。
- **已有对话 A2A**——按自动生成的标题和 Agent 名称查找自己的 Agent 对话，向选定对话发送任务，
继续使用它的原生上下文。Agent 管理员可以关闭目标发现、允许全部可访问的 Agent，或选择部分 Agent。
这不会开放其他用户的对话或消息通道对话。
- **按 Agent 授权管理**——Agent 管理员可以管理其 Agent 的触发器和运行记录，查看会话日志，
并导出所管理 Agent 的日志。平台级设置仍由平台管理员管理。
参见 [Agent 配置](docs/authoring-agents.md)、[A2A](docs/a2a.md)、
[会话](docs/sessions.md)和[自动化](docs/deployments.md)。
## 开箱即用的企业级基建
每个 Environment 拥有自己的部署状态和业务数据库。不同 Environment 使用独立的数据库角色与凭证，
即使共用一个 PostgreSQL 服务，也不共用业务数据。RuntimeProfile 配置 Environment 内的运行方式，
不会创建另一个 Environment。参见[部署隔离](docs/deploy.md#environments)。
一次部署就带齐团队通常要自己拼装的几块：
- **Artifacts**——Agent 和 Assistant 可发布持久化、有版本的页面，支持分享链接和实时数据。参见 [Artifact 指南](website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/artifacts.md)。
- **模型网关**——默认内置 [LiteLLM](https://github.com/BerriAI/litellm)：每个模型一个路由名，
上游密钥留在服务端，支持预算与用量日志，后面可以接 Anthropic、OpenAI 兼容服务或本地模型。
参见[连接模型服务](https://www.astrabox.ai/zh-Hans/docs/models)。
- **团队登录**——预集成 [Casdoor](https://github.com/casdoor/casdoor) 作为身份提供方：
OIDC、组织与角色；管理员在 Casdoor 中添加身份提供方后，可用 Google、Microsoft、Okta、GitHub、
SAML、LDAP 等方式登录，也支持钉钉、飞书、企业微信。运行安装脚本时设置
`ASTRABOX_INSTALL_TEAM_LOGIN=casdoor` 即可开启，从源码运行时使用 Compose 叠加配置，
参见[团队身份验证](https://www.astrabox.ai/zh-Hans/docs/team-login)。
- **隔离沙箱**——基于 [OpenSandbox](https://github.com/opensandbox-group/OpenSandbox)，单台 Docker 主机
或 Kubernetes 集群都行，并预留热容量，对话秒级拉起。
- **凭证不进沙箱**——启用受保护的凭证交付后，Vault 凭证在沙箱的出站边界注入，Agent 只看得到占位符。
参见[凭证保护](docs/egress-credential-injection.md)。
- **消息通道与触发器**——定时任务、签名 Webhook，以及基于官方
[Satori](https://github.com/satorijs/satori) 适配器接入的消息平台。
## 在终端里管理，也可以交给编程助手
`astrabox` 命令行工具无需打开网页控制台，就能配置和使用本地或远程部署。命令结果可以输出为
JSON，Claude Code、Codex 等编程助手也能替你运行这些命令。
- **配置即代码**——`astrabox init --from-deployment` 把部署中的 RuntimeProfile 和 Agent 导出为
`astrabox.yaml`；`astrabox diff` 预览修改，`astrabox apply` 创建或更新资源，从不删除。
- **在命令行派发任务**——`astrabox run ""` 会启动 Session、发送任务并流式输出回复；
加上 `--session` 可以继续已有的 Session。
- **便于程序读取的输出**——加上 `--output json` 后，命令无论成功还是失败都只输出一个 JSON 对象，
每类失败还有各自的退出码。
- **MCP 工具**——`astrabox mcp serve` 通过 stdio 把 schema、get、export、diff、apply、status 和 run
提供为 MCP 工具。
- **本地或远程**——`astrabox up`、`down` 和 `logs` 在源码目录中运行本地 Compose 部署；其他命令
通过 `--endpoint` 加 Bearer Token 或 OAuth 客户端凭证连接任意部署。
在源码目录中运行 `make install` 即可安装 CLI。Deployment（定时任务、Webhook 和消息平台触发）
以及对 Agent 提问的回答，需要在网页控制台或 HTTP API 中处理。详见
[CLI 概览](https://www.astrabox.ai/zh-Hans/docs/cli/overview)。
## 内置 Agent 程序
| Agent 程序 | 沙箱镜像 | 用于创建 |
| --- | --- | --- |
| Claude Code | `ghcr.io/colton-z/astrabox-sandbox-claude-code` | Agent |
| Codex | `ghcr.io/colton-z/astrabox-sandbox-codex` | Agent |
| DeepSeek Harness | `ghcr.io/colton-z/astrabox-sandbox-deepseek-harness` | Agent |
| pi | `ghcr.io/colton-z/astrabox-sandbox-pi` | Agent |
| Hermes Agent | `ghcr.io/colton-z/astrabox-sandbox-hermes` | Assistant |
还可以通过兼容的沙箱镜像接入其他 Agent 程序。详见
[接入新的 Agent 程序](https://www.astrabox.ai/zh-Hans/docs/writing-an-engine-adapter)。
## 为扩展而设计
AstraBox 中每个可替换的部分都是一个 Python 接口，并有对应的插件注册点。安装的 Python 包把实现
注册到相应的插件组，AstraBox 按名称选用；名称不存在时会直接报错，不会退回默认实现。
| 扩展接口 | 插件组 | 内置实现 |
| --- | --- | --- |
| Agent 程序 | `astrabox.providers.engine` | 随 AstraBox 提供的全部 Agent 程序 |
| 沙箱后端 | `astrabox.providers.sandbox` | 运行在 Docker 或 Kubernetes 上的 OpenSandbox |
| 模型服务 | `astrabox.providers.model` | LiteLLM 网关 |
| 消息平台 | `astrabox.providers.channel` | 消息平台网关、通用 JSON Webhook |
| 身份提供方 | `astrabox.web.identity` | 本地模式、OIDC、已验证 JWT、可信身份请求头 |
| Secret Store | `astrabox.providers.secrets` | 本地加密、AWS KMS |
| 工作区存储 | `astrabox.providers.storage` | 挂载卷、Amazon EFS |
| 远程 MCP 服务来源 | `astrabox.providers.extensions` | 管理员在 AstraBox 中保存的配置、LiteLLM MCP 网关 |
| [运行准备集成](docs/providers/runtime-preparation.md) | `astrabox.providers.runtime_preparation` | 可选的部署自有 Agent 资源、Session 材料、逐消息准备与用户前置条件 |
| [通道响应判断](docs/providers/channel-response.md) | `astrabox.providers.channel_response` | 内置标题模型判断、部署自有判断器 |
- **接口版本**——`astrabox.providers.*` 下的插件可以用 `seams_api_version` 声明构建时依据的接口
版本；与当前 AstraBox 不一致时，AstraBox 会拒绝加载。
- **一致性测试套件**——`astrabox.testing` 为沙箱后端、工作区存储、消息平台、Agent 程序和定时调度器
提供可复用的测试套件，在插件自己的测试中引用即可。
- **应用扩展**——通过 API 路由、中间件、生命周期钩子和服务实现的插件组扩展应用本身。
详见[接入新的 Agent 程序](https://www.astrabox.ai/zh-Hans/docs/writing-an-engine-adapter)、
[接入新的消息平台](https://www.astrabox.ai/zh-Hans/docs/writing-a-channel-provider)、
[在 Python 应用中使用 AstraBox](https://www.astrabox.ai/zh-Hans/docs/embedding)和
[扩展接口](https://www.astrabox.ai/zh-Hans/docs/architecture#plugin-interfaces)。
## 工作流程
1. **部署 AstraBox**——在一台 Docker 主机、Kubernetes 或已有基础设施中运行 AstraBox
和 OpenSandbox。
2. **配置 RuntimeProfile**——选择 Agent 程序、沙箱镜像、模型连接、网络访问和
生命周期。
3. **创建 Agent**——在网页控制台选择 RuntimeProfile 和模型；只有 Agent 需要时，才添加
系统提示词、MCP 服务器、Plugin、Skill 或代码仓库。
4. **启动 Session**——打开 Agent，启动一个 Session。
5. **发送消息并接收 Event**——查看实时输出，回答问题或审批；浏览器关闭后，
稍后仍可回来继续。
## 快速开始
### 前置条件
- 一台 Linux 主机（或 WSL 2），安装 Docker Engine 26.0 或更高版本与 Compose 插件
2.17.0 或更高版本，并且当前用户可以使用 Docker socket
- 一个模型服务的 API Key：Anthropic、DeepSeek，或其他 Anthropic 兼容、
OpenAI 兼容的服务
一条命令安装最新发布版本：
```bash
curl -fsSL https://raw.githubusercontent.com/Colton-z/AstraBox/main/scripts/install.sh | bash
```
安装脚本会询问 Agent 使用哪个模型服务，把部署安装到 `~/astrabox`，拉取已发布的镜像
并启动，控制台能够响应后打印其地址。打开 ，选择 RuntimeProfile，
在控制台创建 Agent，然后启动第一个 Session。
本地部署只监听 loopback，启用团队登录之前不要求登录；安装脚本设置
`ASTRABOX_INSTALL_TEAM_LOGIN=casdoor` 即可启用。向其他网络开放前，请按
[团队身份验证](https://www.astrabox.ai/zh-Hans/docs/team-login#put-the-login-flow-behind-a-proxy)
把它放在 HTTPS 代理之后。
升级前先阅读[发布说明](https://github.com/Colton-z/AstraBox/releases)。再次运行安装脚本可安装最新发布版本，
并保留 Session、凭证和设置。服务端与运行时镜像应使用匹配的版本；已有沙箱保留原来的 CLI，换箱后才使用新镜像。
首次启动前选定 `ASTRABOX_ENVIRONMENT_NAME`，之后保持不变；修改名称不会把数据复制到另一个 Environment。
### 从源码运行
从检出的源码构建镜像耗时更长，适合需要修改 AstraBox 本身的场景：
```bash
git clone https://github.com/Colton-z/AstraBox.git
cd AstraBox
make build-agent-image
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export ANTHROPIC_MODEL="your-model-name"
scripts/compose.sh up --build -d
```
完整步骤和 API 用法参见[快速开始](https://www.astrabox.ai/zh-Hans/docs/quickstart)。
安装脚本的全部设置，以及 Kubernetes 或已有 OpenSandbox 服务的用法，参见
[部署 AstraBox](https://www.astrabox.ai/zh-Hans/docs/deploy)。
预热会在 Session 领取之前准备好 Agent 运行时。随附部署中新建的 Agent 默认开启预热，
每个这样的 Agent 会保留一个空闲的已准备沙箱，参见
[容量规划](https://www.astrabox.ai/zh-Hans/docs/deploy#plan-capacity-for-prepared-sandboxes)。
原生会话状态保存在平台数据库中；持久工作区卷是可选能力，单独负责保留任务文件。部署多个 API 副本或沙箱节点时，参见
[分布式部署](https://www.astrabox.ai/zh-Hans/docs/deploy-distributed)和
[工作区存储](https://www.astrabox.ai/zh-Hans/docs/deploy#where-conversation-workspaces-live)。
## 适用场景
- **长时间异步任务**——开发者电脑或浏览器断开后，任务仍可继续执行。
- **API 集成**——在应用中使用 Agent，不需要另外开发和维护 Agent 运行平台。
- **批量处理**——使用多个 Session 分别处理独立请求。
- **定时与事件触发任务**——通过定时任务、Webhook、外部系统或消息平台启动 Agent。
本地 Agent 程序仍然适合在一台电脑上交互开发；AstraBox Agent 则可以远程访问、执行
长时间任务并接入其他系统，两者互补。
## 文档
- [概览](https://www.astrabox.ai/zh-Hans/docs/overview)
- [快速开始](https://www.astrabox.ai/zh-Hans/docs/quickstart)
- [定义 Agent](https://www.astrabox.ai/zh-Hans/docs/authoring-agents)
- [运行 Session](https://www.astrabox.ai/zh-Hans/docs/sessions)
- [连接 MCP 服务器、Plugin 和 Skill](https://www.astrabox.ai/zh-Hans/docs/adding-tools)
- [自动运行 Agent](https://www.astrabox.ai/zh-Hans/docs/deployments)
- [接入消息平台](https://www.astrabox.ai/zh-Hans/docs/channels)
- [部署 AstraBox](https://www.astrabox.ai/zh-Hans/docs/deploy)
- [HTTP API](https://www.astrabox.ai/zh-Hans/docs/api)
- [Agent 间通信](docs/a2a.md)
- [发布说明 · 简体中文与 English](https://github.com/Colton-z/AstraBox/releases)
## 开发
```bash
make install
make build-agent-image
make build-assistant-image
make dev
```
打开 。维护流程参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 参与贡献
欢迎提交 Issue 和 Pull Request。请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 致谢
AstraBox 建立在这些开源项目之上：
[OpenSandbox](https://github.com/opensandbox-group/OpenSandbox)、
[LiteLLM](https://github.com/BerriAI/litellm)、
[Casdoor](https://github.com/casdoor/casdoor)、
[Satori](https://github.com/satorijs/satori)、
[DBOS Transact](https://github.com/dbos-inc/dbos-transact-py)、
[mergerfs](https://github.com/trapexit/mergerfs)、
[AIO Sandbox](https://github.com/agent-infra/sandbox)、
[shadcn/ui](https://github.com/shadcn-ui/ui)、
[Vercel AI SDK 与 AI Elements](https://github.com/vercel/ai) 和
[Docusaurus](https://github.com/facebook/docusaurus)；并运行这些 Agent 程序：
[Codex](https://github.com/openai/codex)、
[Hermes Agent](https://github.com/NousResearch/hermes-agent)、
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)、
[Pi](https://github.com/earendil-works/pi) 和
[Claude Code](https://github.com/anthropics/claude-code)。完整署名与许可证见
[NOTICE](NOTICE)。
## 许可证
本项目使用 Apache License 2.0，详见 [LICENSE](LICENSE)。
Claude 与 Claude Code 是 Anthropic 的商标，OpenAI 与 Codex 是 OpenAI 的商标。AstraBox 是独立项目，
与上述公司无隶属或背书关系。Claude Code 是按 Anthropic 条款使用的专有软件，详见 [NOTICE](NOTICE)。