Persistence¶
A runtime is disposable. The sessions are not. Everything that must survive a restart, upgrade, or scale-to-zero lives on one volume.
What is on the volume¶
| Path | Owner | Contents |
|---|---|---|
/workspaces/.claude |
Claude Code | Transcripts and config (CLAUDE_CONFIG_DIR) |
/workspaces/.opencode/data |
OpenCode | Session data (XDG_DATA_HOME) |
/workspaces/.codex |
Codex CLI | Config and per-issue session stores (CODEX_HOME) |
/workspaces/.penpot-browser |
design image | Chromium profile with the Penpot session |
/workspaces/.penpot |
design image | MCP/plugin/Xvfb logs |
/workspaces/<task-id> |
Multica daemon | Task checkouts and working files |
The daemon skips dot-directories at the workspace root, so the state directories are never mistaken for task workspaces.
Stale Git worktrees¶
Before starting the daemon, the entrypoint runs git worktree prune on cached
bare repositories under /workspaces/.repos/<workspace>/<repo>.git (or
$MULTICA_WORKSPACES_ROOT/.repos). Interrupted tasks can leave stale worktree
registrations that cause worktree path already exists and is not a valid git
worktree errors.
Pruning is best-effort and preserves locked registrations and valid worktrees. It never deletes task directories or files. Invalid task directories may still need manual investigation; startup pruning is not a repair for every checkout failure.
Checkout path already exists¶
This error can also mean the target is an ordinary directory (even an empty
one or a normal clone with a .git/ directory), not a linked Git worktree.
git worktree prune cannot fix that: it only removes stale registrations.
Multica 0.7.2 itself still rejects such a target. The runtime now wraps
multica repo checkout: on this exact failure, it moves a direct-child directory
without .git into /workspaces/.checkout-recovery/<unique-name>/, prunes stale
registrations, and retries once. Files are preserved, not merged into the new
checkout. Recovery paths are printed to stderr. Concurrent checkouts in the same
task directory are serialized. Valid Git checkouts, symlinks, and paths outside
the workspace are never moved. Other commands execute the original CLI directly.
If automatic recovery refuses the path or retry fails, stop the affected task before manual recovery. Preserve the directory and its cached repository metadata; they may contain uncommitted files or unpushed commits. Prefer a fresh task run rather than changing the old checkout:
multica issue runs <issue-id> --full-id
multica issue rerun-task <run-id> --fresh
Use the relevant run ID from the first command. In Multica 0.7.2, task rerun
--fresh creates a new session and working directory. An ordinary rerun reuses
the previous directory and can hit the same error again. Review the preserved
old files and recover needed changes separately.
Do not confuse this with multica repo checkout --fresh: that flag can discard
changes in a recognized checkout and does not bypass the invalid-path guard.
Do not delete the workspaces volume, run git clean, or fabricate a .git file.
What is not¶
/tmp/multica-db(PHP databases) — recreated on every start;- the OpenCode config at
~/.config/opencode/opencode.json— regenerated at start; - anything the agent installs into the image at runtime (it is thrown away).
That is intentional: a database or a half-installed toolchain inside a runtime is not a source of truth.
Docker Compose¶
A named volume is created on first start:
volumes:
workspaces:
name: multica-workspaces
It inherits the ownership of /workspaces from the image (runner:runner,
1000:1000), so no chown is needed.
Bind mount instead?¶
The container runs as uid/gid 1000. A host directory is usually owned by your own user (often 501 on macOS, 1000 on Linux). Make it writable:
sudo mkdir -p /srv/multica-workspaces
sudo chown -R 1000:1000 /srv/multica-workspaces
Without this, the entrypoint logs a warning and Claude/OpenCode fall back to ephemeral home directories — sessions look like they vanish on restart.
Backup¶
Stop the container (or accept a consistent-enough copy), then archive the volume:
docker run --rm \
-v multica-workspaces:/data:ro \
-v "$PWD":/backup \
alpine tar czf /backup/multica-workspaces-$(date +%F).tgz -C /data .
Restore:
docker run --rm \
-v multica-workspaces:/data \
-v "$PWD":/backup \
alpine sh -c 'cd /data && tar xzf /backup/multica-workspaces-YYYY-MM-DD.tgz'
Amazon ECS¶
Fargate has no persistent local disk. Mount EFS at /workspaces:
- EFS access point with POSIX user
1000:1000; - transit encryption enabled;
- IAM authorization, with a task role that has
ClientMount/ClientWrite.
The task definition in deploy/ecs
wires this up. Without EFS, every task restart starts with amnesia.
EFS is slower than local disk. Checkouts and builds on a large repository will feel it. If that matters, run the runtime on EC2/Swarm with a local volume instead of Fargate, or keep the task alive (scale-to-zero off) so EFS is read once.
Kubernetes¶
The manifest uses a ReadWriteOnce PVC. The pod cannot move to another node while
the volume is attached. For rescheduling, use a ReadWriteMany class and keep one
replica.
Evolution¶
The volume layout is part of the public contract. New state directories are added as dot-directories; existing ones are not moved without a migration note in the changelog.