Releases and jobs

Releases and jobs. A release is a version of your application that Hangar runs for each of your customers. Each job uses your prepaid credit.

A vendor builds its application once, as a package. Hangar runs a signed, accepted release of the package for each tenant (each customer) of the vendor. Every job ends with the artefacts that the application wrote, and a return. The return is a job certificate. It shows which release ran, the envelope, the pool and every attempt. Anyone can verify the return offline.

TALOS Warrant is the part of Hangar that decides what a job may do. Before a job starts, TALOS Warrant compiles the envelope: the set of limits that the job cannot leave. The envelope comes from what the release asks for and what your policies allow. During the job, TALOS Warrant enforces the envelope. After the job, TALOS Warrant signs the return.

The route, start to end:

1. You make a release key on your own machine and register it.
2. You push your image and create a package version from hangar_package.json.
3. You sign the release and submit it.
4. TALOS Defence runs the acceptance checks, including a self-test job of the release, and signs its acceptance.
5. You move a channel, such as stable, to the release.
6. You start jobs of the release for your tenants, with the Hangar app, the hangar command line or the Python package gethangar.
7. Each job ends with its artefacts and a signed return.

The reference package hangar_patch_agent in examples/patch-agent follows this route from start to end.

1. The application contract

Your application runs as the entrypoint of the image, in a container on a fresh instance for each attempt. The application reads its inputs and its configuration from fixed paths, and writes its outputs to a fixed folder. The application reports its result with its exit code.

The environment:

Read the folders through the three variables. A local runner, such as the reference package's run_local.py, sets them to temporary folders.

Exit code 0 means that the application finished. Any other code fails the attempt. Hangar still seals and keeps the declared outputs, so you can see what the application wrote.

Hangar collects only the outputs that the package declares. Hangar lists the output folder without following links. Hangar records any other file name, link or folder as skipped, and does not read the skipped item. Hangar still seals and keeps an output that is larger than its max_bytes, and the output fails its descriptor.

The application connects to the network only through the gateway, and only to the destinations in the envelope. The containers of the job trust the certificate authority of the session, which vouches for those destinations only. SSL_CERT_FILE gives the path of the certificate authority file.

2. The package manifest

hangar_package.json describes the package. The file is JSON, in the format hangar-package-v1. Hangar refuses a field that Hangar does not know. A misspelt field is an error, and Hangar never drops a setting without a message. The schema docs/api/package-manifest.schema.json describes the file for editors. The parser in Hangar is the final authority.

The seven type descriptors

Inputs, outputs and configuration keys use a small set of descriptors that Hangar defines. The set is closed. A descriptor is one of these seven.

An artefact is an input or an output, never a field of an object, a list item or a configuration key. Descriptors nest at most six deep.

Hangar refuses a job at submission with input_contract when an input does not match its descriptor. An output that does not match its descriptor fails the attempt with the reason output_contract. Hangar keeps the artefact under your retention, so you can see what the application wrote.

Artefacts travel as digests. The bytes pass through the upload routes into the storage of your organisation in Sydney. The envelope and the return list each artefact by digest, size and media type. The envelope and the return never contain the bytes of an artefact or any value.

The envelope the package asks for

The package asks for the permissions that it needs. The package never gives those permissions to itself. TALOS Warrant compiles the envelope from the request and your policies (Section 7).

Hangar refuses a package version with envelope_request_invalid when the request binds a secret to an undeclared destination, gives a fallback that is not a declared destination, or has a malformed name. The error shows the item.

The CPU pool hosted-cpu-syd runs packages for linux/arm64 with gpu none. You send the image with hangar upload --image, and the manifest refers to the image by its digest.

hangar upload --image ./patch-agent.oci.tar --name patch-agent:1.0.0
hangar release create

hangar release create reads ./hangar_package.json (or the file that you name), sends the file byte for byte, and prints the package version with the manifest digest. The manifest digest is the domain-separated SHA-384 of the exact bytes, with the context hangar-package-v1. The command line computes the same digest on your machine.

3. Releases

A release pins one package version, by digest, under your signature. A release is a canonical CBOR document of the format hangar-app-release-v1:

The release id is the domain-separated SHA-384 of these bytes, with the context hangar-app-release-v1, written as sha384: and 96 hexadecimal digits. A release refers to an image only by digest, never by tag, and contains no configuration value. A changed image has a different digest, so it needs a different release with its own signatures. Pushing an image again under the same name changes no release, no channel and no job.

Your release key

You sign your releases with your own release key: a hybrid key pair of ML-DSA-87 and ECDSA P-256. hangar release keygen makes the key pair on your machine and keeps the private half there, in a file of mode 0600. The private half never leaves your machine. TALOS Defence cannot make or use the private half.

hangar release keygen talos-release
hangar release register talos-release

An owner of your organisation registers the public half, signed in with a passkey (POST /v1/vendor-keys). The registration is a record on the chain of your organisation. A request key cannot register a release key.

Signing and submitting

hangar release submit hangar_patch_agent@1.0.0 --key talos-release

The command line asks Hangar for a draft of the release (POST /v1/packages/{name}/versions/{version}/release-draft). Hangar builds the draft from the package version that Hangar holds, with the next sequence number. The command line checks that the draft matches hangar_package.json on your machine, signs the release id with your key, and submits the manifest and the signature (POST /v1/releases). Hangar accepts the submission when:

• the bytes are the canonical encoding of the manifest;
• every field equals the field in the package version that Hangar holds;
• the sequence is the next one, and the draft is at most 600 seconds old;
• the signature verifies with an unrevoked release key of your organisation.

A release has these states in order: submitted, checking, checks_passed or checks_failed, then accepted or refused. A release later becomes revoked if someone revokes the release. hangar release status shows the state, and GET /v1/releases/{id} gives the release in full.

4. Acceptance

TALOS Defence runs the acceptance checks on every release before the release runs for a tenant. Acceptance shows that the checks passed for the digests in the release. Acceptance does not change the release. The signature of the vendor and the digests stay the same.

The checks that must pass:

The self-test is a job of the release with the self_test inputs of the package and the default configuration. It runs on the platform of the pool, after the preflight of the image, so Hangar cannot accept an image that cannot start on the pool. The return of the self-test shows the notice "This return is a self-test of a release before TALOS Defence accepted it."

When the checks pass, a TALOS Defence operator accepts the release. The acceptance record lists every check by name with the result, the pool and return digest of the self-test, and any widening. TALOS Defence signs the acceptance record with the release root at the key site. TALOS Defence uses the release root only to sign what TALOS Defence ships. No customer data and no permission for any job depends on the release root. A root signature signs the acceptance, never a day key.

Hangar refuses a release whose checks fail. The release shows the checks and the results.

5. Channels, pins, widening and revocation

A channel is a name that you choose (stable, candidate, or any other name). The channel points from a package to one accepted release.

hangar release channel hangar_patch_agent stable 5d1c09e2a7b4

A move (POST /v1/packages/{name}/channels/{channel}) takes an accepted release only, and every move is a record. A job gives a release id (a pin), or a package and a channel. When you submit a job, Hangar resolves the channel to a release id once, and records the release id. Every retry of the job uses that release, even when someone moves the channel.

Widening

hangar_cert::envelope::diff compares two envelope requests and lists every widening, in a fixed order. A widening is one of these:

• a new destination, secret, data scope, companion or model route;
• a new fallback for a model route;
• a larger vcpus, memory_mib or max_minutes;
• a weaker failure policy: more retries, or resuming from a checkpoint;
• a person-present step removed.

At every job, TALOS Warrant compares the release with the baseline of the tenant. The baseline is the newest release of the package that the tenant has run. When the tenant has not run the package yet, the baseline is the first accepted release of the package. The same rule applies to the jobs of your own organisation, which have no tenant. An owner must approve the difference for the tenant before a release that asks for more than the baseline can run for that tenant. Until then, the jobs of the tenant on the channel use the newest earlier release of the channel that stays within the baseline, and the job shows this in held_on. Hangar refuses a job of the widening release by id for that tenant with widening_not_approved, and the error detail shows the approval that an owner can decide. A release that narrows the permissions needs no approval.

The acceptance record and each channel move also list a widening, against the newest accepted release of the package and against the release that the channel pointed at. Those lists show what changed. The baseline sets the approval rule.

GET /v1/approvals lists each pending widening approval. Each entry shows the release, the package and version, the channel, the tenant, the baseline and every item that the release adds. The approval record shows the baseline and the items, so the record shows what the owner approved. The approver is an owner of the vendor's organisation, who acts for the tenant on the website or through the approval routes. The approval record shows the person and the tenant. The next job after the approval resolves to the new release, and the return of that job contains the approval record. The compiled record of every job shows the baseline, and the return contains the baseline release. hangar verify recomputes the widening offline and checks the approval.

Revocation

TALOS Defence or an owner of the vendor's organisation can revoke a release:

hangar release revoke 5d1c09e2a7b4 --reason "Wrong rule set"

A revocation is a record. Hangar holds a channel that points at a revoked release. Hangar refuses jobs on the channel with channel_held until you move the channel to an accepted release. Hangar never falls back to an earlier release by itself.

TALOS Defence signs the release revocation list with the release root and publishes the list at GET /v1/releases/revoked. When a vendor revokes a release of the vendor, Hangar holds the channels of the release at once. The signed list shows the revocation from the next signing. The list and the release key set (GET /v1/releases/keyset) are public, so a customer-controlled pool (offered from 2027) checks a release offline.

GET /v1/releases/{id}/bundle gives one release as a bundle that verifies offline: the signed release, the revocation list and the release key set. The vendor ships the image layers, as an OCI layout that the runtime checks by digest.

6. Site configuration

A package declares its configuration keys, and each pool and tenant sets the values. The same release id runs on every supported pool. One site differs from another in exactly three ways:

1. a declared configuration key;
2. the runtime version, inside the release's runtime range;
3. the pool identity on the return.

Nothing else selects behaviour by tenant or site. A change for one customer is a configuration key, or a new package version for every customer.

PUT /v1/config/hangar_patch_agent/hosted-cpu-syd
{"tenant": "tnt_0192f3a1c7d84e6b9a0c5d2e1f4b7a93", "values": {"test_timeout_seconds": 300}}

PUT /v1/config/{package}/{pool} sets values for the organisation, or for one tenant with tenant. A value for a tenant wins over a value for the organisation. Each set makes a new configuration version with its own digest, and each set is a record. GET /v1/config/{package}/{pool}?tenant= gives the current version.

The rules:

• A key the package does not declare is refused with config_invalid, and so is a value that does not match its descriptor.
• You must set a key that has no default for each pool. Hangar refuses a job on a pool where the key is not set with config_missing, and the error shows the key. site_specific: true marks a key whose value differs by pool, so the people who set up a pool know to set the key.
• Values are data. A destination-typed key selects one of the declared destinations of the package. No key gives an image, a secret value or a file to run.
• You set secrets by name through the secrets routes, and the gateway attaches them. Configuration never contains secrets.

TALOS Warrant compiles the digest of the configuration version into the envelope, and the return shows the digest. Two returns of one release on two sites show the same release id and different configuration digests.

7. Starting a job

hangar run --release 5d1c09e2a7b4 --tenant tnt_0192f3a1 \
    --input repository=sha384:9f2c41e0b37d --input rules='["path_traversal"]'

POST /v1/release-jobs, with an Idempotency-Key:

{
  "package": "hangar_patch_agent",
  "channel": "stable",
  "tenant": "tnt_0192f3a1c7d84e6b9a0c5d2e1f4b7a93",
  "pool": "hosted-cpu-syd",
  "inputs": {
    "repository": {"artefact": "sha384:9f2c41e0b37d..."},
    "rules": {"value": ["path_traversal"]}
  },
  "narrowing": {"max_minutes": 10},
  "client_ref": "harbour-17/2026-10-23/1"
}

client_ref lasts longer than the 24-hour idempotency store. The same client_ref with the same body returns the existing job. A process that restarts after sending finds the job, and starts no second job. Hangar refuses the same client_ref with a different body with client_ref_conflict.

Jobs of a release start on hosted-cpu-syd. Each attempt runs on one fresh Graviton instance in AWS Sydney, for that attempt alone. Hangar terminates the instance when the attempt ends. From 2027, a customer-controlled pool runs releases from the Hangar runtime of the customer, in the customer's environment (Pools, Section 3).

The compile

Before any instance launches, TALOS Warrant compiles the envelope, in this order:

1. The release: the id, or the channel resolved once, with the widening rule of Section 5.
2. The inputs, each against its descriptor.
3. The release's envelope request.
4. Your account policy: the egress list, and the release limits on vCPUs, memory, minutes, model routes and data scopes.
5. The policy of the tenant, which can only narrow your account policy.
6. The configuration version for the package, pool and tenant.
7. The narrowing of the job, which can only remove items.

Each step is an intersection. The envelope never exceeds what any one step allows. When a policy denies a required item, Hangar refuses the job with envelope_denied, and the error shows the item. When a policy denies an optional item, Hangar drops the item and writes the drop, with the reason, in the envelope. Hangar refuses a narrowing that adds anything with narrowing_invalid. Hangar compares names exactly, so a name that differs in case or by a final dot is a different name.

The compiled envelope is canonical CBOR with its own digest. Hangar writes the envelope as a record before the launch. The envelope lists the release, the pool, the tenant, the image and command, the companions, the destinations, the dropped items, the data scopes, the secrets by name, the model routes, the person-present steps, the compute, the failure policy, the configuration digest and the inputs by digest. The envelope also lists the digests of the request, the account policy, the tenant policy and the narrowing that the envelope came from.

The window

Every envelope has a not-before time and a not-after time. The window is at most the max_minutes of one attempt plus 10 minutes to launch, multiplied by the number of attempts that the failure policy allows. Each attempt has its own hard stop: max_minutes plus the 10 minutes to launch, counted from the launch, and never later than the not-after time. At that stop, the authority for the attempt ends and the gateway closes. Hangar stops an attempt that still runs, and the attempt ends interrupted with the reason attempt_time_limit, or window_end at the not-after time. Hangar retries a stopped attempt while the window has room. No attempt starts after the not-after time, and a retry never extends the window.

Enforcement

The worker receives the compiled envelope and the digest of the envelope with the orders for the attempt. The worker refuses to start an attempt when the image, command, companions, platform, inputs, values or configuration differ from the envelope (envelope_mismatch). Nothing runs, and the return records the refusal.

The gateway list for the attempt is the destinations in the envelope, and the gateway attaches the secrets in the envelope. A model route compiles to the primary destination and the declared fallback of the route. The application chooses which destination to call. The gateway refuses every other destination.

A person-present step sends an approval request to the phones of the approvers. A declared credential_use or destination_first_use step turns the approval on for the whole attempt. An agent_action step uses the proposal that the agent sends to the gateway. The approval card shows the sentence of Hangar, with the sentence of the package beside it.

8. States and outcomes

A job moves through seven states:

A returned job has one of five outcomes:

The retry rule: Hangar retries an attempt on a fresh instance when the attempt was interrupted, failed with a non-zero exit, or did not report its outputs sealed. Hangar retries up to the retries of the failure policy, while the window has room. Hangar never retries an attempt that was refused with envelope_mismatch, an output that failed with output_contract, or an image that the preflight refused, because a retry would repeat the same failure.

Each attempt has its own states: launching, staging, running, sealing and ended. Each attempt also has its own outcome and reason.

POST /v1/release-jobs/{id}/cancel stops the attempt and closes the envelope. Cancellation is final. A cancelled job starts no other attempt.

9. Events

GET /v1/release-jobs/{id}/events?after=<offset>&wait=<seconds> gives the events of the job after the offset as newline-delimited JSON (application/x-ndjson). Every line shows the offset (from 1), at (RFC 3339 with the Melbourne offset), the envelope digest and the kind:

{"offset":7,"at":"2026-10-23T15:12:47+11:00","envelope":"sha384:c41e...","kind":"connection","attempt":1,"destination":"pypi.org","outcome":"connected"}
{"offset":8,"at":"2026-10-23T15:12:52+11:00","envelope":"sha384:c41e...","kind":"connection","attempt":1,"destination":"example.com","outcome":"refused","reason":"not_on_allowlist"}
{"kind":"heartbeat","at":"2026-10-23T15:13:07+11:00"}

Each call answers as soon as an event exists after the offset. Otherwise the call answers after at most 15 seconds with one heartbeat line, which has no offset. To continue, call again with the last offset that you read as after. Hangar sends the events since that offset, with no gap and no duplicate, however many times you call or reconnect. The last line of a returned job is {"kind": "end", "state": "returned", "outcome": ...}. With wait=0, the call reads once and answers at once. Reading a returned job gives the remaining events and the end line, and never starts an attempt.

The stream contains metadata only, never input bytes or output bytes. hangar logs <job> --follow prints the stream.

10. The return

Every job ends with a return. The return is a job certificate of kind 4, printed as "job certificate, application release". The issuer of the key set of the pool signs the return. On the pools of Hangar, the issuer shown on each return is TALOS Defence Pty Ltd. Hangar signs a return after the machine is wiped, usually within 15 minutes after the last attempt seals. If you ask for the return before then, the API answers return_pending.

The return lists:

• the vendor organisation and the tenant;
• the package and version, the release id, the package manifest digest, the image and companion digests and the SBOM digest;
• the signature of the vendor with the key registration record, and the acceptance of TALOS Defence with its record;
• the baseline release that the widening is measured against, when the baseline is another release, and any widening approval record;
• the configuration version digest;
• the envelope as compiled, in full, with the digests it came from;
• each attempt: the pool identity, the instance type and id, the zone, the purchase, the times, the reset records, the outcome and the reason;
• the inputs and outputs by digest, size and media type, with each output's descriptor result;
• each connection and refusal by destination name, and the use of each model route: a route counts as used through the primary when a connection to the primary destination was made, and through the fallback when a connection to the declared fallback was made;
• the approvals;
• the runtime version.

A return contains no input or output bytes, no configuration value and no secret value.

What hangar verify checks

hangar verify 0192f3b7
hangar verify 0192f3b7.cert --release-keys release_keyset.cbor

hangar verify runs every check of the job certificate. For a return, it adds the release check:

"The release is signed by its vendor and accepted by TALOS Defence, the compiled envelope lies within the release's request, and every connection and output stays within it."

In order:

1. The release manifest decodes, and the id of the manifest matches the return.
2. The signature of the vendor verifies over the release id with the key in the included registration record.
3. A root in the published release key set of TALOS Defence signed the acceptance, never a day key. The acceptance shows the release and the vendor key.
4. The compiled envelope lies within the envelope request of the release, which the verifier recomputes. The envelope shows the release and the pool.
5. The destination of every connection is in the envelope, and the destination of every model route is in the envelope.
6. Every output digest is in an included record. A succeeded outcome has every output passed.

The hangar command line includes the release key set that TALOS Defence publishes. --release-keys FILE gives the command line another key set. The customer's own keys sign a return from a customer-controlled pool (offered from 2027). To check the return, run hangar verify --issuer-keys <customer key set>.

11. Errors

Every error has three parts, from the catalogue in docs/api/errors.json: what failed, the next step, and what to do if that fails. The codes these routes return:

Read this page as Markdown