What happened
The phantom container was recreated ~2026-06-09T23:58Z (image update on the host). Everything the agent had accumulated outside the six named volumes was destroyed with no warning and no marker:
- All user-installed toolchains under
/home/phantom: gh CLI, nvm + node, go, cargo, python/uv, hadolint, ~/bin helper scripts
/home/phantom/services/: a long-lived bridge server backing a live product, plus its watchdog and supervise scripts. The public endpoint 502'd until the bridge was rewritten from its consumer-side contract (~75 min of downtime)/app/projects/: weeks of project docs, roadmaps, and decision logs~/.config/truffle/: env wiring and credential files (recoverable from the secrets store, but only because the values happened to be stored there)- The
~/repos symlink into the phantom_repos volume, which made the surviving clones look lost until inspected
docker-compose.yaml:42-53 mounts exactly six paths: /app/config, /app/phantom-config, /app/data, /app/public, /app/repos, /home/phantom/.claude. Everything else an agent writes is container overlay.
Why it matters
Phantom's premise is a persistent agent: "Your workspace, your knowledge, and your capabilities persist and compound over time." The agent naturally treats its home directory as durable (installing toolchains, deploying services, keeping working notes), and nothing in the runtime tells it otherwise. The failure is silent: no signal fires on first boot after a recreate, so the agent discovers the loss mid-task when a source ~/.config/truffle/env.sh fails.
Options, smallest first
- Document the persistence map in the agent-facing system prompt (the Docker notes section already says "Your data (config, memory, web pages, repos) persists in Docker volumes"; it should also say which paths do NOT, in particular
$HOME).
- Drop a first-boot marker (e.g.
/app/data/.container-id checked against the current container id at startup) and surface "this container was recreated; overlay state from the previous container is gone" in the first session after a recreate.
- Add a
phantom_home:/home/phantom volume so the agent's home survives recreates the way ~/.claude already does. This is the strongest fix but changes upgrade semantics (stale toolchains persist across image updates), so it may want to be opt-in.
Happy to PR whichever direction fits. 1 + 2 are small and composable; 3 is a one-line compose change with documentation implications.
What happened
The phantom container was recreated ~2026-06-09T23:58Z (image update on the host). Everything the agent had accumulated outside the six named volumes was destroyed with no warning and no marker:
/home/phantom: gh CLI, nvm + node, go, cargo, python/uv, hadolint,~/binhelper scripts/home/phantom/services/: a long-lived bridge server backing a live product, plus its watchdog and supervise scripts. The public endpoint 502'd until the bridge was rewritten from its consumer-side contract (~75 min of downtime)/app/projects/: weeks of project docs, roadmaps, and decision logs~/.config/truffle/: env wiring and credential files (recoverable from the secrets store, but only because the values happened to be stored there)~/repossymlink into thephantom_reposvolume, which made the surviving clones look lost until inspecteddocker-compose.yaml:42-53mounts exactly six paths:/app/config,/app/phantom-config,/app/data,/app/public,/app/repos,/home/phantom/.claude. Everything else an agent writes is container overlay.Why it matters
Phantom's premise is a persistent agent: "Your workspace, your knowledge, and your capabilities persist and compound over time." The agent naturally treats its home directory as durable (installing toolchains, deploying services, keeping working notes), and nothing in the runtime tells it otherwise. The failure is silent: no signal fires on first boot after a recreate, so the agent discovers the loss mid-task when a
source ~/.config/truffle/env.shfails.Options, smallest first
$HOME)./app/data/.container-idchecked against the current container id at startup) and surface "this container was recreated; overlay state from the previous container is gone" in the first session after a recreate.phantom_home:/home/phantomvolume so the agent's home survives recreates the way~/.claudealready does. This is the strongest fix but changes upgrade semantics (stale toolchains persist across image updates), so it may want to be opt-in.Happy to PR whichever direction fits. 1 + 2 are small and composable; 3 is a one-line compose change with documentation implications.