> ## 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.

# 接入 Fly Machines

Fly Machines 与 Fly Sprites 是两个独立 Provider。这里使用 `fly-machines`：每个 Session 创建专属 App、私有网络和 Machine。平台记录的持久资源 ID 是 App ID，因此 Machine 创建响应丢失时，已创建的 App 仍需保留并对账。

## 配置与权限

准备能够访问目标 organization、创建和删除 App/Machine、使用私有代理的 Token。仅有某个无关 App 的权限不够。控制平面主机还需要 PATH 中的 `fly` 命令和可用的私有网络传输；列表验证不能证明这条通道可用。

| 字段 | 默认值 | 约束 |
| - | - | - |
| organization | personal | 小写字母、数字、连字符 |
| region | iad | 小写字母或数字 |
| memory\_mb | 4096 | 2048—16384 的整数 |

当前 Machine 使用 shared CPU、2 vCPU，不能通过未定义的 config 字段覆盖。配置中不接受已有 App 名，避免把用户共享资源当 Session 专属资源。

下面使用本地管理客户端；hosted 初始化见[自托管](https://docs.hexagon.autos/zh-CN/operate/self-host.md)。key 从私有环境读取并保留在控制平面。示例创建新连接，保存 ID 后复用。

```python theme={null}
import os
from hexagon import Hexagon
client = Hexagon.local()
connection = client.create_connection(
    kind="sandbox", provider="fly-machines", name="Fly workspace",
    credential=os.environ["FLY_API_TOKEN"],
    config={"organization": os.environ["FLY_ORGANIZATION"],
            "region": "iad", "memory_mb": 4096},
)
checked = client.validate_connection(connection["id"])
if checked["status"] != "ready":
    raise RuntimeError("Inspect Fly connection diagnostics")
client.update_connection(connection["id"], enabled=True)
```

```typescript theme={null}
import { Hexagon } from '@hexagon/agent-sdk';
const client = await Hexagon.local();
const credential = process.env.FLY_API_TOKEN;
const organization = process.env.FLY_ORGANIZATION;
if (!credential || !organization) throw new Error('Set Fly account configuration');
const connection = await client.createConnection({
  kind: 'sandbox', provider: 'fly-machines', name: 'Fly workspace', credential,
  config: { organization, region: 'iad', memory_mb: 4096 },
});
const checked = await client.validateConnection(connection.id);
if (checked.status !== 'ready') throw new Error('Inspect Fly connection diagnostics');
await client.updateConnection(connection.id, { enabled: true });
```

验证只列举 organization 的 App。ready 后明确启用；配置或凭据变化后重新验证、启用。已有 Session 保留固定配置。

## 内置与公开 OCI

内置 Harness 路线使用 `node:24-bookworm` 基础镜像。按[首个 Session](https://docs.hexagon.autos/zh-CN/start/first-session.md)使用 connection.id、兼容模型和 Harness 完成任务与产物。

公开 OCI 通过[镜像注册指南](https://docs.hexagon.autos/zh-CN/integrations/harnesses/oci.md)选择固定 digest。可参考当前注册证据中的 OpenCode 镜像：

`ghcr.io/anomalyco/opencode@sha256:763ea3bce6bdaee6d6092775c83c03a90b11b2a74dcfb89942a4cb82a99f974e`

使用匹配的 opencode-v1 协议与 command，并从[精确组合记录](https://github.com/NexusFox88/docs/blob/main/resources/modules/harnesses/verification.ts)确认模型、SDK 和场景。登记 digest 不代表本次已运行验证；按双 SDK 分别提交任务、检查文件产物、所需 Tools 与清理。

当前不支持私有镜像，提供 registry credential 会被拒绝。镜像可能需要在 VM 内安装 Python、Bash、timeout 等依赖；支持 Alpine / Debian 系准备，其他包管理器可能失败。命令以 root 执行，镜像 USER 不是已验证隔离边界。源 digest 不代表准备后的文件系统完全未变。镜像默认入口不会自动执行，Runtime 启动注册命令。

## 私有访问与限制

没有公开 services，也不继承已有 App secrets 或 volumes。每个 App 使用自己的私有网络。预览由控制平面启动 `fly proxy`，绑定本机 loopback，经私有网络到目标 Machine；不是把账户 Token 或 Provider URL 交给浏览器。用户使用[Hexagon 预览授权](https://docs.hexagon.autos/zh-CN/build/private-preview.md)。

本地代理监听成功不证明 WireGuard、DNS 和 guest 服务已就绪。诊断时逐层核查，不能只看本地端口。当前不声明 network\_allowlist，需要受限出站的任务应选择支持的 Provider。

连接器文件读取最多 64 MiB，按块核验字节数；上层接口可能更小。前台命令最多 590 秒，后台最多 3600 秒；这不是整个 Run 的时长定义。

## suspend/start 与冷启动

空闲采用 suspend，下一轮 submit 自动 start。Fly 可能在没有可用内存快照时冷启动，因此文档依赖边界是文件系统，而非进程内存。Runtime、对话和预览服务分别检查，不能承诺任意后台进程延续。

恢复选择专属 App 中当前唯一的 Machine，获取该 Machine 的 lease 后重新读取状态，以防止旧请求竞争。它接受 started 或 suspended，拒绝 stopped 或多 Machine 状态，也不会创建替代计算资源。但这一步本身不会与另行持久保存的原始 Machine ID 比较；执行命令时还会检查 Machine 的 operation metadata 与 App operation 是否一致。empty / ambiguous 表示 App 存在但资源结构异常，需要调查。不要手工替换其中的 Machine。

按[空闲与唤醒](https://docs.hexagon.autos/zh-CN/build/idle-and-wake.md)验证两轮文件与对话，记录精确镜像和模型协议。不要手工替换 Machine 来掩盖恢复失败。

## 分开判断资源观察结果

| 观察结果 | 能证明什么 | 下一步 |
| - | - | - |
| App 存在，Machine 列表为空 | 仍有部分创建的资源归平台管理 | 保留 App ID，对账或关闭该 Session |
| 唯一 Machine 为 suspended | 计算已暂停，尚未删除 | 向同一 Session 提交任务，唤醒后验证文件与 Runtime |
| 唯一 Machine 为 stopped | 不属于当前接受的恢复状态 | 调查原资源，不用替换 Machine 掩盖失败 |
| App 查询成功后，Machine 列表返回 404 | 子资源查询失败，不能证明 App 不存在 | 保留不确定状态，再检查 App |
| close 后专属 App 查询明确返回 404 | 平台拥有的资源组不存在 | 再核对平台清理完成状态与保留产物 |

[11 月 18 日 MiniMax 矩阵](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-18-minimax-matrix.md)记录了 Fly Machines 上的公开 OCI 任务，包括固定 digest 的 OpenCode 组合。验证范围是双 SDK 的原生对话继续、远程 Tool、环境、产物与清理，不代表每个单元都重新执行了 Web/预览或空闲旅程。使用精确组合记录中的镜像、协议和模型条目，不能仅凭镜像名称推断兼容。

## 清理与对账

close 关闭本地代理并删除 Session 专属 App，然后确认 App 不存在。这覆盖平台拥有的那组资源，不是删除组织内所有 App。不要把无关资源加入该专属 App，也不要对用户共享 App 复用这套删除操作。

创建部分成功也可能留下 empty App；Machine 不存在不能证明 App 已清理。网络失败不等于不存在，Provider 明确 404 才按缺失处理。保留原 App/operation ID，按[资源对账](https://docs.hexagon.autos/zh-CN/operate/reconciliation.md)核查，不能在未知结果后盲建新 App。

常见诊断：fly\_machine\_not\_ready 检查唯一 Machine、状态和归属；fly\_resume\_state\_pending 检查原 Machine 状态；harness\_runtime\_prerequisites\_unavailable 检查镜像准备；fly\_app\_deletion\_unconfirmed 检查原 App 的删除结果。

本页核对了连接器与私有代理实现，没有新执行云任务。历史范围见[执行矩阵](https://github.com/NexusFox88/docs/blob/main/resources/testing/execution-matrix.md)及[serverless 矩阵](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-19-harness-serverless-matrix.json)。

依据：[镜像生命周期](https://github.com/NexusFox88/docs/blob/main/resources/docs/harness-images.md)、[连接器](https://github.com/NexusFox88/docs/blob/main/resources/integrations/sandboxes/fly-machines.ts)、[私有代理](https://github.com/NexusFox88/docs/blob/main/resources/integrations/sandboxes/fly-machines-proxy.ts)。下一步：[OCI Harness](https://docs.hexagon.autos/zh-CN/integrations/harnesses/oci.md)、[空闲与唤醒](https://docs.hexagon.autos/zh-CN/build/idle-and-wake.md)、[清理对账](https://docs.hexagon.autos/zh-CN/operate/reconciliation.md)。


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