90 lines
3.0 KiB
Markdown
90 lines
3.0 KiB
Markdown
# 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 `/`.
|