Backups

q15 keeps everything in files, so a backup is a copy of a folder. There is no backup command, no export format and no vendor to ask: you copy volumes, and you are done.

What to copy

In the order of how much it hurts to lose.

What	Where it lives	Why it is on the list
The transcript and memory	q15_memory → /memory	Every turn, everything the agent learned, and the identity files. Nothing recreates it.
The project tree	q15_workspace → /workspace	The files the agent worked on and produced, plus the embedding source registry.
Skills	q15_skills → /skills	Procedures you taught it. Cheap to copy, annoying to rewrite.
Job definitions and records	q15_agent_state → /var/lib/q15/agent	Every scheduled job and its run history.
Media	q15_media → /media	Attachments you sent and media the agent generated.
The credential store	q15_web_state → /var/lib/q15-web	Your passkeys. Private material. See the warning below.
Your deployment directory	deploy/compose/ and its siblings	The Compose file, agent-config.yaml, proxy-policy.yaml, secrets/, auth/.

The volumes are only half a backup

A memory volume without the deployment directory that mounts it is a folder with no stack. Copy both, ideally into the same snapshot, so they cannot drift apart.

q15_web_state holds credential material. Keep its copies private, and read the restore warning below before you use an old one.

What you can lose on purpose

• q15_exec_nix_store → /nix. Packages rebuild on demand. The first command after a restore is slower than the ones after it.
• q15_tei_hf_cache → /data. Embedding model weights, downloaded again on first start.
• q15_qdrant_storage. The vector collections. They can be rebuilt from their sources with a full sync, which costs embedding time on a local backend and money on a hosted one. Keeping the volume is cheaper than re-embedding a large library.
• q15_bridge → /run/q15. A socket. Nothing in it survives a restart anyway.
• q15_proxy_state → /var/lib/q15/proxy. The proxy’s CA and policy revision. Regenerating the CA is fine: the executor fetches the new one at startup.

How to actually do it

Two shapes, and you want both:

1. Snapshots, on the host, often. If your filesystem does snapshots (btrfs, ZFS), take them hourly and keep a rotation. This is your protection against the mistake you make this afternoon.
2. An encrypted copy, somewhere else. A restic or borg job against the volume directories, to a target that is not this machine. This is your protection against the disk dying, the machine being stolen, and you.

The named volumes live under the container engine’s storage root, which for a rootless install is inside your home directory. Back up the volume directories from the host, or bind-mount the data where your backup tool already looks.

Encrypt one of the two. The volumes are plaintext files on disk: what protects them is disk encryption on the host, or encryption in the backup tool. Assume the copy leaves your machine.

Restoring, in order

1. Stop the stack. Do not restore underneath a running agent.
2. Restore the volumes, keeping the volume names. The names are part of the contract: a restored volume under a new name is not mounted.
3. Restore the deployment directory next to it, with the same secrets/ and auth/ contents.
4. Start the stack and wait for health. The agent upgrades stored history to the current schema on first start, which is a one-way operation.
5. Check the stack’s health, which today means the container health checks and the log lines that name a missing input (q15 doctor is the goal, and is not built), then sign in and send a message.

Three things that bite:

• Restoring an old credential store resurrects devices you revoked. Revoke them again before you expose the service, or delete the old sessions.
• A schema upgrade does not roll back. If you restore an older agent together with a newer memory volume, the agent will not read it. Restore the matching pair.
• A restored job keeps firing. Jobs are files in the agent state volume, with their own schedules and their own pinned models. Expect them to resume, and check schedule_list afterwards.

Test it once

A backup you have never restored is a backup you do not have. Copy the volumes somewhere harmless, start a second stack against the copies on another port, and send it one message. Once, and you will know.

Where to go next

• Updating for what changes between releases.
• Troubleshooting when the restored stack will not come up.
• Reference for the volume table with mounts and contents.