CelestoAI/celesto

Celesto AI – 为 AI 代理提供安全且持久的沙盒

简介 – Celesto（前身为 SmolVM）是一个开源平台，为大型语言模型代理（如 Claude、Codex、Pi 等）提供一个私有、快速启动的虚拟电脑，让它们可以运行代码、浏览网页或使用完整的桌面环境。每个沙盒都是一个轻量级的微型虚拟机（Linux 上的 Firecracker，基于 KVM 的 Windows 客户机），可在约 500 毫秒内启动，在硬件层级将代理与主机隔离，并可在多次 API 调用之间保持运行。

重要性 – 直接在开发者的笔记本电脑上运行 AI 生成的代码具有风险。Celesto 让您能在抛弃式虚拟机中运行代码，该虚拟机可以：

• 在多次运行之间保留文件和状态，实现多步骤工作流程。
• 为“电脑使用”代理提供真实的浏览器或完整桌面。
• 强制执行严格的网络策略（关闭、限制 CIDR 或完全互联网访问）。
• 以只读或可写入方式挂载主机目录，让代理无需复制文件即可处理现有的代码库。
• 对虚拟机进行快照并恢复，或在 Python with 块结束时自动删除。

核心组件

组件	功能
Python SDK (celesto 包)	高阶 Computer / Celesto 类，用于创建、运行指令、上传文件、挂载目录、打开终端及管理浏览器。
CLI (celesto 命令)	创建、列出、停止、进入沙盒 Shell、删除沙盒；启动浏览器或桌面会话；管理 Windows/macOS 预览。
TypeScript 预览 (@celestoai/smolvm)	用于相同沙盒功能的 Node.js API，适用于以 JavaScript/TypeScript 编写的服务器端代理。
基于 Firecracker 的 Linux 微型虚拟机	次秒级启动、硬件隔离、可配置网络、快照支持。
Windows 11 客户机支持	在具备 KVM 的 Linux 主机上运行；提供 PowerShell 访问权限与并行沙盒处理。
macOS 桌面预览	在 Apple-silicon Mac 上启动临时的 macOS 桌面以进行 UI 测试（需要约 50 GB 下载）。

典型使用案例

• 安全运行 AI 生成的代码 – 运行不受信任的代码片段，而不危及主机操作系统。
• 代理的浏览器自动化 – 为 LLM 提供一个可通过 CDP、VNC 或查看器 URL 控制的即时 Chromium 实例。
• 代码库协助 – 挂载项目目录，让代理可以在沙盒内读取、编辑并提交变更。
• 具状态的多轮次工作流程 – 在多次 API 调用中保持同一个虚拟机运行，以维持上下文。
• 测试安装程序或 GUI 应用程序 – 使用 macOS 或 Linux 桌面预览来自动化 UI 交互。

入门指南（快速启动）

# 安装 alpha 包（需要 Python 3.11+）
pip install 'celesto==0.0.15a0'

# 准备主机依赖项（在 Linux 上可能需要 sudo）
celesto setup
celesto doctor   # 健全性检查

from celesto import Computer

# 一次性沙盒，打印消息
with Computer(local=True) as comp:
    out = comp.run("echo 'Hello from the sandbox!'")
    print(out.stdout)

当 with 块结束时，沙盒会消失。若要使用持久性虚拟机，请以 lifetime="persistent" 创建，并稍后通过 Computer.get(id, local=True) 重新连接。

在云端运行 – 设置 CELESTO_API_KEY 并省略 local=True。相同的 Python API 即可运行；云端使用可能会产生费用。

CLI 示例

# 创建、列出并停止沙盒
celesto sandbox create --name demo
celesto sandbox list
celesto sandbox stop demo

# 打开交互式 Shell
celesto sandbox shell demo

# 运行单个指令（在脚本中很有用）
celesto sandbox exec demo -- python --version

浏览器沙盒 – 启动可见的 Chromium 实例并即时观看：

celesto browser start --live
# 查看器 URL 和 VNC URL 会被打印出来；在浏览器中打开查看器以查看会话。

在 Python 中：

from celesto import Celesto
with Celesto.browser(headless=False) as b:
    print(b.viewer_url)   # 打开以观看
    print(b.cdp_url)      # 提供给 Playwright / CDP 工具

Windows 沙盒 – 需要具备 KVM 的 Linux 主机。从 ISO 创建镜像或使用预先制作的 QCOW2：

celesto windows build-image --iso Win11.iso --virtio-win-iso virtio-win.iso --output ~/.smolvm/images/win11.qcow2

然后使用 os="windows" 的 Python API。

安全性与隔离

• 每个沙盒都在自己的虚拟机中运行（硬件层级隔离）。
• 网络可以完全禁用或限制为特定的 CIDR 块。
• 文件系统挂载默认为只读；可写入挂载必须明确请求。
• 快照可捕获完整的内存、磁盘和进程状态，以便稍后恢复。

文档与社区

• 完整文档：https://docs.celesto.ai
• 快速启动、API 参考，以及关于网络、macOS、Windows 和浏览器沙盒的指南。
• Discord 社区支持：https://discord.gg/KNb5UkrAmm

成熟度 – 该项目目前处于 alpha 版本 (0.0.15a0)。核心 Linux 微型虚拟机功能稳定，而 Windows 和 macOS 预览版仍处于实验阶段。CI 徽章显示测试和 CodeQL 扫描皆已通过。

---

总结 – Celesto 提供了基础架构，让基于 LLM 的代理拥有自己的快速、隔离的电脑，无论您需要无头指令执行器、完整浏览器还是桌面 UI。它抽象化了虚拟机配置、网络和持久性，让开发者能专注于安全地构建 AI 驱动的工作流程。