> The durable project tree that survives restarts and upgrades.

`/workspace` is not ephemeral scratch space. It is the durable working state for a q15 stack.

## What lives here

- Your project files and working directory
- Embedding source registry at `/workspace/.q15/embed/sources.json`
- Embedding sync state at `/workspace/.q15/embed/state.jsonl`
- Any files the agent creates, edits, or downloads during its work

## Persistence model

| Deployment            | Expectation                         |
| --------------------- | ----------------------------------- |
| **Compose**           | Required named volume or bind mount |
| **Local development** | May start empty, populated later    |

A newly created stack may attach an empty persistent volume. That empty initial state is valid. Operators may populate it later through normal agent work or manual setup.

The key expectation is that `/workspace` **remains attached to the same stack over time**. Restarts, redeployments, and upgrades should preserve the existing volume. Do not downgrade it to an ephemeral mount (`emptyDir`, anonymous volume, or temporary bind location).

## Files the agent sends and receives

Attachments and generated media live in the media store at `/media`, not in the project tree. When you
send a photo in the browser or in Telegram, the agent stores it under a content hash and attaches that
reference to your message; when the agent sends something back, it comes from the same store. The
project tree holds your work, and the media store holds what came through a chat window.

## What does not live here

- Agent identity and memory live under `/memory`
- Skill artifacts live under `/skills`
- Attachments and generated media live under `/media`
- Nix store state lives under `/nix`
- Proxy state lives under `/var/lib/q15/proxy`

These are separate persistent volumes, each with its own ownership and lifecycle. What each one costs
you is worth knowing before you decide what to copy:

- **`/nix`** is the executor's package store. It grows with every package the agent has fetched, and it
  is the one volume you can throw away: the packages come back on demand, and the first command after
  a restore is simply slower than the ones after it.
- **`/workspace` and `/memory`** are the two that cannot be recreated. They are what
  [Backups](/backups/) exists for.
