系统架构
AstraBox 将管理 Agent 的服务与运行 Agent 程序的沙箱分开。即使浏览器或开发者的电脑断开连接，Agent 也可以继续工作；同时，沙箱与 AstraBox 账户和已保存的产品数据保持隔离。
AstraBox 如何工作
| 组成部分 | 负责内容 |
|---|---|
| AstraBox 服务 | 提供网页控制台和 API，完成用户认证与资源鉴权，保存 Agent 和 Session 记录，并向客户端实时返回工作进度。 |
| OpenSandbox | 在 Docker 或 Kubernetes 上创建、连接、暂停、恢复和删除隔离沙箱。 |
| 沙箱 | 包含 Agent 程序及其可用的系统软件。RuntimeProfile 决定沙箱镜像、网络访问和生命周期。 |
| Agent 程序 | 理解任务，调用模型和可用能力，持续工作直至需要用户输入或完成任务。 |
AstraBox 统一处理鉴权、运行配置分配、凭证、状态保存和输入输出投递。沙箱分配、隔离和 存储使用所选 Provider 支持的操作；Agent 程序通过适配器运行自己的工具、权限机制和 对话协议，它自己的对话以它的运行时为准：是否正在工作、已经取走哪些输入，以及每条 回复从哪里开始、到哪里结束。这些集成都进入同一套平台工作流程。
在内置镜像中，Agent 程序读写 Session 的 /workspace 工作区。Agent 在沙箱中启动应用后，可以通过 OpenSandbox 提供的地址在浏览器中打开；这部分流量不经过 AstraBox API。
模型端点可以使用内置 LiteLLM、已有 LiteLLM 部署，或模型 Plugin 提供的端点。 RuntimeProfile 表单列出当前部署已安装的 Agent 程序，并校验所选沙箱镜像。发布版本支持的 Agent 程序和镜像名称统一列在仓库介绍中。
主要组件
Web 控制台与 HTTP API
React 控制台与其他客户端使用同一个 FastAPI 服务。生产镜像在容器内通过 8000 端口
提供这两个入口。服务负责：
- Agent、RuntimeProfile、Session、Deployment、Assistant 和管理 API；
- 身份认证和资源鉴权；
- 已保存的 Session 历史和实时 SSE；
- 审批和问题的回答；
- 通过所选 provider 管理沙箱生命周期；
- 绑定目标地址的 MCP 出站访问和消息平台集成。
GET /healthz 用于存活检查；GET /readyz 表示当前副本是否应继续接收流量。滚动更新
设置见部署 AstraBox。
沙箱 provider
沙箱 provider 接口传递生命周期、网络、权限和受保护凭证请求，不暴露 provider SDK。所选 provider 会转换自己支持的能力，并在任务开始前拒绝其他请求。
沙箱句柄还提供沙箱内的文件，能在沙箱内运行命令、保持长驻进程，并把沙箱端口解析为地址。
无论使用哪个后端，AstraBox 都通过同一份契约使用它们：文件路径为绝对路径，权限使用 POSIX
权限位，属主使用账户名；命令是以 root 运行的 shell 命令行，退出码作为数据返回，截止时间由
调用方一侧把守；长驻进程（例如终端的 shell 或 Pi 程序）可由任一副本按 id 接入，并从字节
偏移重放输出；端点是一个 URL 加上每个请求都要带的请求头。每个内置镜像都带有 OpenSandbox
的 execd，AstraBox 自带基于它的契约实现（astrabox.providers.execd）：沙箱运行 execd、
且端点解析能带上请求所需的请求头到达其端口的 provider，可以直接复用这份实现，而不必
自己转换 SDK。无论哪种方式，astrabox.testing.sandbox_data_conformance 都在该 provider
的真实沙箱上检查这份契约。不支持长驻进程的后端通过 supports_process_sessions 声明，
需要它的 Agent 程序和终端面板会在配置时被拒绝。参见
接入新的沙箱 provider。
一个部署可以安装多个沙箱 provider，并用 ASTRABOX_SANDBOX_BACKENDS 启用实际使用的
那些；ASTRABOX_SANDBOX_BACKEND 是未指定后端的 RuntimeProfile 使用的默认后端。
RuntimeProfile 只能选择已启用的后端。仍指向已安装但未启用后端的记录会返回
SANDBOX_BACKEND_DISABLED，AstraBox 不会把它交给其他后端；启动时会在日志中列出选择了
这类后端的已启用 RuntimeProfile。后台的沙箱清点和工作区
视图回收按已启用的后端分别进行，一个控制面不可达不会影响其他后端。
内置 open_sandbox Plugin 调用 OpenSandbox Lifecycle 服务。服务镜像可以自行运行该服务并使用本机
Docker daemon，也可以连接到以 Kubernetes 为后端、单独维护的 OpenSandbox 部署。
OpenSandbox 创建沙箱、解析访问地址、续租，并执行部署支持的暂停、恢复和清理操作。 隔离强度由部署选择的容器运行时决定，例如 Docker、gVisor 或 Kata。详见 OpenSandbox 后端。
对于沙箱内的 HTTP 服务，AstraBox 先完成访问鉴权，再返回 OpenSandbox 地址。浏览器随后 通过 OpenSandbox 的 Docker 端口转发或 Kubernetes ingress 连接；应用流量无需经过 AstraBox，仍可使用相对路径资源、SSE 和 WebSocket。
Agent 程序
每个已安装的 Agent 程序都有一个 adapter，将它的原生 API 接入 AstraBox Session 操作。 推理、工具选择、权限含义和程序专属配置仍由该 Agent 程序定义。
适配器为所有 Agent 程序提供同一套运行时接口约定：把输入交给程序，从可恢复的位置读取 程序的事件，报告程序自身的状态，转交回答和中断请求，并把程序的输出转换成 AI SDK UI 消息 part。这些事件说明程序何时已持久地取走一条输入、回复何时开始和结束以及以何种方式 结束、何时在等待审批或问题的回答，以及它是否正在工作。AstraBox 按程序报告的内容记录 这些事实，从不自行推断。
适配器声明镜像、启动输入、状态格式和连接要求。平台的公共启动流程准备工作区、解析 凭证、恢复已保存的原生状态，然后激活适配器。独占沙箱和 Agent 共享沙箱中的隔离位置 使用同一套编排流程。
RuntimeProfile 选择的镜像必须与 engine_kind 兼容。需要新增 Agent 程序时，按照
接入新的 Agent 程序实现所需接口和检查。
消息平台
服务镜像内置一个私有网关，用于当前支持的 Satori 官方 adapter。AstraBox 保存 provider 配置、 只写 bot 凭证、入站消息、投递状态和来源游标；网关维持第三方连接并转换 provider Event。
具体消息平台无需另外部署 Koishi 或 Satori。Satori Protocol Server 选项用于连接部署方 已经运行的服务。多副本安装可以配置一个经过认证的外部消息网关。
Web 和消息适配器读取同一份 Session 输出。Agent 程序适配器解释原生回复边界，平台把 回复记录到 Session 的输出日志中。渠道负责向目标平台展示这些输出，不会另外运行一套 Agent 工作流程。
接入的渠道会持续跟随 Session，不需要收到新的入站消息。当原生后台任务或扩展唤醒 主 Agent 时，它的回复会沿同一条输出路径到达 Web 和接入的消息平台。子任务状态和 子任务对话记录与主 Agent 回复分别保留。纯文本渠道收到回复正文，Web 还会展示工具卡片 及其他受支持的内容。
渠道订阅在 Session 的输出日志中保存自己的位置，回复 outbox 保存投递尝试和平台消息 ID。
每次投递都从输出日志中完整读取它的回复，因此重启后继续的投递发送的是同一条回复。
适配器可以在消息开始时通过运行时输出约定设置 channel_delivery=False，标记提示性消息。
该消息保留在 Session 历史中；无论目标接收流式还是最终文本，渠道订阅都跳过它，不创建 outbox
记录。Claude 的 SessionStart hook 消息使用这项策略，原生后台回复仍正常投递。
运行环境替换时，重放包含仍在等待宿主持久化回执的 SDK 事件，即使它们早于当前回复。
服务端和 Claude 运行镜像必须一起携带这份快照约定。
系统没有第二份对话存储。参见接入新的消息平台。
数据与凭证
PostgreSQL 是 AstraBox 支持的默认数据库；所有副本使用相同持久化提供方与数据库。
内置 postgres 提供方在启动时升级结构，详见部署 AstraBox。
外部关系型提供方提供 SQLAlchemy 引擎、原生冲突操作、
结构初始化、错误分类与物理协调。仓库流程使用共享 SQLAlchemy 语句，原生差异通过提供方
冲突操作和方言编译扩展实现。模型包含 MySQL 类型与 DDL 映射，
但完整 MySQL 提供方仍需兼容的结构初始化、物理协调和真实验收；这些映射不代表支持 MySQL。
内置 LiteLLM 使用独立的数据库和数据库角色。
定时 Deployment 通过 scheduler provider 运行。内置的 dbos provider 在每个服务进程中
嵌入 DBOS Transact，把定时计划和运行记录保存在同一个 PostgreSQL 数据库的 dbos
schema 中。
AstraBox Credential Vault 是组织级资源。local Secret Store 使用 AES-GCM 加密，
aws_kms 使用 AWS KMS envelope encryption。管理员把 Vault 分配给 Agent 或 Assistant，
对话请求使用这项管理员分配。
用户身份与运行时凭证相互独立：用户身份决定谁能使用资源。受保护凭证传递也是独立步骤； 启用后，Agent 进程只收到占位符，所选沙箱 provider 只会在请求符合规则时加入真实凭证。 内置 OpenSandbox provider 通过它的出站 Credential Vault 完成映射。
平台先合并模型、MCP 和已配置的环境凭证，再交给所选沙箱 Provider。冷启动、从预热 资源分配和重新连接使用相同的凭证规则。Agent 程序适配器声明所需输入，Provider 实现 自身支持的传递方式。
Session 运行时会发生什么
- 控制台、API 或集成向 Session 发送输入；
- AstraBox 认证调用方、检查鉴权、记录输入，并返回回执。客户端持续读取 Session 的输出流；
- 同一时间由一个 AstraBox 进程持有 Session 与其运行配置的连接；任何副本都可以接收输入，并通过数据库通知告知该进程。Session 还没有运行配置，或运行配置需要重建时，AstraBox 读取当前 Agent 和 RuntimeProfile，再请求 OpenSandbox 创建、领取、恢复或重新连接沙箱；
- AstraBox 确认工作区和凭证，按需恢复原生状态，并连接到所选 Agent 程序。部署安装了运行准备流程时，AstraBox 先执行该流程，再把输入交给程序；
- Agent 程序在
/workspace中工作，并报告自己的输出、回复的开始和结束、正在等待的审批或问题，以及它是否正在工作； - 每个输出 part 到达后，AstraBox 立即转发给正在跟随该 Session 的客户端，并把这些 part 连同程序的读取位置一起记录到数据库；
- Agent 程序报告回复结束时，回复才结束，结束方式由程序自己给出。问题或审批会让回复暂停，直到有人回答。
关闭浏览器不会取消任务。客户端可以携带最后收到的 after_seq 游标重新连接，先收到断开期间错过的内容，再实时接收后续输出。详见 SSE 事件流。
运行配置可以通过以下路径启动：
| 路径 | 接收用户输入前的准备 |
|---|---|
| 冷启动 | 分配沙箱或隔离位置，准备工作区和凭证，再建立 Agent 程序连接。 |
| 预热启动 | 分配已准备的资源并关联到 Session，选择工作区，完成凭证交接和状态恢复后再激活。 |
| 重新连接或恢复 | 连接仍在运行的计算资源，或将已保存的原生状态恢复到替代资源，再调用程序的原生恢复操作。 |
预热资源可能早于 Session 创建，因此持久工作区在交付前选定。共享沙箱保留已有的根目录， 每个对话使用自己的隔离目录。如果确认计算资源已经丢失，Agent 程序正在生成的回复会以失败 结束。程序尚未取走的消息会交给替代运行配置，由它从已保存的原生状态继续对话；程序已经 取走的消息不会再次发送。
数据保存在哪里
| 数据 | 保存位置 |
|---|---|
| Agent、RuntimeProfile 和 Deployment 记录 | AstraBox 的 PostgreSQL 数据库 |
| 凭证值 | 已配置的 Secret Store |
| Session 记录：输入、回复、审批和问题，以及输出日志 | AstraBox 的 PostgreSQL 数据库 |
| Agent 程序原生状态（SessionStore） | AstraBox 的 PostgreSQL 数据库，以程序原生记录或归档格式保存 |
| Session 和 Assistant 文件 | /workspace，可使用持久工作区卷；未配置时随沙箱或受支持的快照保留 |
Environment 内联凭证要求 Secret Store 继承 EncryptedCollectionSecretStore，让引用与
密文在 PostgreSQL 中一同提交，读取方获得一致快照。local 和 aws_kms 都支持。
其他 Secret Store 可以服务无凭证的 Environment；内联凭证会以
ENVIRONMENT_SECRET_STORE_NOT_TRANSACTIONAL 拒绝。
原生状态包含 Agent 程序恢复对话所需的记录，也包括原生子对话状态。AstraBox 保存这些 记录，界面展示的消息历史不替代原生状态。替代运行配置恢复对话前，平台通过程序的状态 接口或原生文件还原记录。这项数据库存储不依赖持久工作区卷。
工作区文件的生命周期是独立的。配置持久工作区卷后，替代计算资源访问同一个工作区目录。 未配置时，删除沙箱会移除其中的文件，除非已保留受支持的快照、下载文件、提交到代码 仓库或另行保存。Assistant 暂停会先保存原生状态，再释放计算资源；保留工作区文件还需 配置持久工作区存储。详见文件和 OpenSandbox。
启用持久工作区时，存储插件提供底层文件系统，沙箱后端的工作区路由把它带进每个沙箱。 内置 OpenSandbox 后端的路由为每个沙箱提供一个 mergerfs 视图：交付前，平台把这个入口 关联到新建或已有工作区，OpenSandbox 只挂载工作区子目录，不挂载视图的管理根目录。 在创建时自行挂载存储的后端，其路由不能改绑已创建的沙箱；已有文件的 Session 因此会使用 新建的沙箱，而不是预热好的沙箱。Agent 程序不负责选择存储介质或实现目录路由。本地 文件系统适用于单个沙箱主机；多台主机需要访问同一个共享文件系统。未配置工作区卷的 部署不需要路由。配置方法见工作区部署。
Assistant 部署也可以设置 ASTRABOX_ASSISTANT_PROFILE_ON_WORKSPACE_VOLUME=false，
挂载工作区但把运行中的程序 profile 留在沙箱本地存储。这只改变共享挂载计划，原生/profile
快照与保存确认流程仍然相同。参阅工作区部署。
mounted_volume 存储插件使用部署配置的卷。aws_efs 插件校验已经配置、支持共享访问的
EFS CSI Kubernetes 卷。两者都通过后端的路由进入沙箱。部署者管理底层文件系统；使用 EFS
时，还需管理 EFS 文件系统、CSI 驱动和 AWS 凭证。
目录在沙箱交付给 Session 前选定。分配完成后，该入口不能改为另一个工作区。mergerfs 辅助进程运行在用户沙箱外，不提供任务执行期间切换文件系统的用户操作。在 Kubernetes 中，目录卷的节点亲和性使沙箱与其文件系统辅助进程运行在同一节点。
隔离与访问
Agent 程序不会收到 AstraBox 登录凭证，也不能直接访问 AstraBox 数据库。RuntimeProfile 决定沙箱使用 limited 还是 unrestricted 网络模式。启用凭证保护后，受保护的模型、MCP 及已分配的出站 Vault 凭证保存在沙箱外，只会添加到符合规则的出站请求中。
这不代表所有环境变量都受同样保护：原生 tracing 鉴权会传入沙箱内 Agent 程序的
OpenTelemetry 配置，不经过出站 Vault 注入。参见 tracing 配置说明。
沙箱启动前，镜像中已经包含 Agent 程序、沙箱内的 AstraBox 服务、系统账户和通用软件。预热沙箱可能早于领取它的 Session 创建，因此这些能力不能等到 Session 开始时再安装。通用软件和平台能力应在构建镜像时加入；只在分配沙箱后准备当前 Session 的工作区内容。
运行方式
| 方式 | Agent 任务运行在哪里 |
|---|---|
| 单台 Docker 主机 | OpenSandbox 在 AstraBox 主机上为沙箱创建独立容器。 |
| Kubernetes | OpenSandbox 在已配置的集群中创建沙箱工作负载。 |
| 已有 OpenSandbox 服务 | AstraBox 使用该服务所管理的 Docker 或 Kubernetes 运行配置。 |
三种方式使用相同的 AstraBox API 和 Session 行为。安装、安全和备份要求见部署 AstraBox。
任务如何分布取决于两个独立选择：
| 选择 | 共享内容 |
|---|---|
| AstraBox 后端副本 | API 和编排副本使用相同的产品数据库、凭证配置和可访问的沙箱服务。已保存的 Session 与原生状态不依赖某个副本的本机内存。同一时间只有一个副本持有每个 Session 与其运行配置的连接；该副本停止后，由另一个副本接管这个 Session。 |
| 沙箱工作节点 | 沙箱服务在工作节点上分配计算资源。跨节点使用持久工作区需要共享底层存储，每个 mergerfs 目录视图与使用它的沙箱位于同一节点。 |
增加后端副本不会把节点本地文件系统变成共享存储。分别配置后端副本的数据库与服务访问， 以及沙箱工作节点的计算资源与工作区存储。
扩展接口
安装 Provider 包后，可以接入其他 Agent 程序、沙箱后端、模型服务、Secret Store、身份提供方、工作区存储、扩展来源、调度器或消息平台，不需要改变 Session API。AstraBox 会在启动时检查 Provider 兼容性，并拒绝未知或不兼容的配置。
扩展接口见嵌入 AstraBox、接入新的 Agent 程序、接入新的消息平台、接入新的调度器和接入新的沙箱 provider。
相关文档
- 概览 — Agent、RuntimeProfile 和 Session
- 部署 AstraBox — 安装与运维
- OpenSandbox — 沙箱行为与配置
- HTTP API — 请求、认证、响应和流式输出