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

# Connect Fly Machines

Fly Machines and Fly Sprites are independent providers. Use `fly-machines` here: each Session owns a dedicated App, private network, and Machine. The durable resource ID is the App ID. An App created before a lost Machine response must still be retained and reconciled.

## Configuration and permissions

Use a Token authorized for the target organization, App/Machine creation/deletion, and private proxy access. Access to an unrelated App alone is insufficient. The control-plane host also needs `fly` on PATH and functioning private transport. Listing validation does not prove that transport works.

| Field | Default | Constraint |
| - | - | - |
| organization | personal | Lowercase letters, digits, hyphens |
| region | iad | Lowercase letters or digits |
| memory\_mb | 4096 | Integer, 2048–16384 |

Machines currently use shared CPU with 2 vCPU; undefined config fields cannot override it. Configuration does not accept an existing App name, avoiding accidental ownership of shared resources.

These examples use local management clients; see [self-hosting](https://docs.hexagon.autos/en/operate/self-host.md) for hosted initialization. The private key stays in the control plane. Retain the created connection ID rather than recreating it.

```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 });
```

Validation only lists organization Apps. Explicitly enable after ready validation; revalidate/enable after configuration or key changes. Existing Sessions remain pinned.

## Built-in and public OCI execution

Built-in Harnesses use `node:24-bookworm`. Follow the [first Session](https://docs.hexagon.autos/en/start/first-session.md) with connection.id and a compatible model/Harness, verifying execution and artifacts.

For public OCI, follow [image registration](https://docs.hexagon.autos/en/integrations/harnesses/oci.md) and pin a digest. An OpenCode image in current scoped records is:

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

Use matching opencode-v1 protocol/command and inspect [exact combination records](https://github.com/NexusFox88/docs/blob/main/resources/modules/harnesses/verification.ts) for models, SDKs, and scenarios. Registration is not a fresh execution pass. Independently verify both SDKs, task, files, required Tools, and cleanup.

Private images are unsupported; registry credentials are rejected. The VM may install Python, Bash, timeout, and other prerequisites using Alpine/Debian-family package managers. Unsupported preparation fails. Commands execute as root; image USER is not a verified isolation boundary. The source digest does not describe an unchanged prepared filesystem. The default image entrypoint is not automatically run; Runtime launches the registered command.

## Private access and limits

No public services are configured; existing App secrets or volumes are not inherited. Each App has its own private network. The control plane launches `fly proxy` on loopback to reach the specific Machine privately. Browsers use [Hexagon preview authorization](https://docs.hexagon.autos/en/build/private-preview.md), never account Tokens or raw provider URLs.

A listening local proxy does not establish WireGuard, DNS, or guest readiness. Diagnose each layer. The connector does not declare network\_allowlist; choose another provider when domain restrictions are required.

File reads are capped at 64 MiB with chunk checks; higher layers may impose smaller limits. Foreground commands allow at most 590 seconds and background commands 3600 seconds. These are not total Run duration limits.

## suspend/start and cold boot

Idle uses suspend; the next submit starts the Machine automatically. Fly can cold-boot without a usable memory snapshot, so the dependable boundary is filesystem state rather than process memory. Check Runtime, conversation, and preview services separately; arbitrary background processes are not guaranteed to continue.

Restore selects the currently unique Machine in the owned App, acquires its lease, and rereads its state to fence stale requests. It accepts started or suspended, rejects stopped or multiple Machines, and does not create replacement compute. This step alone does not compare against a separately persisted original Machine ID. Command execution additionally requires the Machine operation metadata to match the App operation. Empty/ambiguous means the App exists with an unexpected resource structure requiring investigation. Do not manually replace its Machine.

Use [idle and wake](https://docs.hexagon.autos/en/build/idle-and-wake.md) to verify two-turn files/conversation with exact image/model records. Do not manually replace compute to hide recovery failures.

## Read resource observations separately

| Observation | What it establishes | Next action |
| - | - | - |
| App exists, Machine list is empty | Partial resource ownership remains | Keep the App ID and reconcile or close that Session |
| Unique Machine is suspended | Compute is paused, not deleted | Submit to the same Session; verify files and Runtime after wake |
| Unique Machine is stopped | Not an accepted resume state | Investigate the original resource; do not replace it to hide failure |
| Machine listing fails with 404 after App lookup succeeded | A failed child lookup, not confirmed App absence | Preserve uncertainty and inspect the App again |
| Dedicated App lookup confirms 404 after close | The owned resource group is absent | Check platform cleanup completion and retained artifacts |

The [November 18 MiniMax matrix](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-18-minimax-matrix.md) records public OCI tasks on Fly Machines, including pinned OpenCode combinations. Its scope is native continuation, remote Tool, environment, artifacts and cleanup through both SDKs; it does not certify a fresh Web/preview or idle journey for each cell. Use the exact image/protocol/model entry in the linked combination records, rather than treating the image name as a compatibility guarantee.

## Cleanup and reconciliation

Close releases local proxies, deletes the Session-owned App, and confirms App absence. This applies only to that dedicated resource group, not every App in the organization. Do not add unrelated resources to it or reuse this deletion flow on shared Apps.

Partial creation can leave an empty App; absent compute does not establish App cleanup. Transport failure is not absence; explicit provider 404 is. Preserve original App/operation IDs and [reconcile](https://docs.hexagon.autos/en/operate/reconciliation.md) without blindly creating another App after uncertainty.

For fly\_machine\_not\_ready, inspect unique Machine/state/ownership. For fly\_resume\_state\_pending, inspect the original state. For harness\_runtime\_prerequisites\_unavailable, inspect image preparation. For fly\_app\_deletion\_unconfirmed, inspect original App deletion.

This page is source-reviewed without new cloud execution. Historical scope is in the [execution matrix](https://github.com/NexusFox88/docs/blob/main/resources/testing/execution-matrix.md) and [serverless ledger](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-19-harness-serverless-matrix.json).

Sources: [image lifecycle](https://github.com/NexusFox88/docs/blob/main/resources/docs/harness-images.md), [connector](https://github.com/NexusFox88/docs/blob/main/resources/integrations/sandboxes/fly-machines.ts), [private proxy](https://github.com/NexusFox88/docs/blob/main/resources/integrations/sandboxes/fly-machines-proxy.ts). Next: [OCI Harness](https://docs.hexagon.autos/en/integrations/harnesses/oci.md), [idle and wake](https://docs.hexagon.autos/en/build/idle-and-wake.md), [reconciliation](https://docs.hexagon.autos/en/operate/reconciliation.md).


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