# Cancel a deployment

Source: https://docs.imprezahost.com/deployment-cancellation.html

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](/agent-updates.html) 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](/runtime-health.html) for the current app. Cancellation does not certify HTTP/DNS/TLS availability or restore database contents. See [deployment safety and recovery](/deployment-safety.html).

Read [Deployment progress and interrupted agents](/deployment-progress.html) 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](/deployment-progress.html#supervised-preparation). 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](/agent-updates.html) 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 status
```

`prepare` 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 disable
```

Disabling 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.