celesto

环境要求

• Linux 或 macOS（Windows/macOS 桌面运行时按 README 单独创建）
• Python 3.11 或更新版本（手动安装时）
• 本地运行时需完成本机虚拟化设置，macOS 会通过 Homebrew 安装 QEMU，Linux 可能要求 sudo
• 使用 Celesto Cloud 只需 Python 包和 CELESTO_API_KEY

安装与启动步骤

1. 1一键安装 Celesto

   在 Linux 或 macOS 上执行该脚本，会安装 CLI 与 Python SDK、准备机器并检查是否就绪。

   curl -fsSL https://celesto.ai/install.sh | bash

   复制

2. 2手动安装 SDK

   不使用一键脚本时，用 pip 安装 celesto 包，注意 Python 版本需 3.11 以上。

   pip install celesto

   复制

3. 3准备并检查环境

   setup 负责准备本机（macOS 装 QEMU，Linux 可能提示 sudo），doctor 检查环境是否可用。

   celesto setup
   celesto doctor

   复制

4. 4在沙箱中运行命令

   双横线 -- 之后的内容会在沙箱内执行，示例是查看沙箱里的 Python 版本。

   celesto computer exec my-sandbox -- python --version

   复制

5. 5调用 Python API

   用 Computer 作为上下文管理器，创建沙箱后执行命令并读取 stdout 结果。

   from celesto import Computer
   
   with Computer() as computer:
       result = computer.run("python --version")
       print(result.stdout)

   复制

6. 6切换到云端沙箱

   云端不需要本机虚拟化，先导出 API Key，再把 provider 参数设为 cloud。

   export CELESTO_API_KEY="your-api-key"

   复制

7. 7选用专用运行时

   浏览器用 celesto browser；需要完整桌面时创建 desktop 实例，还可指定 windows 或 macos。

   celesto browser
   celesto computer create --desktop
   celesto computer create --os windows --image PATH
   celesto computer create --os macos

   复制

关键配置

如何确认成功

运行 celesto doctor 无报错即环境就绪；执行 celesto computer exec my-sandbox -- python --version 能输出沙箱内 Python 版本即沙箱可用。

常见问题

注意事项

• 项目处于早期阶段，接口和功能可能变动。
• OpenMuse 是预览版，需要 clone 仓库后本地运行。
• 本地 provider 适合开发、测试和私有工作负载；云端适合远程任务、持久工作区和生产负载。
• 使用低层 VM 选项（后端、通信通道、guest OS、挂载、网络策略）时直接用 Celesto(...) 构造。