Updates and rollbacks

A q15 release is one set of four images, never a mix:

• ghcr.io/q15co/q15-agent
• ghcr.io/q15co/q15-exec
• ghcr.io/q15co/q15-proxy
• ghcr.io/q15co/q15-web

The agent and the browser client share a bridge protocol, so a mixed set is not a supported configuration: the web tier refuses to start on a protocol mismatch rather than misbehaving quietly.

How you update

The release you are on lives inside the q15 binary. Install a newer one, then re-render and restart:

curl -fsSL https://q15.co/install.sh | sh   # the new release, over the old binary
q15 up                                      # re-render the units at the new tag, wait for health
q15 doctor                                  # binary, rendered units and running containers agree

doctor compares all three: the release the binary carries, the tag in the rendered units, and what is running. If something is out of step, that is the check that says so.

Everything in a volume survives an update: /workspace, /memory, /skills, /media, the agent’s state, the proxy’s state, the web tier’s credential store, and Qdrant’s collections. Models download again only if they are missing.

Rolling back

Install the older q15 and run q15 up again. Storage is preserved in both directions.

Two things do not roll back by themselves:

• Schema upgrades. A newer agent may have upgraded the transcript schema in the memory volume, and an older agent will not understand it. Restore the pre-update backup first.
• Credential state. The web tier’s store carries its own version. Sessions issued under the old format are discarded, so you sign in again. Restoring an older copy of that store can also resurrect devices you had revoked: revoke them again before exposing the service.

Never delete volumes to stop a stack

A stop command with -v deletes the volumes, which is every piece of state above, including the credential store. Stop the stack without it.

While the installer is not built

Today the stack is a Compose project and the release is a line in a file: Q15_IMAGE_TAG in deploy/compose/release.env. Set it, pull, and roll.

podman compose --env-file deploy/compose/release.env \
  -f deploy/compose/docker-compose.image-first.yml pull
podman compose --env-file deploy/compose/release.env \
  -f deploy/compose/docker-compose.image-first.yml up -d --wait

On Docker, docker compose in place of podman compose; nothing else changes. --wait returns only when every health check passes, so the command ending is your answer. The Reference has the files, the volumes and the port rule.

Which tag to pin

Tag	Meaning
stable	A moving tag. It advances on all four packages only after the same release has been published and verified on all four.
YYYY.MM.DD.<run-number>	One immutable release, for example 2026.10.10.84. The same tag always selects one compatible set of four images.

Published tags are on the q15 packages page, and the images pull without registry authentication. Pin an immutable tag if you want control over when your stack moves, and keep a note of the tag you were on: that note is your rollback.

Pull stable after a publish finishes

While a release is still publishing, a pull can land on a torn set. An immutable tag removes that risk, and so does waiting for the publish to go green.

If it will not come up

Roll the tag back first, then read the logs. The cause is almost always one of three: a missing provider credential, a health check that never passed, or a mixed tag set. Troubleshooting takes them one at a time.