107 lines
3.8 KiB
Markdown
107 lines
3.8 KiB
Markdown
> **This repository has been archived.** It has been superseded by
|
||
> [agent-container](https://git.jeena.net/jeena/agent-container), which
|
||
> combines multiple coding agents (OpenCode, Claude Code, etc.) into a
|
||
> single container setup. Please use that repository instead.
|
||
|
||
---
|
||
|
||
# claude-container
|
||
|
||
Run Claude Code inside an 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
|
||
- 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 to persist across projects
|
||
- **Sudo access**: Claude agent 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)
|
||
- **Easy updates**: `claude update` rebuilds the image with the latest Claude Code
|
||
- Simple shell function (`claude`) to launch interactively
|
||
|
||
## Install
|
||
|
||
Change to your projects directory and clone the repository:
|
||
|
||
```
|
||
cd ~/Projects/
|
||
git clone https://git.jeena.net/jeena/claude-container.git
|
||
```
|
||
|
||
Source the helper file `claude.aliases` in your shell configuration
|
||
(`.bashrc` or `.zshrc`) so the `claude` function is available in new sessions.
|
||
|
||
```sh
|
||
source ~/Projects/claude-container/claude.aliases
|
||
```
|
||
|
||
We set up the `XDG_DATA_HOME/claude-container/container-home` directory as a central `$HOME` inside
|
||
the container, independent of the session or project directory we start in. This
|
||
persists the whole `$HOME` from inside the container so everything Claude Code
|
||
writes into config files etc. persists there.
|
||
|
||
## Environment Variables
|
||
|
||
- `XDG_DATA_HOME`: Override default data directory (default: `~/.local/share`)
|
||
- `ANTHROPIC_API_KEY`: Your Anthropic API key (required, read from host environment)
|
||
- `ANTHROPIC_BASE_URL`: Override the API base URL (optional)
|
||
|
||
## Usage
|
||
|
||
From any project directory:
|
||
|
||
```
|
||
claude
|
||
```
|
||
|
||
The image is built automatically on first use if it does not already exist.
|
||
Claude Code starts inside the container with the current directory mounted and
|
||
set as the working directory.
|
||
|
||
### Updating Claude Code
|
||
|
||
To update Claude Code to the latest version:
|
||
|
||
```
|
||
claude update
|
||
```
|
||
|
||
This rebuilds the Docker image with the latest Claude Code binary and removes
|
||
all existing containers. Containers are recreated automatically on the next
|
||
run. The persistent home directory is not affected.
|
||
|
||
The in-container auto-updater is disabled because Claude Code is installed in
|
||
the image layer. Use `claude update` to get new versions.
|
||
|
||
## Sharing host config files via hard links
|
||
|
||
The container home at `~/.local/share/claude-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`:
|
||
|
||
```sh
|
||
mkdir -p ~/.local/share/claude-container/container-home
|
||
ln ~/.gitconfig ~/.local/share/claude-container/container-home/.gitconfig
|
||
```
|
||
|
||
You can do the same for other config files you want to share. Avoid linking
|
||
sensitive files such as `~/.ssh/id_*` or `~/.gnupg/` — keeping those out of the
|
||
container is an intentional security boundary.
|
||
|
||
## Cleanup
|
||
|
||
To remove all containers, the image, and the persistent home directory:
|
||
|
||
```
|
||
~/Projects/claude-container/force-cleanup.sh
|
||
```
|