用途
Blaxel 是一个云平台，为 AI 智能体提供专属计算环境。其旗舰产品是持久沙箱（perpetual sandboxes）：即时启动的 microVM，可从待机状态在 25 毫秒内恢复，并在空闲数秒后缩容至零。Blaxel SDK 用于通过代码操作这些能力，主要场景包括：
- 启动沙箱、安装依赖、运行开发服务器并暴露实时预览 URL
- 构建和部署沙箱模板（自定义 Docker 镜像）以复用环境
- 将 AI 智能体、MCP 服务器和批处理任务部署为无服务器端点
主要能力
SDK 提供 TypeScript（@blaxel/core）和 Python（blaxel）两个版本，另有 CLI 工具 bl。核心能力包括：
- 沙箱生命周期管理：创建、复用、获取、删除沙箱，支持 createIfNotExists 自动处理已终止或失败的沙箱记录
- 文件系统操作：写入单个文件、批量写入文件树、读取、列目录、写入二进制
- 进程执行：运行命令、等待完成、按端口就绪返回、获取日志、终止进程
- 预览 URL：为指定端口创建公开或私有预览，私有预览可生成访问令牌
- 沙箱模板：通过 bl new sandbox 生成模板，自定义 Dockerfile 并部署为可复用镜像
- 持久化：卷（创建时挂载的块存储）与 Agent Drive（可动态挂载的共享文件系统，私有预览）
使用方式
认证按优先级使用：已登录的 Blaxel CLI、.env 中的 BL_WORKSPACE 与 BL_API_KEY、系统环境变量、~/.blaxel/config.yaml。本地开发可执行 bl login YOUR-WORKSPACE，远程或 CI 环境可设置环境变量。在 Blaxel 上运行时认证自动完成。
典型沙箱工作流：
- 创建沙箱，指定镜像、内存和端口。端口必须在创建时声明，之后无法添加；80、443、8080 为保留端口。
- 写入文件并执行命令。开发服务器必须绑定 0.0.0.0 而非 localhost，预览 URL 才可访问。
- 创建预览 URL，公开预览设置 public: true，私有预览设置 public: false 并创建令牌。
- 管理沙箱：重连、列文件、读文件、获取进程日志、终止进程、删除沙箱。
CLI 常用命令包括 bl login、bl new sandbox|agent|job|mcp、bl deploy、bl serve、bl get、bl delete、bl connect、bl chat、bl run job。在非交互环境（脚本、CI、智能体）中可加 -y 自动确认。
适用场景
- 为 AI 智能体提供隔离的代码执行环境
- 快速搭建带实时预览的开发环境（Astro、Expo、Next.js 等教程均有提供）
- 部署 AI 智能体、MCP 服务器和批处理任务
- 在多个沙箱或智能体之间共享数据与依赖缓存
限制与注意事项
- 端口必须在沙箱创建时声明，无法后续添加；80、443、8080 为保留端口
- 开发服务器必须绑定 0.0.0.0
- 约 50% 的沙箱内存预留给内存文件系统（tmpfs），额外存储需使用卷
- 沙箱空闲约 5 秒后缩容至零，状态在待机中保留
- 已删除沙箱会在 TERMINATED 状态保留数分钟以便访问日志，直接 get 可能返回已终止实例
- 进程超时以秒为单位（默认 600），超时抛出 HTTP 422 但进程继续运行；waitForCompletion 会保持 HTTP 请求打开，沙箱 MCP 服务器上上限约 58 秒
- 默认所有进程 stdout/stderr 会导出为遥测，日志量大时会造成 CPU 争用，可通过 SANDBOX_DISABLE_PROCESS_LOGGING=true 或工作区设置关闭
- 密钥不应放入 [env]，应使用控制台的 Variables-and-secrets
- Agent Drive 目前为私有预览，仅在 us-was-1 区域可用，且驱动器与沙箱必须位于该区域
最佳实践
- 批量文件上传使用 zip + writeBinary + unzip，避免逐文件写入造成大量网络往返；少量文件可用 writeTree
- 跨沙箱重建持久化项目状态：使用卷、Agent Drive 或模板镜像，避免每次冷启动重新克隆仓库和安装依赖
- 空闲沙箱优先让其进入待机而非删除重建
- 使用 createIfNotExists 而非 get-then-create，避免删除后快速重建时出现 workload-not-found