agent-container/README.md

agent-container

Run OpenCode and Claude Code 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 both OpenCode and Claude Code 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
• Unified home: Both tools share the same $HOME, enabling plugins like opencode-claude-bridge that need access to both tools' config
• 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
• 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, 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

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

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 both OpenCode and Claude Code:

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.

Optional: Use Claude Pro/Max with OpenCode

The opencode-claude-bridge plugin lets OpenCode use your Claude Pro/Max subscription via the Claude CLI's OAuth credentials. Because both tools share the same $HOME inside the container, the bridge can read Claude's credentials directly.

1. Run Claude Code inside the container and log in to your Max account:

   claude
   

   Complete the login flow. This creates the credentials file at ~/.claude/.credentials.json inside the container home.

2. Create the OpenCode config to enable the plugin:

   mkdir -p ~/.local/share/agent-container/container-home/.config/opencode
   cat > ~/.local/share/agent-container/container-home/.config/opencode/opencode.json << 'EOF'
   {
     "plugin": ["opencode-claude-bridge"]
   }
   EOF
   

3. Start OpenCode:

   opencode
   

   Press Ctrl-p, select Switch Model, and Anthropic will appear as a provider.