jeena/agent-container
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

readme: Document sharing agent state via symlinks in container home

Browse source
This commit is contained in:
Jeena 2026-09-12 21:36:03 +09:00
parent 336ec1d97d
commit a3aa03e14d
1 changed files with 28 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

28
README.md
View file

@ -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/<username>`, 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/`: