Stop a fleet run before its next target (admin).
const url = 'http://localhost:8080/v1/admin/platform/apply/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancel';const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}use reqwest;
#[tokio::main]pub async fn main() { let url = "http://localhost:8080/v1/admin/platform/apply/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancel";
let mut headers = reqwest::header::HeaderMap::new(); headers.insert("Authorization", "Bearer <token>".parse().unwrap());
let client = reqwest::Client::new(); let response = client.post(url) .headers(headers) .send() .await;
let results = response.unwrap() .json::<serde_json::Value>() .await .unwrap();
dbg!(results);}curl --request POST \ --url http://localhost:8080/v1/admin/platform/apply/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancel \ --header 'Authorization: Bearer <token>'Sets the run’s PERSISTED cancel flag. IT STOPS THE RUN BEFORE ITS NEXT TARGET AND NEVER INTERRUPTS AN IN-FLIGHT ATTEMPT - a pull or a recreate already running finishes, and the run goes cancelled when that attempt terminates. Interrupting a recreate is how a stack is left with no container at all, so this operation deliberately cannot do it. An attempt still queued or waiting_sessions becomes cancelled at once. Idempotent. The flag is persisted so a cancel issued while the run’s control-plane target is restarting the control plane is honoured by the binary that boots.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Responses
Section titled “Responses”The run as it stands; state is still running if an attempt is in flight.
object
One fleet apply (schema.md platform_apply_runs): one release applied across the instance, control plane first then eligible hosts in sequence (ADR 0002). AT MOST ONE IS ACTIVE PER INSTANCE, enforced by a partial unique index rather than by a code check, so two admins pressing Apply at once produce a unique violation and not two fleets moving.
object
A fleet run’s state. A run succeeds only when EVERY target it reached succeeded, and it STOPS AT ITS FIRST FAILED TARGET - past a failed control plane, continuing would move agents onto a release the control plane is not on (ADR 0002); past a failed host, it would march a known-bad digest set across the fleet. A FAILED run has no partial variant: it may have succeeded targets behind it, and the per-target attempts are where that is read. AMENDMENT 9 (#185) APPENDS succeeded_partial: the run reached the end of its host list with nothing failed, but it PASSED OVER at least one host that was behind the release for a reason other than up_to_date (its agent was offline, its preflight was blocked, it is source-built, it has no updater) - so the fleet is on mixed versions. Terminal, and NOT a failure: it does not suppress an unattended release, and the next unattended pass or a “retry” (a plain fleet apply of the same release carrying retry_of) picks the host up once it can take the release. A client renders it distinctly from succeeded - the skipped list and its reasons are the outcome, not a footnote.
ADDITIVE (amendment 9, #185). The run this one was started to finish - an admin pressed “Retry skipped hosts” on a succeeded_partial run. Provenance only: the retry is an ordinary fleet apply of the same release, and the hosts it moves are decided at their turn exactly as always (the already-updated ones read up_to_date and are skipped). Null on every other run, and on a server predating the amendment. ON DELETE SET NULL, so deleting the original leaves the retry standing.
Applied to EVERY host target in this run. It exists on the fleet body, and not only on the per-host one, because a run whose every host target waits for a natural drain can otherwise stall indefinitely.
ADDITIVE, amendment 8 (#122). True when the detection schedule started this run rather than an admin pressing Update. A CLIENT SHOULD SAY SO: an admin finding a fleet run they did not start is owed the explanation. requested_by cannot answer this - it is null for an unattended run AND for one whose requesting admin has since been deleted (ON DELETE SET NULL). Always false on a run an admin created, and false on a server predating this amendment. An unattended run NEVER carries force: force is an operator agreeing to end N live sessions and there is no operator, so an unattended run is only ever started for a release whose migrates is false (see the apply section).
The cancel FLAG, not the cancel state. Read BETWEEN TARGETS and never mid-attempt. It is persisted rather than an in-memory signal so a cancel survives a control-plane restart - which matters here more than anywhere, because a fleet run’s first target IS a control-plane restart.
The target the run is on now; null when pending or terminal.
Operator prose for a run-level failure belonging to no attempt. Never parsed.
Hosts the run passed over as ineligible at their turn.
A host a fleet run passed over. An ineligibility is NOT a failure - a run must not go failed because a host happened to be offline - so a skip produces no attempt row and is reported here instead, which is what answers “why did my host not move” from the run itself.
object
Why a target is not eligible for the newest listed release. A CLOSED vocabulary of STABLE IDENTIFIERS the UI maps to text - the server never sends the sentence, so wording can improve in the client with no contract change. Precedence is fixed and is the order listed here, so two implementations cannot disagree about which of several true reasons is reported. A client meeting an unrecognized value renders it verbatim rather than dropping the row. Full per-value semantics: control-api.md §“Platform releases”. AMENDMENT 2 (#104/#114) APPENDS attempt_in_flight and run_active AT THE END, so no existing evaluation changes: they are the most transient facts on the list, and amendment 1’s rule that durable reasons outrank transient ones fixes their position. attempt_in_flight precedes run_active because it is about THIS target. AMENDMENT 9 (#185) INSERTS preflight_blocked after control_plane_not_first and before the two transient ones: a stack shape (an unmounted socket volume, a squatted health port) is a durable fact, and the rule that durable reasons outrank transient ones is what fixes its position. The only target whose answer changes is one that is BOTH blocked and mid-apply, which now reads preflight_blocked. The failing check and its fix are on the same target’s preflight. A preflight of unknown never produces this reason. AMENDMENT 14 (#353) APPENDS below_floor: the host’s agent or recovery actor would be, or already is, older than the floor the installed control plane declares (the oldest agent and recovery-actor release it still manages). It is produced by the per-host revert refusal (409 host_not_eligible) and NEVER on a targets entry - a target is evaluated for an update to available[0], which is what a below-floor host is offered - so it takes no position in the precedence above. Amendment 14 also reads “install mode is registry” as “registry or owned”, and up_to_date on an owned host as “agent AND recovery actor on the release’s commit”.
The per-target attempts, in the order the run reached them (control plane first).
One attempt to move ONE target - the control plane, or one host - to one digest set (schema.md platform_apply_attempts). Every apply produces one: fleet or standalone, apply or revert, success or failure.
object
The fleet run this belongs to. NULL for a standalone per-host apply or revert - those are attempts with no run, because a run carries fleet ordering and a single-host action has none.
A REVERT IS AN APPLY WITH AN OLDER DIGEST SET - same wire message, same states, same reasons. This field exists so history can say which button was pressed, and for nothing else. AMENDMENT 9 (#185) APPENDS auto_revert: no button was pressed - the host’s UPDATER put the previous digests back itself after the new agent container failed its health wait (agent-api.md release_state restored), and the control plane wrote this row beside the failed apply so the history shows both steps. It is recorded succeeded on insert (the updater reports restored only for a restore that came up; a restore that itself failed leaves no row and both failures in the failed apply’s output), was never driven over the wire, and its requested_digests are the failed apply’s previous_digests. Amendment 14 (#353): on an owned host the recovery actor did the restore, and the row names ONLY the restored component (the one whose replacement failed), which may be recovery-actor. Amendment 14 (owner addition on #353) APPENDS developer_apply: an admin applied an arbitrary digest set to an owned target (POST /v1/admin/platform/developer-apply); release_id is null, and it is otherwise an ordinary apply and revert source. A client meeting an unrecognized kind renders it verbatim.
Null exactly when target is control_plane.
The release the digests came from, when one is still known. NULL is legitimate on a revert, whose digest set may correspond to no release row this instance still has - requested_digests, not this field, is the authority for what an attempt did.
What was asked for, in manifest order - the exact components array sent on agent-api.md release_apply. THE AUTHORITY for what this attempt did.
One component of a platform release, pinned. Same shape as ReleaseManifestComponent and as agent-api.md release_apply.components.
object
The component. Only “node-agent” is ever sent to a registry host; an owned host (amendment 14, #353) may also be sent “recovery-actor”, and the ORDER of the list is the order of replacement. “control-plane” is applied by the updater or recovery actor beside the control plane and never over an agent connection.
Registry repository reference with NO TAG AND NO DIGEST. Consumers compose image@digest (ADR 0001).
Sha256: followed by 64 lowercase hex.
What the target was on before. Empty until first reported. What a revert reads back, and what the manual restore recipe in a failure is copied from.
What a component was on BEFORE an attempt. Recorded from every release_state, in every state and not only failing ones, because the previous digests are what restores a half-failed stack and something has to have written them down before the restore is needed (#113 prototype finding 5). This is what a revert reads.
object
Null when the updater could not determine it. NEVER OMITTED - a client must be able to tell “nothing was there” from “nobody looked”.
One target’s attempt state. The six middle values are EXACTLY agent-api.md release_state.state, relayed unchanged. queued and waiting_sessions are control-plane-only and precede the wire (the command has not been sent); cancelled applies ONLY to an attempt a cancel caught in one of those two states - CANCEL NEVER INTERRUPTS AN ATTEMPT THAT HAS BEEN SENT. Amendment 14 (#353) rewords, without changing any value: recreating means the target’s actor is replacing a component’s container (on an owned machine the old one is stopped and kept until the new one is verified), not a Compose command.
Why an attempt failed. A CLOSED vocabulary of STABLE IDENTIFIERS the UI maps to text, shared verbatim with agent-api.md release_state.reason and with the release_apply ack’s error, so ONE client-side mapping serves the wire, this API and the history. Non-null exactly when the state is failed. “unsupported” is written by the control plane and never sent on the wire: no ack arrived within the 10s ack timeout, so the agent build predates the amendment. A client meeting an unrecognized value renders it verbatim. “signature_missing” and “signature_invalid” are amendment 5’s two APPENDED values (#120): a host that requires a signed release met an unsigned one, and a manifest signature that did not verify (bad signature, untrusted key, digests not named by the signed manifest, a signature that could not be fetched, or verification on with no trusted keys - all fail closed). Signature verification is OFF BY DEFAULT (ADR 0003), so neither occurs unless an operator turns it on. AMENDMENT 14 (#353) APPENDS five values, produced only by an owned machine and each meaning “nothing changed”: recipe_unsupported (the recovery actor lacks the recipe revision an image declares, ADR 0008), owner_conflict (a Quasar-looking container without this installation’s labels is in the way), backup_failed (control plane, migrating release, Quasar-owned database: the pre-update dump could not be taken), backup_unconfirmed (control plane, migrating release, external database, no external_backup_confirmed) and interrupted (the actor, engine or machine restarted before the old container was taken out of service; settled, never retried). Amendment 14 also confirms signature_missing and signature_invalid as members. Full per-value semantics: agent-api.md §release_state.
The N in “waiting on N sessions”: the last observed non-terminal session count while state is waiting_sessions - ON THIS HOST for a host target, and FLEET-WIDE for the control-plane target, whose recreate is instance-wide. On a control-plane target it is set ONLY when the release’s migrates is true (amendment 6, #153): a recreate alone no longer ends a running session, so a non-migrating control-plane attempt never enters waiting_sessions and leaves this null throughout. A CLIENT MUST SHOW IT IN A FORCE CONFIRMATION - force is the operator agreeing to end N live sessions, and a confirmation that does not name N is not informed consent. Advisory and last-observed, never a gate. Null once the attempt has been sent.
Skip the zero-sessions wait and stop what is running. The agent does no session logic on it: it records which decision the control plane made.
The bounded tail (last 8192 bytes, truncated from the front at a line boundary) of the failing step’s output. “” when there is nothing to report. NEVER a credential or an environment value. Amendment 14 (#353): a failed MIGRATING control-plane attempt on an owned machine is never restored automatically, and its output ends with the one-line restore command naming pre_update_dump and the version it returns to.
ADDITIVE (amendment 14, #353). The DUMP REFERENCE: the name of the pre-update dump the recovery actor took before replacing the control plane with a migrating release, exactly as the operator passes it to the restore command. Opaque - display it, never parse it. Null on every host attempt, on a non-migrating or external-database control-plane attempt, and on a registry control plane. A server implementing the amendment always serializes it; optional here so a client still accepts an older server (absent reads as null).
Example
{ "run": { "state": "pending", "current_target": "control_plane", "skipped": [ { "reason": "no_release" } ], "attempts": [ { "kind": "apply", "target": "control_plane", "state": "queued", "reason": "updater_absent" } ] }}Missing/invalid/expired/revoked token.
object
object
E.g. validation_failed, unauthorized, forbidden, not_found, conflict, session_quota_exceeded, home_in_use, home_not_provisioned, parent_app_disabled, profile_ineligible, profile_not_launchable_for_app, no_host_available, capacity_exhausted, host_not_ready, restart_required, stale_revision, unsupported_source, approval_superseded, approval_expired, attempt_conflict, cancel_too_late, retry_exhausted, home_conflict, placement_ineligible, inherited_placement, recovery_uncertain, rate_limited, internal. Open string, not an enum: new codes are additive and an unknown one falls through to a client’s generic per-status branch.
Present on restart_required.
Steam library discovery Phase 3, ADDITIVE: present on home_in_use when the guard could name the CONFLICTING live session - the one already holding the home. It is here so the client can offer “go to your running session” with a link instead of a dead-end toast. OMITTED rather than empty when the conflict is known but the session is not, so a client branches on presence and never renders a link to nowhere. Also omitted when the holder is the caller’s parked session or released runtime (amendment 39). Load-bearing once derived tiles exist: the lock is held by the PARENT’s home, so a user who clicks a game tile can be refused because a DIFFERENT app (the Steam launcher, or another game from the same install) is running, and without the session id the refusal reads as a bug. See control-api.md §Derived tiles.
Steam library discovery Phase 3, ADDITIVE: present on the 409 conflict from DELETE /v1/apps/{id} when the app has derived tiles and ?delete_derived=true was not sent. A LIST, not a count - the point of the confirmation is that the admin sees what they are about to destroy. Capped; an empty array means the tiles could not be listed, never that there are none.
object
Amendment 40 (#602), ADDITIVE: a machine-readable cause under code. On 503 no_host_available, home_host_unavailable: the launch is pinned to the host that holds the caller’s home for this app (Amendment 53: or it is pinned to the host of the caller’s Steam home for a sharing launch) and that host is offline or no longer enrolled. Only an admin clears it, so a client does not spend its automatic retry on it. Names no host. Amendment 53 (#1001), on 409 home_in_use: steam_library_open_in_desktop (the holder mounts the Steam library as a shared home) or steam_game_running (the refused launch shares the library and a Steam session holds it); absent when the holder is already stopping. Open string: a client treats an unknown value as absent.
Examplegenerated
{ "error": { "code": "example", "message": "example", "live_sessions": 1, "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "derived_tiles": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example" } ], "reason": "example" }}Authenticated but insufficient role / not the owner (precedes resource lookup).
object
object
E.g. validation_failed, unauthorized, forbidden, not_found, conflict, session_quota_exceeded, home_in_use, home_not_provisioned, parent_app_disabled, profile_ineligible, profile_not_launchable_for_app, no_host_available, capacity_exhausted, host_not_ready, restart_required, stale_revision, unsupported_source, approval_superseded, approval_expired, attempt_conflict, cancel_too_late, retry_exhausted, home_conflict, placement_ineligible, inherited_placement, recovery_uncertain, rate_limited, internal. Open string, not an enum: new codes are additive and an unknown one falls through to a client’s generic per-status branch.
Present on restart_required.
Steam library discovery Phase 3, ADDITIVE: present on home_in_use when the guard could name the CONFLICTING live session - the one already holding the home. It is here so the client can offer “go to your running session” with a link instead of a dead-end toast. OMITTED rather than empty when the conflict is known but the session is not, so a client branches on presence and never renders a link to nowhere. Also omitted when the holder is the caller’s parked session or released runtime (amendment 39). Load-bearing once derived tiles exist: the lock is held by the PARENT’s home, so a user who clicks a game tile can be refused because a DIFFERENT app (the Steam launcher, or another game from the same install) is running, and without the session id the refusal reads as a bug. See control-api.md §Derived tiles.
Steam library discovery Phase 3, ADDITIVE: present on the 409 conflict from DELETE /v1/apps/{id} when the app has derived tiles and ?delete_derived=true was not sent. A LIST, not a count - the point of the confirmation is that the admin sees what they are about to destroy. Capped; an empty array means the tiles could not be listed, never that there are none.
object
Amendment 40 (#602), ADDITIVE: a machine-readable cause under code. On 503 no_host_available, home_host_unavailable: the launch is pinned to the host that holds the caller’s home for this app (Amendment 53: or it is pinned to the host of the caller’s Steam home for a sharing launch) and that host is offline or no longer enrolled. Only an admin clears it, so a client does not spend its automatic retry on it. Names no host. Amendment 53 (#1001), on 409 home_in_use: steam_library_open_in_desktop (the holder mounts the Steam library as a shared home) or steam_game_running (the refused launch shares the library and a Steam session holds it); absent when the holder is already stopping. Open string: a client treats an unknown value as absent.
Examplegenerated
{ "error": { "code": "example", "message": "example", "live_sessions": 1, "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "derived_tiles": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example" } ], "reason": "example" }}No such resource.
object
object
E.g. validation_failed, unauthorized, forbidden, not_found, conflict, session_quota_exceeded, home_in_use, home_not_provisioned, parent_app_disabled, profile_ineligible, profile_not_launchable_for_app, no_host_available, capacity_exhausted, host_not_ready, restart_required, stale_revision, unsupported_source, approval_superseded, approval_expired, attempt_conflict, cancel_too_late, retry_exhausted, home_conflict, placement_ineligible, inherited_placement, recovery_uncertain, rate_limited, internal. Open string, not an enum: new codes are additive and an unknown one falls through to a client’s generic per-status branch.
Present on restart_required.
Steam library discovery Phase 3, ADDITIVE: present on home_in_use when the guard could name the CONFLICTING live session - the one already holding the home. It is here so the client can offer “go to your running session” with a link instead of a dead-end toast. OMITTED rather than empty when the conflict is known but the session is not, so a client branches on presence and never renders a link to nowhere. Also omitted when the holder is the caller’s parked session or released runtime (amendment 39). Load-bearing once derived tiles exist: the lock is held by the PARENT’s home, so a user who clicks a game tile can be refused because a DIFFERENT app (the Steam launcher, or another game from the same install) is running, and without the session id the refusal reads as a bug. See control-api.md §Derived tiles.
Steam library discovery Phase 3, ADDITIVE: present on the 409 conflict from DELETE /v1/apps/{id} when the app has derived tiles and ?delete_derived=true was not sent. A LIST, not a count - the point of the confirmation is that the admin sees what they are about to destroy. Capped; an empty array means the tiles could not be listed, never that there are none.
object
Amendment 40 (#602), ADDITIVE: a machine-readable cause under code. On 503 no_host_available, home_host_unavailable: the launch is pinned to the host that holds the caller’s home for this app (Amendment 53: or it is pinned to the host of the caller’s Steam home for a sharing launch) and that host is offline or no longer enrolled. Only an admin clears it, so a client does not spend its automatic retry on it. Names no host. Amendment 53 (#1001), on 409 home_in_use: steam_library_open_in_desktop (the holder mounts the Steam library as a shared home) or steam_game_running (the refused launch shares the library and a Steam session holds it); absent when the holder is already stopping. Open string: a client treats an unknown value as absent.
Examplegenerated
{ "error": { "code": "example", "message": "example", "live_sessions": 1, "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "derived_tiles": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example" } ], "reason": "example" }}Run_not_active - the run is already terminal and there is nothing to stop.
object
object
E.g. validation_failed, unauthorized, forbidden, not_found, conflict, session_quota_exceeded, home_in_use, home_not_provisioned, parent_app_disabled, profile_ineligible, profile_not_launchable_for_app, no_host_available, capacity_exhausted, host_not_ready, restart_required, stale_revision, unsupported_source, approval_superseded, approval_expired, attempt_conflict, cancel_too_late, retry_exhausted, home_conflict, placement_ineligible, inherited_placement, recovery_uncertain, rate_limited, internal. Open string, not an enum: new codes are additive and an unknown one falls through to a client’s generic per-status branch.
Present on restart_required.
Steam library discovery Phase 3, ADDITIVE: present on home_in_use when the guard could name the CONFLICTING live session - the one already holding the home. It is here so the client can offer “go to your running session” with a link instead of a dead-end toast. OMITTED rather than empty when the conflict is known but the session is not, so a client branches on presence and never renders a link to nowhere. Also omitted when the holder is the caller’s parked session or released runtime (amendment 39). Load-bearing once derived tiles exist: the lock is held by the PARENT’s home, so a user who clicks a game tile can be refused because a DIFFERENT app (the Steam launcher, or another game from the same install) is running, and without the session id the refusal reads as a bug. See control-api.md §Derived tiles.
Steam library discovery Phase 3, ADDITIVE: present on the 409 conflict from DELETE /v1/apps/{id} when the app has derived tiles and ?delete_derived=true was not sent. A LIST, not a count - the point of the confirmation is that the admin sees what they are about to destroy. Capped; an empty array means the tiles could not be listed, never that there are none.
object
Amendment 40 (#602), ADDITIVE: a machine-readable cause under code. On 503 no_host_available, home_host_unavailable: the launch is pinned to the host that holds the caller’s home for this app (Amendment 53: or it is pinned to the host of the caller’s Steam home for a sharing launch) and that host is offline or no longer enrolled. Only an admin clears it, so a client does not spend its automatic retry on it. Names no host. Amendment 53 (#1001), on 409 home_in_use: steam_library_open_in_desktop (the holder mounts the Steam library as a shared home) or steam_game_running (the refused launch shares the library and a Steam session holds it); absent when the holder is already stopping. Open string: a client treats an unknown value as absent.
Examplegenerated
{ "error": { "code": "example", "message": "example", "live_sessions": 1, "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "derived_tiles": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example" } ], "reason": "example" }}