# claudio

Run Claude Code isolated in a podman container, one command per project.

## Files

- `Containerfile`: the image (Debian slim + Claude Code).
- `claudio.sh`: builds, updates and runs the container.
- `.claudio`: template for per-project settings (plain bash).

## Install

```sh
mkdir -p ~/claudio && cp Containerfile claudio.sh ~/claudio/
chmod +x ~/claudio/claudio.sh
echo 'alias claudio=~/claudio/claudio.sh' >> ~/.bashrc
```

Requires `podman` (rootless is fine).

## Usage

```sh
cd ~/projects/myapp
claudio              # start Claude Code here (builds the image on first run)
claudio --resume     # any extra args are passed to claude
claudio shell        # bash inside the container instead of claude
claudio build        # build the image
claudio update       # rebuild from scratch: latest base image + latest Claude Code
```

The current directory is mounted at the same path inside the container.
Nothing else from the host is visible unless you add it to a `.claudio` file.

## Per-project settings

Copy the template into a project and uncomment what you need:

```sh
cp ~/claudio/.claudio ~/projects/myapp/
```

```bash
GUI=1
AUDIO=1
MOUNTS=("$HOME/.gitconfig:/home/claude/.gitconfig:ro" "/data/shared")
PODMAN_ARGS=(-e GITHUB_TOKEN -p 3000:3000)
CLAUDE_ARGS=(--model opus)
```

- `GUI=1`: graphical apps open on your desktop (see below).
- `AUDIO=1`: apps can play sound (see below).
- `MOUNTS`: extra `-v` mounts. A bare path is mounted at the same path. Add `:ro` for read-only.
- `PODMAN_ARGS`: extra `podman run` options.
- `CLAUDE_ARGS`: default arguments for `claude`.

`.claudio` is sourced as bash, so only use ones you trust.

## Graphical apps and sound

Both are off by default and work by sharing a single socket from your session.

- `GUI=1` shares your Wayland socket and the GPU (`/dev/dri`), and makes
  GTK, Qt, SDL and Electron apps use Wayland. It requires a Wayland session
  (there is no X11 support). How isolated the container is depends on your
  compositor: on KDE Plasma it **can type and click into other apps, record
  the screen, read the clipboard and control all windows**, because KWin
  offers those interfaces to every app.
- `AUDIO=1` shares the PulseAudio socket (`pulse/native`, also provided by
  PipeWire). It works both ways: anything in the container can also **record
  from your microphone**.

The image only ships OpenGL drivers, a font and the PulseAudio client. Add the
apps you want to run (and their libraries) to the `apt-get install` line.

## State

The container's home (`/home/claude`) lives in the podman volume `claudio-home`.
This volume is shared by all projects and holds your login, settings and history.
The container itself is removed after every run.

- Reset everything: `podman volume rm claudio-home`
- Need more tools in the image? Add them to the `apt-get install` line, then run `claudio update`.

## Notes

- Files written in mounts are owned by your host user (`--userns=keep-id`).
- SELinux labeling is disabled for the container, so mounts work without relabeling.
- claudio refuses to run from `$HOME` or `/`.