From a3aa03e14d57b6a4b0eaab6734d7f3bf821d6536 Mon Sep 17 00:00:00 2001 From: Jeena Date: Sat, 12 Sep 2026 21:36:03 +0900 Subject: [PATCH] readme: Document sharing agent state via symlinks in container home --- README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/README.md b/README.md index 39e892e..3bba44d 100644 --- a/README.md +++ b/README.md @@ -100,6 +100,34 @@ ln ~/.gitconfig ~/.local/share/agent-container/container-home/.gitconfig Avoid linking sensitive files such as `~/.ssh/id_*` or `~/.gnupg/` -- keeping those out of the container is an intentional security boundary. +## Sharing agent state between host and container via symlinks + +State directories such as `.claude/`, `.pi/`, or `.agents/` can be shared between the +containerized tools (`claude`, `pi`, `opencode`) and their local variants +(`claude-local`, `pi-local`, `opencode-local`). Keep the real data in the container home +and symlink to it from your real `$HOME`: + +```sh +mkdir -p ~/.local/share/agent-container/container-home +mv ~/.claude ~/.local/share/agent-container/container-home/.claude +ln -s ~/.local/share/agent-container/container-home/.claude ~/.claude +``` + +The direction matters: the real directory must live in the container home, and the +symlink must be in the host `$HOME`. The container mounts the container home as +`/home/`, so inside the container the path is a regular directory. The host +`$HOME` is never mounted into the container, so a symlink pointing the other way would +not resolve inside the container. + +On the host, `~/.claude` resolves to the same data the container sees, so logins, +settings, and history are shared by both sides without copying or syncing. The same +works for single files like `.claude.json` if a tool needs them on the host too. +Repeat the two steps for other state directories (`.pi`, `.agents`, +`.config/opencode`, ...) as needed. + +If `XDG_DATA_HOME` is set to a non-default location, use that path instead. As with +hard links, never share sensitive files such as `~/.ssh/id_*` or `~/.gnupg/`. + ## OpenCode plugins The repository ships an OpenCode plugin in `plugins/opencode/`: