hexagon-json-v1. Prefer OCI images for new integrations so the interpreter and dependencies have an explicit environment. Registration stores tenant-owned data; the control plane never imports or executes your source. Installation and execution happen in the cloud Sandbox.
Prerequisites and format
Use a management client, validated and enabled Sandbox/model connections, and a Sandbox withpython3 or node. The current source-package schema only accepts model_providers: ["anthropic-compatible"]. Changing a declaration does not add Chat Completions or Responses support.
A package contains 1–32 UTF-8 source files totaling at most 512 KiB. Each content string also has a 262144 JavaScript code-unit limit. Paths are at most 240 characters and must be schema-compatible relative paths: no empty segments, ., .., duplicates, or file/directory conflicts. The entrypoint must be present in files.
The format does not orchestrate npm/pip lockfile installation or accept binary archives. Structural validation and byte integrity do not prove executable correctness. Dependencies must already exist in the Sandbox or be managed explicitly by your package.
Register and select a version
These integration excerpts reuse an initialized client and connection IDs from the first Session tutorial. Read the existing Python Harness example from the repository root. It uses the standard library to call a Messages model, with shell access, declared remote Tools, and conversation history.harness_version_conflict. Use a new version for changed code and select it in a new Session; existing Sessions remain pinned. There is currently no source-package deletion endpoint. Capabilities are author declarations, not certification of arbitrary uploaded code.
stdin, credentials, and Tools
Runtime starts the entrypoint in the Session workspace and supplies one JSON object on stdin followed by EOF. It contains protocol, run_id, input, initialization, model, native_session, artifact_directory, and tools; native_session may be absent initially. Your Harness stores its own history and uses the returned opaque native_session to recover it on subsequent Runs. Use the suppliedmodel.base_url and model.model, not a hardcoded service URL. The current worker supplies HEXAGON_MODEL_KEY as delegated access to the protected model path; the original model account key stays in the control plane. HEXAGON_TOOL_TOKEN authorizes only this Run’s local Tool mailbox. Never log these values, add them to model context, or export them as artifacts.
Call remote Tools at http://127.0.0.1:8765/tools/<run_id>/call with Authorization Bearer <HEXAGON_TOOL_TOKEN> and JSON {"id":"<UUID>","name":"<declared name>","arguments":{}}. Poll the same logical call with the same id and arguments until state is completed, then process result and isError. The control plane manages authorization and approval waits. Generating another UUID can create a new operation; it is not a safe retry for an unknown external side effect. Do not bypass the mailbox to obtain bound Tool credentials.
Final output and failure
stdout must contain exactly one valid final result JSON line:Upgrade without changing existing work
Treat each package id/version as immutable. The server canonicalizes the file order and capability set for its content digest; changing executable content or other definition fields under the same version is a conflict, not an update. Register the changed package under a new version, then select it for a new Session. Do not edit an existing Session’s installed source to simulate a version upgrade. The package API validates the source layout and content bounds, not dependency availability or model behavior. Check the interpreter, actual imports, delegated model access, final-result parser and conversation history independently. A script that prints a success-shaped JSON result without doing the work is not a valid acceptance fixture. When the program fails, return the contract’s supported failure fields and a nonzero exit where appropriate; do not attach arbitrary diagnostic keys to the strict final-result object. Emit sanitized ordinary diagnostic logs separately. Preserve the original invocation and investigate Tool side effects before restarting after interruption.Read result failures correctly
These cases exercise the result contract, not the model. The local package tests also corrupt uploaded bytes and require installation to fail. The database-backed version test covers identical-content registration, changed-content conflicts, registry reconstruction and tenant isolation; it must actually run against a test database before claiming those persistence checks passed. The initial review ran local result/integrity checks and skipped the unconfigured database case. The later combined evidence review records isolated PostgreSQL execution: all four selected files and 16 tests passed, including package-version persistence checks; the temporary schema was removed. The compatibility API remains supported; this page assigns no deprecation or removal date.