> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装并启动本地控制平面

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

## 准备环境

* Node.js 22.19.0 或更高版本。
* 已运行的 PostgreSQL，以及能够在专用数据库中创建表的身份。
* 使用 Python SDK 时需要 Python 3.10 或更高版本。
* 使用临时开发凭据入口时需要 `cloudflared`；Instabox 需要 OpenSSH 客户端。
* 一个可用的云 Sandbox 账户和模型端点，用于后续真实任务。

当前仓库提供本地构建与安装方式。不要假设同名 npm / PyPI 包已经公开发布。控制平面安装不会自动安装 PostgreSQL，也不会自动创建供应商账户。

## 启动

克隆主仓库并进入目录。若已有此仓库检出，从仓库根目录的 `npm ci` 开始：

```sh theme={null}
git clone https://github.com/NexusFox88/Hexagon.git
cd Hexagon
npm ci
export DATABASE_URL='postgres://YOUR_USER@127.0.0.1:5432/hexagon'
npm run local -- doctor
npm run local -- start
npm run local -- status
```

将连接串替换为你已创建的专用数据库。不要复用其他应用的数据库。未设置 `DATABASE_URL` 时，开发默认值是 `postgres://hexagon@127.0.0.1:55432/hexagon`，这不表示该数据库已经存在。

`doctor` 检查前提条件；启动器运行数据库迁移并管理本地服务。若启动失败，先检查数据库连接和报告中的缺失依赖，再重试。保留已有数据目录和对应加密密钥，不通过删除它们来处理云资源未知状态。

打开 [本地 Console](http://127.0.0.1:8787/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 入口或明确选择的开发隧道见[网络指南](https://docs.hexagon.autos/zh-CN/operate/networking.md)。管理专用的 disabled 模式不能完成受保护云执行。

## 安装 SDK

Python 建议使用独立虚拟环境：

```sh theme={null}
python3 -m venv .local/docs-example-venv
.local/docs-example-venv/bin/python -m pip install -e sdk/python
```

教程使用这个明确的 Python 路径，换一个终端也无需重新激活环境。若使用其他虚拟环境，请在后续命令中一致地替换解释器路径。

TypeScript 从仓库构建：

```sh theme={null}
npm --prefix sdk/typescript run build
```

仓库内程序可导入 `sdk/typescript/dist/index.js`。独立应用可以使用[本地包构建与安装流程](https://github.com/NexusFox88/docs/blob/main/resources/docs/local-installation.md#local-package-distribution)。

Python 使用 `Hexagon.local()`，TypeScript 使用 `await Hexagon.local()` 发现当前工作区，不需要手工复制 owner token。多个工作区时显式指定 Python 的 `data_directory` 或 TypeScript 的 `dataDirectory`。远程 hosted 连接使用明确 URL 和 Token，不使用本地发现身份。

## 分层判断是否准备完成

| 检查 | 通过依据 | 未就绪时处理 |
| - | - | - |
| `doctor` 的 Node／database 字段 | Node 版本满足要求，数据库连接探测成功 | 启动前先修正运行环境或专用数据库连接 |
| `doctor` 的可选依赖字段 | 按路径需要具备 Python SDK 所用 Python、Instabox 所用 OpenSSH、开发入口所用 cloudflared | 安装所选路径需要的依赖；退出码为零不证明所有字段都已 ready |
| `status` | 取得已鉴权健康响应，API／数据库 ready，执行与凭据状态可用 | 检查私有服务日志及失败子系统；`unreachable` 与 `stopped` 不同 |
| Console | 工作区打开，预期的已保存连接元数据可见 | 核对启动器报告的真实 URL、选定工作区及本地身份 |
| SDK 导入 | 本地包能由目标解释器／运行环境加载 | 修正虚拟环境或重新构建 TypeScript 包 |
| 首个云任务 | 后续教程观察到完成的 Run、有效产物和已确认清理 | 调查原 ID；本地安装本身没有验证这一层 |

当前 `doctor` 在 Node 不满足要求或数据库不可达时返回失败退出码。Python、OpenSSH 或 cloudflared 缺失会体现在 JSON 字段中，但命令仍可能返回零。它检查的是命令可用性，不证明所有支持版本或 Provider 行为；数据库连接探测也不证明拥有迁移权限，启动时仍需成功应用迁移。

本页命令采用 POSIX 风格 shell 和本地路径，不代表已经认证干净 Windows 安装或全部操作系统／包管理器组合。[本地安装契约](https://github.com/NexusFox88/docs/blob/main/resources/docs/local-installation.md)说明启动器与分发边界；应使用能实际验证的环境，不从 SDK 可用直接推断操作系统支持。

完成 SDK 安装／构建步骤后，可以运行以下导入检查；它们不创建 Session、不调用模型，也不分配云资源：

```sh theme={null}
.local/docs-example-venv/bin/python -c 'from hexagon import Hexagon; print("Python SDK import OK")'
node --input-type=module -e 'import { Hexagon } from "./sdk/typescript/dist/index.js"; console.log(typeof Hexagon === "function" ? "TypeScript SDK import OK" : "Unexpected SDK export")'
```

Python 包的最低解释器版本与控制平面的 Node 要求是不同前提。运行仓库教程时，即使 SDK 包声明的最低 Node 版本更低，也应采用控制平面的 Node 要求。

## 确认完成与停止

安装阶段完成的信号是：`status` 显示服务可用，Console 可访问，数据库和工作区身份可用。真实运行还需要连接验证、云资源创建和一次任务执行；不要将安装成功记录成完整云旅程通过。

计划停止前，完成或取消活动 Run，并关闭不再使用的云 Session，确认资源清理：

```sh theme={null}
npm run local -- stop
```

停止本地控制平面不等于删除云 Sandbox。依赖控制平面执行的到期清理在服务停止期间无法按时执行。

下一步按[首个 Session](https://docs.hexagon.autos/zh-CN/start/first-session.md)或 API Playground 创建 Session；日常管理见[本地工作区](https://docs.hexagon.autos/zh-CN/operate/local-workspace.md)，部署、代理、备份与恢复的底层契约见[本地启动器说明](https://github.com/NexusFox88/docs/blob/main/resources/docs/local-installation.md)。

## 已记录的安装范围

[11 月 20 日隔离源码安装检查](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-20-docs-isolated-install.json)从当前工作区副本开始，副本没有 `node_modules`，使用全新数据目录和专用数据库。`npm ci`、doctor/start/status、Python 虚拟环境安装、TypeScript 构建、双 SDK 本地发现、重启与停止均通过。已保存的定义、owner 身份和加密密钥在重启后保持；服务已停止，临时数据库已移除。

执行环境是已有 macOS 主机，预装 Node 24.8.0、Python、PostgreSQL、OpenSSH、cloudflared，并保留包缓存；这不是全新操作系统安装声明。管理启动阶段有意不配置凭据入口。真实云任务继续按首个 Session 教程执行，其独立双 SDK 云证据具有自己的配置范围。验证脚本首轮误设了不支持的 tunnel 环境值，失败记录单独保留，随后纠正并完成检查。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.