# 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)
- 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.

## 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
```