Skip to main content
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.
Follow the first Session 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. Select a validated Modal or Fly Machines connection and the exact MiniMax-M3 protocol entry in the verification registry. 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 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. 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, image contract, registration. Next: Harness adapters, verified combinations, security boundaries.