Skip to main content
Catalog discovery is available to owner/application tokens; both registration routes require an owner. Registrations are tenant-scoped. Registration is not a Sandbox launch, model test or certification of a declared capability.

Discover catalogs

GET /v1/catalog returns 200, {connections,harnesses,harness_templates,harness_protocols}, with no pagination. Connections contains adapter kind/provider/capabilities and optional setup_url/evidence. Harnesses contains tenant-visible executable definitions; harness_templates is a separate template collection, not a promise that every image is registered or available. Harness_protocols describes adapter protocol contracts.
Harness entries include their source definition plus protocol, model_providers, continuation, distribution and verification. The current projection computes distribution from image, recipe and source metadata; do not use that label alone as proof of installation. Verification entries match exact image reference, protocol and command and include their Sandbox/model/client/scenario scope. An empty verification array means this projection has no matching evidence, not necessarily that execution is impossible. Choose compatible connections and preflight the actual Session.

Register an OCI Harness

POST /v1/harnesses accepts a strict object: Accepted references use Docker Hub or GHCR repository syntax, not arbitrary URLs. python:3.12 expands to Docker Hub’s library/python; org/image:tag defaults to Docker Hub; explicit docker.io/... and ghcr.io/... are supported. An omitted tag/digest selects latest. A digest selector must be @sha256: followed by 64 lowercase hexadecimal characters. HTTP(S) schemes, custom registry hosts and host ports are rejected. Prefer an immutable digest for a repeatable registration; a syntactically valid reference still needs a real image implementing the selected Harness protocol. For private registry authentication, the managed Secret value must be strict JSON {username,password} with nonempty strings. Do not put registry secrets into image URLs or request logs. The resolver checks the supported image/platform contract; current registrations pin linux/amd64. See OCI integration for runnable image requirements. Save your actual image definition as harness-image.json:
Success returns 201 with id/version/name, source=oci, protocol, effective capabilities/model_providers, image (reference/digest/platform/user and optional registry_secret_id), command and registration_digest. It contacts a registry and saves a resolved definition; it does not execute the image. Tools/initialization must be supported by the selected protocol, and a missing resolved command returns 400 harness_entrypoint_missing. The immutable key is tenant/id/version. Re-registering an identical resolved definition returns it; different content at the same key yields 409 harness_version_conflict. Image tags can move between requests, so preserve the returned digest and use an immutable image reference. OCI and source packages share this version namespace. No public update/delete route is defined here.

Register a source package

POST /v1/harness-packages accepts a strict object: Paths are at most 240 characters, begin with an alphanumeric/underscore/hyphen and use alphanumeric, underscore, dot, slash or hyphen characters. Empty/./.. segments, duplicate paths and file/directory collisions are rejected. Content is text, not Base64, ≤262,144 JavaScript string code units per file; total UTF-8 content is at most 512 KiB. This endpoint is not a general dependency installer. Prepare harness-package.json following the source-package guide, including actual executable protocol implementation:
Success 201 returns id/version/capabilities/model_providers, digest and created_at, not the full source files. Digest is computed over a canonical package with deduplicated/sorted capabilities and sorted files. Identical canonical content at the same key is accepted; different content or an OCI collision yields 409 harness_version_conflict. Registration stores inert data in the control plane. During execution, files are installed and byte-checked in the Sandbox, the interpreter must exist, and the program must implement the declared protocol. Source acceptance alone does not establish tool support, continuation, correctness or isolation beyond the documented Sandbox boundary. Malformed strict inputs return 400 invalid_request; image-specific registry/manifest failures use resolver errors. Private registry lookup may return secret_not_found (404), secret_disabled (409), secret_store_unavailable (503) or image_registry_credential_invalid (400). A lost registration response should be reconciled against catalog identity/digest rather than changing version to bypass a conflict.

Registration failures

Both registration operations use the common error envelope. The following named failures supplement strict input validation; a transport or unclassified server failure can still use the general error contract. Private registry Secret failures are listed above. Source-package path, entrypoint, file count, encoding-size and strict-schema violations return 400 invalid_request; a successful package registration does not run the interpreter or validate behavior. Registry reads may retry bounded read failures internally; this does not authorize retrying image publication, cloud allocation or external Tool writes. Sources: catalog projection, OCI registration, source packages, routes. Examples assume an origin without /v1; no registry request, registration or cloud execution was performed in this documentation pass. Next: HTTP overview, Harness selection.