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 驅動的工作流程。