Stop a queued deployment or request a stop before the agent replaces application containers.
From the portal
Open the app card and read Last operation. When the operation is eligible, choose Cancel deployment. The request targets the displayed operation, so an old page cannot silently cancel a newer deploy. Refresh the card to check the outcome.
Request and confirmation are different
| Stage | Result |
|---|---|
| Queued | The job is marked cancelled atomically before dispatch. The agent receives no command for it. |
| Preparing source, pull or build | The request is recorded. With controlled builds enabled, the agent can stop its owned build executor. Otherwise the current preparation step finishes. The agent then verifies cleanup, restores the previous Compose/environment/startup files and confirms cancellation. Existing containers are not replaced. |
| Replacing containers or recovering | Cancellation is refused. The operation must finish its startup or recovery path. |
| Already finished | A repeated cancellation of the same cancelled job succeeds without changes. Other completed results remain unchanged. |
cancellation.state=requested is not confirmation. Wait for last_operation.status=cancelled. A pull or build already running can continue until that step completes, so cancellation may take minutes. A preparation error can instead finish the operation as failed. No application container is force-killed and no data rollback is performed; downloaded sources and prepared images may remain cached.
REST and MCP
Requires manage permission. Read the exact last_operation.command_id from the deployment list or detail, then call:
POST /v1/platform/deployments/{id}/cancel
{"command_id":"cmd_example"}HTTP 200 confirms queued/already-completed cancellation. HTTP 202 records a request awaiting the agent. HTTP 409 means the operation is finished, incompatible or already in replacement/recovery; read the returned explanation. Another account receives 404.
MCP 0.24.0 adds impreza_cancel_deployment with deployment_id and command_id. Poll impreza_list_deployments afterward. Cancelling an MCP Task still only stops tracking; it does not send this deployment cancellation request.
{"command_id":"cmd_example","status":"in_progress",
"cancellation":{"state":"requested","phase":"preparing","can_cancel":false,
"requested_at":"2026-09-14T18:00:00Z","confirmed_at":null}}Agent compatibility and interrupted connections
Queued jobs can be cancelled with older agents. Running cancellation requires agent 0.6.5 or later, advertising deploy-cancel-v1 when the job is claimed. Follow Update your agent before starting the next deploy. The current running job cannot gain this protocol retroactively.
If the replacement checkpoint cannot reach the control plane, the agent fails preparation without replacing containers. If the agent crashes or disappears, an unconfirmed request stays unconfirmed. Controlled jobs are not automatically dispatched again after their deadline: doing so could duplicate work still running. Agent 0.6.6+ resends a saved final result after restart without repeating the operation. Agent 0.6.7+ can reconcile a durable completed preparation checkpoint after restart and confirm an existing cancellation request after restoration. Wait while recovery=reconciling. Unconfirmed external work and uncertain replacement still require support when recovery=required; do not start a second deployment based only on a timeout.
What is preserved
Cancellation supports deploy jobs, including redeploys. It does not cancel restart, uninstall, rollback, backup or other jobs. Build interruption requires the explicit controlled-build setup below. Configuration restoration failure produces failed, never a confirmed cancellation. On an ordinary confirmed cancellation, existing containers and application data remain in place; a first installation never starts its app containers.
The legacy deployment status may be failed to allow retry after cancellation. Use last_operation.status for the actual outcome and runtime health for the current app. Cancellation does not certify HTTP/DNS/TLS availability or restore database contents. See deployment safety and recovery.
Read Deployment progress and interrupted agents for step reports, persistent result delivery and operations that require reconciliation.
For legacy builds, agent 0.6.8+ supports supervised preparation after an agent restart. The original pull/build must finish successfully before interrupted preparation can be reconciled. This does not immediately stop Docker or repeat the deployment.
Opt in to controlled builds
Available in agent 0.6.12 and later. The optional executor supports builds on Ubuntu 24.04 amd64 with systemd, AppArmor, local Docker, the Buildx plugin and Compose supporting an explicit builder. Other operating systems and architectures retain checkpoint cancellation.
Update the agent explicitly while deployment operations are idle. Install the Buildx plugin from the same trusted package source as Docker (Ubuntu packages use docker-buildx; Docker CE uses docker-buildx-plugin). Use the standard executable under /usr/local/bin and persistent state under /var/lib; temporary, home and protected system state paths are refused because supervised workers cannot use them. Then run on the server:
sudo impreza-agent builder prepare
sudo impreza-agent builder statusprepare downloads an immutable pinned executor image, verifies local prerequisites and enables the mode for future builds. It does not re-register the agent, change credentials, update existing apps or change a global Docker builder or host sysctl. It does not install missing host packages. A failed check leaves activation unchanged. Prerequisites are checked again before each owned build; failures do not silently fall back.
Use the existing portal, REST or MCP cancellation command; no new cancellation parameter is required. Only builds created after activation use the owned executor. Source download and image pull still finish their current step. Container replacement and recovery cannot be cancelled. Wait for the final cancelled result; network outages, races and recovery can delay or prevent confirmation.
sudo impreza-agent builder disableDisabling affects future builds. It does not stop active work or erase recovery records. The rootless executor has bounded CPU, memory and PIDs, no host bind mount or Docker socket, and a private state volume. It requires container-local seccomp/system-path exceptions and a scoped AppArmor profile; it is not a security sandbox for hostile code and does not restrict build network egress. Use reviewed project code, especially with build credentials. Its disposable build cache is not retained between jobs; images already loaded into Docker can remain after cancellation.
After agent or host interruption, recovery requires verified worker/resource identity and authenticated operation state. A complete private container-ID receipt can recover a creation response lost before binding. Missing, partial, unsafe or foreign receipts remain blocked for support review. Never delete the operation journal or retry solely because a process disappeared.