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

# Register and run an OCI Harness

New Harness integrations use OCI images. Registration resolves metadata and pins a Linux amd64 manifest digest. It is not Agent execution or proof of runtime success.

Use an owner identity, an approved Docker Hub/GHCR reference, and compatible Sandbox/model connections. Arbitrary registry URLs are not supported fetch targets.

## Register and preflight

Continue with an initialized management client. The reference must contain a real matching program; this example selects opencode-v1.

```python theme={null}
harness = client.register_harness(
    image="ghcr.io/anomalyco/opencode@sha256:763ea3bce6bdaee6d6092775c83c03a90b11b2a74dcfb89942a4cb82a99f974e", id='custom.project-agent', version='1.0.0',
    protocol='opencode-v1', command=['opencode'], capabilities=['conversation', 'tools'],
)
definition = dict(harness={'id': harness['id'], 'version': harness['version']},
                  sandbox_connection_id=sandbox_connection_id,
                  model_connection_id=model_connection_id)
check = client.preflight_session(**definition)
if not check['ready']:
    raise RuntimeError('Review compatibility before creating the Session')
session = client.create_session(**definition)
```

```typescript theme={null}
const harness = await client.registerHarness({
  image: 'ghcr.io/anomalyco/opencode@sha256:763ea3bce6bdaee6d6092775c83c03a90b11b2a74dcfb89942a4cb82a99f974e', id: 'custom.project-agent', version: '1.0.0',
  protocol: 'opencode-v1', command: ['opencode'], capabilities: ['conversation', 'tools'],
});
const definition = { harness: { id: harness.id, version: harness.version },
  sandbox_connection_id: sandboxConnectionId, model_connection_id: modelConnectionId };
const check = await client.preflightSession(definition);
if (!check.ready) throw new Error('Review compatibility before creating the Session');
const session = await client.createSession(definition);
```

Follow the [first Session](https://docs.hexagon.autos/en/start/first-session.md) persistent-submission pattern for execution, artifact checks, and cleanup. Record the returned digest, not only the mutable tag. Identical registration is idempotent; changed id/version conflicts require a new version. Source packages share that namespace.

Command defaults to Entrypoint + Cmd; protocol comes from the image label or default JSON contract. Inspect defaults rather than assuming an arbitrary CLI image works.

## Keep image identity separate from version labels

Registration records the resolved Linux amd64 image digest, the executable command, protocol, capabilities and optional registry Secret reference. The Harness `id`/`version` is your stable selection key; a mutable registry tag is only an input to resolution. Moving that tag later does not silently update an existing registration or Session.

If omitted, protocol comes from `ai.hexagon.harness.protocol` or defaults to `hexagon-json-v1`; command comes from image Entrypoint plus Cmd. Neither default proves that the program implements the chosen protocol. The default capability list contains only conversation. Declare Tools or initialization only when the adapter and program actually support them; registration rejects combinations such as Tools for Aider and initialization for Aider/DeepSeek.

For a release, build and verify the image, record its resolved digest, register a new id/version when the definition changes, then run a dedicated Session before selecting that version for application traffic. A repeated id/version whose resolved definition differs returns `harness_version_conflict`; do not treat that conflict as permission to overwrite a working version. Source packages and OCI registrations share the version namespace.

Record three different checkpoints: registration resolved metadata; the Provider prepared and started that image; the Harness completed the required behavior. A registry manifest alone proves only the first. Image preparation can modify Runtime prerequisites, so record runtime identity and behavior separately from the source digest.

## Scope of the pinned example

The image and explicit `opencode` command above match the [November 18 MiniMax matrix](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-18-minimax-matrix.md). Select a validated Modal or Fly Machines connection and the exact MiniMax-M3 protocol entry in the [verification registry](https://github.com/NexusFox88/docs/blob/main/resources/modules/harnesses/verification.ts). That record covers both SDKs, continuation, remote Tool, environment, artifacts and cleanup; this page does not claim a fresh pull or execution. Registry access and your current account still need verification.

Before creating resources, keep the failed preflight diagnostics if you select a non-OCI Provider; do not remove compatibility checks or substitute another image to conceal the failure. Registering the same definition again should return the same selection. Changing the command under the same id/version should conflict; register a new version for that change. Neither exercise proves a model task succeeded. Follow the complete tutorial for persisted submission, output and artifact verification, then confirm cleanup of compute and any Provider-owned preparation resource.

The [combined Harness evidence review](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-20-docs-harness-reuse.json) matches this exact digest to independent Python and TypeScript Modal journeys with artifact verification and confirmed cleanup. Current isolated database checks separately reject unsupported image providers before any Session or resource operation is created. These checks do not constitute a new pull or cloud run.

## Provider boundaries

Modal and Fly Machines support native OCI, with public images only on Fly. E2B now prepares public OCI through a Session-owned Template, with separate build/create records and compute-before-template cleanup. Its additional combinations remain individually unverified until evidence exists.

Modal derives Runtime prerequisites as root. Current code reapplies image USER, while existing runtime notes report root execution; USER is not a verified security boundary. Verify actual uid when identity matters; see [Modal integration](https://docs.hexagon.autos/en/integrations/sandboxes/modal.md). Fly may also install prerequisites and execute as root. Source-image digest does not mean the runtime filesystem was never changed during preparation.

Private registry access uses an enabled username/password JSON Secret, not ordinary Agent environment. Private-image capability is separate from public OCI. Verify resolution, pull, execution, Tools, and cleanup independently.

## Build and diagnose

`node --import tsx tooling/build-harness-images.ts all` builds repository templates without pushing. It may download dependencies and create local images; inspect template prerequisites. A recipe is not a published artifact.

Distinguish missing entrypoint, architecture, registry authorization, Runtime prerequisites, model protocol, and result interpretation. Lost build receipts require reconciliation of the original operation, not automatic duplicate builds. Retain and clean up failed templates/resources.

Sources: [OCI design](https://github.com/NexusFox88/docs/blob/main/resources/docs/oci-harness-design.md), [image contract](https://github.com/NexusFox88/docs/blob/main/resources/docs/harness-images.md), [registration](https://github.com/NexusFox88/docs/blob/main/resources/modules/harnesses/images.ts). Next: [Harness adapters](https://docs.hexagon.autos/en/contribute/harness-adapters.md), [verified combinations](https://docs.hexagon.autos/en/integrations/verified-combinations.md), [security boundaries](https://docs.hexagon.autos/en/concepts/security-boundaries.md).


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