跳转到主要内容
本教程从源码检出启动 Hexagon。完成后,你可以打开 Console,配置云 Sandbox 和模型连接,并使用本地 SDK 自动发现工作区。

准备环境

  • Node.js 22.19.0 或更高版本。
  • 已运行的 PostgreSQL,以及能够在专用数据库中创建表的身份。
  • 使用 Python SDK 时需要 Python 3.10 或更高版本。
  • 使用临时开发凭据入口时需要 cloudflared;Instabox 需要 OpenSSH 客户端。
  • 一个可用的云 Sandbox 账户和模型端点,用于后续真实任务。
当前仓库提供本地构建与安装方式。不要假设同名 npm / PyPI 包已经公开发布。控制平面安装不会自动安装 PostgreSQL,也不会自动创建供应商账户。

启动

克隆主仓库并进入目录。若已有此仓库检出,从仓库根目录的 npm ci 开始:
将连接串替换为你已创建的专用数据库。不要复用其他应用的数据库。未设置 DATABASE_URL 时,开发默认值是 postgres://hexagon@127.0.0.1:55432/hexagon,这不表示该数据库已经存在。 doctor 检查前提条件;启动器运行数据库迁移并管理本地服务。若启动失败,先检查数据库连接和报告中的缺失依赖,再重试。保留已有数据目录和对应加密密钥,不通过删除它们来处理云资源未知状态。 打开 本地 Console。默认私有数据目录为 .local/control-plane,可以通过 HEXAGON_DATA_DIR 指定。保留数据库时必须同时保留对应加密密钥。

配置第一个执行组合

  1. 在 Infrastructure 的 Sandbox 页面创建连接,填写所选 Provider 所需信息,验证并启用。
  2. 在 LLM 页面配置模型端点、模型标识、协议和凭据,验证并启用。
  3. 在 API Playground 中选择兼容 Harness 和上述连接,生成 Python 或 TypeScript 程序。
无需先创建 Agent 模板。云 Sandbox 必须能访问凭据通道。Console 能打开并不单独证明云执行网络可用。Settings → Network & ingress 管理保存的部署设置,修改后重启;稳定外部 HTTPS 入口或明确选择的开发隧道见网络指南。管理专用的 disabled 模式不能完成受保护云执行。

安装 SDK

Python 建议使用独立虚拟环境:
教程使用这个明确的 Python 路径,换一个终端也无需重新激活环境。若使用其他虚拟环境,请在后续命令中一致地替换解释器路径。 TypeScript 从仓库构建:
仓库内程序可导入 sdk/typescript/dist/index.js。独立应用可以使用本地包构建与安装流程。 Python 使用 Hexagon.local(),TypeScript 使用 await Hexagon.local() 发现当前工作区,不需要手工复制 owner token。多个工作区时显式指定 Python 的 data_directory 或 TypeScript 的 dataDirectory。远程 hosted 连接使用明确 URL 和 Token,不使用本地发现身份。

分层判断是否准备完成

当前 doctor 在 Node 不满足要求或数据库不可达时返回失败退出码。Python、OpenSSH 或 cloudflared 缺失会体现在 JSON 字段中,但命令仍可能返回零。它检查的是命令可用性,不证明所有支持版本或 Provider 行为;数据库连接探测也不证明拥有迁移权限,启动时仍需成功应用迁移。 本页命令采用 POSIX 风格 shell 和本地路径,不代表已经认证干净 Windows 安装或全部操作系统/包管理器组合。本地安装契约说明启动器与分发边界;应使用能实际验证的环境,不从 SDK 可用直接推断操作系统支持。 完成 SDK 安装/构建步骤后,可以运行以下导入检查;它们不创建 Session、不调用模型,也不分配云资源:
Python 包的最低解释器版本与控制平面的 Node 要求是不同前提。运行仓库教程时,即使 SDK 包声明的最低 Node 版本更低,也应采用控制平面的 Node 要求。

确认完成与停止

安装阶段完成的信号是:status 显示服务可用,Console 可访问,数据库和工作区身份可用。真实运行还需要连接验证、云资源创建和一次任务执行;不要将安装成功记录成完整云旅程通过。 计划停止前,完成或取消活动 Run,并关闭不再使用的云 Session,确认资源清理:
停止本地控制平面不等于删除云 Sandbox。依赖控制平面执行的到期清理在服务停止期间无法按时执行。 下一步按首个 Session或 API Playground 创建 Session;日常管理见本地工作区,部署、代理、备份与恢复的底层契约见本地启动器说明。

已记录的安装范围

11 月 20 日隔离源码安装检查从当前工作区副本开始,副本没有 node_modules,使用全新数据目录和专用数据库。npm ci、doctor/start/status、Python 虚拟环境安装、TypeScript 构建、双 SDK 本地发现、重启与停止均通过。已保存的定义、owner 身份和加密密钥在重启后保持;服务已停止,临时数据库已移除。 执行环境是已有 macOS 主机,预装 Node 24.8.0、Python、PostgreSQL、OpenSSH、cloudflared,并保留包缓存;这不是全新操作系统安装声明。管理启动阶段有意不配置凭据入口。真实云任务继续按首个 Session 教程执行,其独立双 SDK 云证据具有自己的配置范围。验证脚本首轮误设了不支持的 tunnel 环境值,失败记录单独保留,随后纠正并完成检查。