# Update your Impreza agent

Source: https://docs.imprezahost.com/agent-updates.html

Portal and direct REST orders default to **No app**, without an Agent. An MCP purchase requests the Impreza Agent (`@agent`) when the app is omitted; see [Connect MCP](/tutorials/ai-mcp-integration.html#prereqs). Choose another initial app explicitly, or add the Agent later on an eligible server. Installing the Agent and connecting MCP are separate actions. Existing servers keep their installed version until you choose to update. Nothing updates your fleet automatically: channels and cohorts only shape what the portal offers, and every update is an explicit action on your side. Current stable: **0.6.37**.

Agent 0.6.37 makes onion readiness and staging clones more accurate. An onion address is reported ready only after Tor confirms that it published the service, instead of probing the address from outside. A staging clone of an app that runs as a fixed user, such as Memos, keeps that user and gets no extra capabilities. The release also includes code for maintenance features that are not released yet; it stays inactive, and nothing changes on your server until a feature is released and you turn it on. As with every release, updating is your explicit action: finish active operations first; agents 0.6.22 and later can update from the portal, API or MCP, and older agents update once with [`update.sh`](#check-update). Identity, configuration and applications are preserved.

Agent 0.6.36 makes domain changes and builds safer. Changing an application's domain keeps the current domain serving until the new one is proven, and an interrupted change is either finished or undone, so the application is not left without a working address. The Tor sidecar runs exactly the Tor version pinned by its image digest. A custom build refuses changed inputs before any container starts. As with every release, updating is your explicit action: finish active operations first; agents 0.6.22 and later can update from the portal, API or MCP, and older agents update once with [`update.sh`](#check-update). Identity, configuration and applications are preserved.

Agent 0.6.35 reports the public route of a deployment and hardens the updater. A deployment result now says whether the existing public HTTPS check confirmed the application's address, and warns when the public route could not be applied; the application stays installed either way, and the result is one observation at deployment time, not continuous monitoring. The updater now checks the offered agent's size, digest and embedded version before it touches the installed ingress boot unit, so a refused update leaves the installed agent and its boot unit unchanged. As with every release, updating is your explicit action: finish active operations first; agents 0.6.22 and later can update from the portal, API or MCP, and older agents update once with [`update.sh`](#check-update). Identity, configuration and applications are preserved.

Agent 0.6.34 tightens two agent behaviors. The IPv6 egress guard now drops forwarded traffic to link-local (`fe80::/10`) and unique local (`fc00::/7`) addresses and to the IPv4-mapped cloud metadata address before the rule that accepts port-forwarded traffic, so a published port cannot be used to reach those ranges; port forwarding to a unique local address on the server's own Docker bridge keeps working. An agent that Impreza runs as an uptime-check vantage point now runs only its checks: while that setting applies it no longer polls for commands, sends heartbeats or reports metrics, it keeps picking up changes to its check targets, and removing the setting brings normal operation back.

Agent 0.6.33 makes removals and cleanups more trustworthy. Uninstalling an app now reports success only after the agent has confirmed that its containers are gone, including containers started under a legacy Compose project name; if one survives, the uninstall fails and keeps the app's configuration so you can retry. The first proxy reload after the agent starts waits until the local proxy admin is ready instead of failing while it is still starting, a full queue of accepted backup cleanups no longer holds the next command, and after a database promotion the agent removes a transit schema only when it is empty and belongs to the same owner.

Agent 0.6.32 makes restores and data folders sturdier. The agent now creates the bind mounts under an app's `./data` itself, refusing symbolic links, before it applies the data owner, so an image that runs as a non-root user can write its own state on the first start. A restore that cannot be verified keeps its app quarantined for more operations (onion address rotation and removal, failover receipt and traffic switches toward it) until support reconciles it, while health checks, logs and moving traffic away keep working. Restore waits survive an agent restart without starting over, a restore job that disappears mid-exchange is stopped and reported, old release copies no longer keep a service-binding password after it was rotated or removed, and the working folder of a finished app backup is removed once the result is acknowledged.

Agent 0.6.31 makes domain changes more patient with certificate issuance. After you change an app's domain, the agent checks HTTPS on the new name for up to three minutes, long enough for the certificate authority to retry once while the new DNS record propagates, instead of giving up after the first attempt. If the new certificate still is not ready, the previous domain keeps serving and the error now says that the new domain's certificate did not become ready in time; you can retry the change once DNS has propagated.

Agent 0.6.30 makes zero-downtime redeploys reload-free. A deployment's proxy route now carries both the running container and the standby slot with an active health check, so a swap only starts and stops containers: the new version is started and proven before the old one stops, and the proxy configuration does not change during the swap. That removes the request a proxy reload used to drop. The health check requests each upstream's readiness path twice a second, so expect those requests in your app's access log. A git redeploy now replaces the build context with two directory renames and restores the previous context if the swap fails between them. The installer downloads the agent binary through the same verified, https-only fetch as the signed manifest, allows up to three minutes on slow links and installs the ingress boot unit from the start; updating an older agent repairs that unit when it is missing. Egress firewall updates from the agent and from the `impreza-agent` command on the same server now take turns through a lock file.

Agent 0.6.29 makes updates safer. After installing a new version, the updater now watches the agent service for thirty seconds and rolls back to the previous version if the service restarts at any point in that window, so a release that crashes a few seconds after starting is no longer kept. A version that first fails more than thirty seconds after starting is still kept: check the agent again if it stops reporting. Reapplying the network egress rules is now serialized inside the agent, so the periodic reconcile, a firewalld reload and a deployment that creates the proxy network can no longer remove each other's rules. The installer fix for servers without Docker (a fresh install no longer stops with "invalid pinned version" after installing Docker) was already served by `install.sh` before this release.

Agent 0.6.28 measures readiness on the clock: a service without a Docker healthcheck counts as ready only after a full readiness window has passed since its last restart, and a sidecar that keeps restarting next to a healthy service is no longer reported ready. A failed git clone no longer takes down the running application, because the new source replaces the previous one only after the clone and the pinned-commit checkout both succeed. Every Docker network the agent creates gets the egress rules immediately, and a deploy fails instead of leaving a new network without them. A deployment whose `compose.yaml` is missing uninstalls and rolls back cleanly. Responses read from the control plane are size-capped. It also adds the agent-side support for pull-request previews, the host inventory and public status pages on the app's onion address; each follows the platform's own rollout. **The installer changed too:** `install.sh` now verifies the channel's signed release manifest before downloading, resolves the version through it and no longer pipes a remote script into a shell to install Docker.

Agent 0.6.27 brings Shield v2 to the managed proxy: the web application firewall with an IP allowlist, an under-attack mode, per-path proof-of-work challenges and per-window request counters, configured per route from the portal, the API or MCP. The first deploy with a route after the update (or the agent start, on servers with onion services) recreates the proxy container on the new image and keeps its certificates and data; routes without a Shield configuration are untouched. It also adds the ready swap on redeploy: when you opt in, the new release starts and its readiness is checked before traffic moves to it, and the previous release keeps serving until then. An uptime probe ships as groundwork and changes nothing until the platform enables it.

Agent 0.6.26 answers instead of leaving work pending. When the agent is interrupted during an operation and will not repeat it, the server receives a readable failed result: a verified preparation says what was restored, and anything that cannot be verified says so and asks you to retry explicitly. A supervised worker that stopped without a receipt no longer holds later commands for the same server. A network failure while the agent delivers a result no longer marks the application for recovery review. Every update also installs or repairs the agent's network boot unit, which restores the agent's host rules before Docker starts. If enabling it fails, `update.sh` names the repair command (`systemctl enable impreza-agent-ingress.service`) and exits with status **3**: the new agent is installed and running, and the agent retries the enable once at startup. Treat status 3 in your automation as "updated, follow the printed repair step".

**Connections from containers to the server itself.** Agents 0.6.21 to 0.6.24 drop new connections from containers to services on the server itself, ahead of your firewall rules; earlier notes did not say so. **Agent 0.6.25 lets your firewall decide first**: a host port your firewall allows, and the ports the server publishes, are reachable from containers again, and you can allow a port or turn the block off with `impreza-agent egress host`. If an application reaches a database, cache, mail relay or other service running directly on the server, or calls the server's own address, update to 0.6.25 and read [connections from containers to the server itself](deployment-safety.html#container-to-host).

Agent 0.6.25 moves the container-to-host rule to the end of the server's `INPUT` chain, so your firewall (UFW, firewalld or your own rules) decides first, and keeps it there after `ufw enable` and reboots. Ports the server publishes through Docker, such as the proxy on 80/443, are reachable from containers through the server's own address, which also fixes WordPress loopback requests (WP-Cron, Site Health) behind the proxy; other host services and the cloud metadata endpoint stay closed to containers. A restore of an application's files stops the application only for the exchange of its data, puts the previous data back if the exchange fails, and resumes after an agent restart; the application stays stopped while a restore job may still be writing to it.

Agent 0.6.24 keeps the shared reverse proxy running across deploys: it is recreated only when its image, its settings or the agent's credentials change, instead of on every deploy with a route, which left every application on the server without HTTPS for a few seconds. The first deploy with a route after the update replaces it once, and a value that leaves the proxy's environment, such as the agent's previous credentials after a re-registration, recreates it once so it never keeps a removed value. An application is reported as down in its metrics as soon as any service its Compose file declares stops. Docker Compose runs on each application's own project and file, so no deployment variable can point it at another application, and variables named `COMPOSE_*` or `DOCKER_*` are refused. Applications bound to a managed MariaDB database can be rolled back again, and memory and volume usage are reported with real numbers.

Agent 0.6.23 keeps a server's command queue moving when image preparation goes wrong. A large image pull keeps downloading on an extended budget, up to 45 minutes. A pull that stalls or reaches that limit, a build that runs past its ten-minute budget, and a pull or build whose worker stops without a result each end the deployment as a retryable failure with the previous configuration restored. Before, a build like that could stop the agent from running any later command on the server, uninstalls and updates included. If the server already closed a deployment the agent was still recovering, the agent verifies and restores the previous configuration and moves on. Deployment variables now reach the application's `.env` file literally: `$`, `${...}`, quotes, backslashes and ` #` are no longer interpreted, and one value can no longer define another variable. If a value relied on another variable expanding inside it, set the final value directly.

Agent 0.6.22 changes an application's domain through a verified handover, accepts update requests from the portal, API and MCP, and runs the Impreza Shield proxy image. New deployments start on the standard Shield profile, which audits and never blocks; existing deployments are not migrated and keep Shield off. After the update, a server with onion services moves the shared proxy to the new image when the agent starts; other servers move at their next deployment. Certificates are kept.

Agent 0.6.21 runs Tor image 1.0.1. An upgraded tor package resets the owner of the Tor data directory, and earlier agents cannot start Tor after that, so update before deploying an onion service. On a server that already hosts onion services, the updated agent moves Tor to the new image when it starts.

Agent 0.6.16 adds [traffic switching](project-environments.html#candidate-environment-workflows), [verified PostgreSQL backups and assisted restore](service-bindings.html#candidate-database-backups), and [protected previews and the Docker egress baseline](deployment-safety.html#candidate-security-controls). Each workflow checks its required capabilities; publishing a new version does not upgrade existing servers automatically.

Agent 0.6.3 adds [required healthy startup](/tutorials/agent-apps-panels.html#required-startup), including first deployments, with a configurable deadline. This option is disabled by default. Older installations must be updated explicitly before enabling it.

**Release status.** The [per-server update policy](#update-policy) — channel, pin and maintenance window — is available in the portal, the REST API, the hosted MCP connector and local `impreza-mcp` 0.46.0 or later. Requesting an update from the portal, API or MCP needs an agent that announces `agent-upgrade-v1` (agent 0.6.22 or later); for older agents the request is refused before anything is queued, so update them once with the server commands in [Check and update](#check-update). The stable channel publishes a signed manifest since 25 September 2026.

## Account tokens and agent registration

Anonymous-account MCP tokens issued by `impreza_bootstrap_account` or
`POST /v1/account/bootstrap` last **15 minutes**. Renew them with the account's
REST key; older anonymous-account MCP tokens without an expiry expire on
**16 October 2026 at 21:48 UTC**. See
[anonymous-account renewal and privacy](/tutorials/ai-mcp-integration.html#anonymous-account).
This deadline is separate from the **10-minute agent registration bootstrap
token** and from an enrolled agent's credentials. MCP expiry does not require
reinstalling or re-registering an agent. Updating the agent does not renew an
account MCP token. The account-creation IP is cleared after 24 hours on the next
cron pass; this cleanup does not erase backups or persistent account metadata.

## Signed release channels

Releases are published per channel — `stable` and `beta` — and a channel that
publishes a signed manifest (`manifest.signed.json`) is verified end to end
before anything is installed:

- an **Ed25519 signature** over the whole manifest, produced by an offline
  signing process with two-person release rules;
- a **short expiry** (at most seven days), so a channel that stops publishing
  goes stale on purpose instead of serving an old head forever;
- a strictly increasing **sequence**; the offline signer checks the release
  chain, while each server refuses rollback or same-sequence equivocation and
  checks the predecessor digest when it receives the next adjacent sequence;
- the **artifact digests** from the signed manifest itself, not from a
  sidecar file fetched from the same origin.

Once a server has accepted a channel's manifest, the verified path is
mandatory: a later missing, expired, rolled-back or tampered manifest
refuses the update instead of falling back to unverified checksums. A
channel without a manifest keeps the documented checksum behavior, and a
version pinned with `IMPREZA_AGENT_VERSION` always uses the per-release
checksum path. Verification needs `python3` and `openssl` (1.1.1 or newer)
on the server.

The update can also be served from a mirror such as the `.onion` artifacts
host: set `IMPREZA_AGENT_RELEASE_BASE` to the mirror's releases URL and,
when it should be reached through Tor, `IMPREZA_AGENT_SOCKS_PROXY` to the
local SOCKS listener (for example `127.0.0.1:9050`). The manifest signature
still gates everything a mirror serves.

## Check and update

On the server, check the installed and available versions:

```
curl -fsSL https://raw.githubusercontent.com/imprezahost/agent-public/main/update.sh | sudo sh -s -- --check
```

After all deployment operations have finished, apply the update:

```
curl -fsSL https://raw.githubusercontent.com/imprezahost/agent-public/main/update.sh | sudo sh -s -- --apply
```

The command discovers the channel head automatically. Use
`IMPREZA_AGENT_CHANNEL=beta` to track the beta channel. If an older saved
updater reports `Invalid release version`, fetch the current updater again
using the command above. A manual version override is not required; keep
checksum, manifest and embedded-version verification enabled.

No bootstrap token is required. This command also works on older agents such as 0.5.1. The updater verifies the release — signature and digests for a channel with a manifest, SHA-256 and embedded version otherwise — then replaces the executable atomically. It restarts only the agent, keeping its identity, configuration and app containers. If startup fails, it restores the previous executable.

## Per-server update policy

Each server carries its own update policy, readable and changeable through
the portal, `PUT /v1/platform/servers/{agent_id}/update-policy` and the
`impreza_get_update_policy` / `impreza_set_update_policy` MCP tools:

- **Channel** — `stable` or `beta`. Selects which head the portal offers and
  which command it shows.
- **Pinned** — freeze a server to an exact version. A pinned server never
  receives update offers; changing the channel back re-enables them.
- **Maintenance window** — a daily UTC window (`HH:MM` to `HH:MM`). Update
  requests outside the window are refused with the reason.

When the channel's manifest advertises a minimum supported version, servers
below it show an **end-of-life notice**. The notice never forces an update:
run the command when you are ready.

The policy shapes offers only. Queueing an update is a separate, explicit
action: `POST /v1/platform/servers/{agent_id}/agent-update` or
`impreza_request_agent_update` with `confirm=true`. The request is refused
while any operation is pending on the server, outside the maintenance
window, when the agent is pinned, already current, or does not announce
`agent-upgrade-v1`. The job completes as verified only when the next
heartbeat reports the new version.

## Pause and resume dispatch

The reversible server pause stops **command dispatch** and temporarily suspends
AI credentials bound to that server, including descendants of a bound
credential. It does not stop application containers or commands already sent.
Pause and resume require an authorized action and explicit confirmation.

A pause is not a blanket refusal of every API or portal request. Guarded actions,
including creating a backup on the paused server, return `AGENT_PAUSED` (HTTP 409).
Some preparation and failover requests can still be accepted: metadata or queued
work may remain pending while polling refuses to dispatch. Accepted queued work
can run after you resume. Pause is not cancellation; cancel unwanted work before
resuming. Do not use a pause as an account-wide maintenance lock.

Resuming restores only unexpired, unrevoked server-bound credentials. It does
not widen their permissions or resource scope, and it does not make a stale
agent online. The server pause is available in the portal, REST and MCP; failover
availability remains subject to its separate rollout gate. This clarification
does not enable a gated workflow or request an automatic fleet update.

## Portal and MCP

Under Your servers, open the agent update option to see the channel, pin,
maintenance window, end-of-life notice and the command to copy. The portal and `impreza_list_servers` expose update information from `GET /v1/platform/servers`. An unknown installed/latest version produces an unknown availability status, not a claim that the agent is current. Run the command on the correct server; listing servers does not execute an update.

Confirm the new version after the next heartbeat. Local service startup does not prove that the API can be reachable. Update only when deployments are idle; the updater does not drain queued commands. It refuses downgrades and does not support custom executable/service paths.

[Deployment safety and rollback](/deployment-safety.html)

Read [current runtime health and deployment results](/runtime-health.html) separately. A failed deployment can leave the previous app running; old observations do not confirm current health.

To stop queued work or preparation before container replacement, see [Cancel a deployment](/deployment-cancellation.html).

Read [Deployment progress and interrupted agents](/deployment-progress.html) for step reports, persistent result delivery, supervised pull/build completion in agent 0.6.8+ and operations that require reconciliation.

Agent 0.6.9+ adds [supervised replacement after an agent restart](/deployment-progress.html#supervised-replacement): the original runtime worker completes once and its final result is delivered without repeating containers or hooks. Missing or invalid final receipts still require support.

## Transport protection update

Agent 0.6.10 refuses API redirects, including bootstrap, polling and heartbeat requests carrying agent credentials. Configure the final API URL directly. Installing a newer SDK on a workstation does not update a running agent binary; existing agents require the explicit update command above.

## Deployment input and recovery update

Agent 0.6.11 adds build credential delivery, retained Compose source files and guarded preparation recovery after a host reboot. Update explicitly before using these capabilities. Local MCP inputs require 0.34.0+. Existing operations do not gain recovery support retroactively. See [project plans](/project-plans.html), [Compose imports](/compose-import.html#source-candidate) and [reboot recovery](/deployment-progress.html#reboot-preparation-candidate).

## Controlled builds

Agent 0.6.12 adds optional [controlled builds](/deployment-cancellation.html#controlled-builds) that can interrupt an owned build before application replacement. Activation is a separate administrator command on supported Ubuntu 24.04 amd64 servers; upgrading the binary alone does not enable it. No automatic fleet update is performed.

Agent 0.6.13 supports [reviewed PostgreSQL connections](service-bindings.html), including dedicated login creation, data-preserving removal and recovery of a verified retirement receipt. [Credential rotation](service-bindings.html#rotation) additionally requires an agent announcing `postgres-service-binding-rotation-v1`; an older agent refuses the rotation command and the failed job directs you to update explicitly.


## Metrics and MariaDB support

Agent **0.6.17** adds per-application resource metrics and managed MariaDB
connection creation, removal and rotation. Older agents cannot report these
metrics or execute the new database protocol. Update explicitly with the command
above; the portal does not upgrade the fleet automatically. See
[application operations](customer-workflows.html) and
[database connections](service-bindings.html).


## Verified MariaDB recovery

Agent **0.6.18** adds verified MariaDB table backups and reviewed restoration
into a new database. Recovery jobs use temporary database logins and clean them
up before returning success. Existing MariaDB binding grants are normalized to
exact database names when the customer next deploys that binding. Updating the
agent alone does not redeploy applications or rotate their credentials.
See [supported data and recovery limits](customer-workflows.html#restore).

## Onion service controls

Agent **0.6.19** adds onion service protection profiles, client authorization and
reviewed identity import, export and rotation. Update explicitly after active
operations finish. Onion reconciliation can briefly interrupt onion connections
while Tor restarts; application containers keep running. See [onion services](/onion-services.html)
for required permissions, client versions and recovery limits.

## Signed advisory database

Agent **0.6.20+** includes source review and the trusted public key for its signed
advisory database. Inspect or refresh that database with:

```sh
sudo impreza-agent advisories status
sudo impreza-agent advisories update
```

`status` includes `trusted_key_sha256` when a trust key is configured, even if no
database is available yet. The production key fingerprint is
`29a64f4eff2331ef46891bfe6537f939a1c051f4cba28a79476bbefa5c64d6b3`.
The key is built into the agent; no signing secret is installed on the VPS.
An explicit root configuration can select another trusted publisher.

These commands refresh signed advisory data, not the agent binary. Refresh also
runs at startup and every six hours, honoring the agent's Tor/SOCKS transport.
Invalid or older data is refused and the last verified cache is retained. Expired
data is stale. The signed feed is published and refreshed daily;
see [source review and coverage limits](/deployment-safety.html#source-scan).