agent-container

Run OpenCode, Claude Code, and Pi (pi.dev) inside a shared Arch Linux Docker container that closely mirrors a local development environment, while limiting access to sensitive files on the host.

Features

• Arch Linux-based image with OpenCode, Claude Code, and Pi pre-installed
• Runs as the host user (same username, UID, GID)
• Per-project isolation: Each project gets its own container (identified by project path hash)
• Shared persistent home: All containers mount the same home directory from XDG_DATA_HOME, allowing tools and credentials to persist across projects
• Sudo access: Agents can install project-specific dependencies that persist in the stopped container
• Hard linking support: Can hard link files like ~/.gitconfig to share configurations with containers
• Local variants: opencode-local, claude-local, and pi-local run the tools directly on the host, bypassing the container
• Mounts only the current project directory (same absolute path inside container)
• Security boundary: No access to SSH keys, passwords, or full $HOME (intentionally prevents remote code pushes)

Install

Clone the repository:

cd ~/Projects/
git clone https://git.jeena.net/jeena/agent-container.git

Source the helper file agent.aliases in your shell configuration (.bashrc or .zshrc):

source ~/Projects/agent-container/agent.aliases

This makes the opencode, claude, pi, and agent-container commands available in new sessions.

The container home directory at $XDG_DATA_HOME/agent-container/container-home/ serves as a central $HOME inside every container, independent of which project directory you start in. Everything written to $HOME inside the container persists there.

Environment Variables

Host environment variables matching the following prefixes are automatically forwarded into the container:

• OPENCODE_* -- passed through to OpenCode
• ANTHROPIC_*, CLAUDE_* -- passed through to Claude Code
• PI_* plus provider key prefixes (ANTHROPIC_*, OPENAI_*, GEMINI_*, GROQ_*, OLLAMA_*, and others) -- passed through to Pi. Alternatively log in once with /login inside the container; credentials persist in the shared container home.

This means inline overrides work as expected: OPENCODE_CONFIG=foo opencode

For persistent environment variables, add them to container-home/.bashrc (or .bash_profile / .profile). Tools run through bash -l inside the container, so standard shell config files are sourced automatically. Default shell config files from /etc/skel are seeded into the container home on first run.

• XDG_DATA_HOME: Override default data directory (default: ~/.local/share)

Usage

From any project directory:

# Run OpenCode
opencode

# Run Claude Code
claude

# Run Pi
pi

The image is built automatically on first use if it does not already exist. The tool starts inside the container with the current directory mounted and set as the working directory.

Updating

To rebuild the image with the latest versions of OpenCode, Claude Code, and Pi:

agent-container update

This removes all existing containers and rebuilds the image from scratch. Containers are recreated automatically on the next run. The persistent home directory is not affected.

Purge

To remove all containers, the image, and the persistent home directory:

agent-container purge

Sharing host config files via hard links

The container home at ~/.local/share/agent-container/container-home/ is mounted as /home/<username> inside every container. You can hard link files from your real $HOME into this directory so the container sees them without copying or syncing.

Because both paths live on the same filesystem, a hard link means they are literally the same file -- changes from either side are instantly reflected.

Example for .gitconfig:

mkdir -p ~/.local/share/agent-container/container-home
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.