Skip to content

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.