134 lines
5.3 KiB
Markdown
134 lines
5.3 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).
|
|
- `test.sh`: end-to-end tests, run on the host (`./test.sh`, or `./test.sh --update`
|
|
to also test the slow `claudio update`).
|
|
|
|
## 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
|
|
claudio reset # remove this project's persistent container (PERSIST=1)
|
|
```
|
|
|
|
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
|
|
ROOT=1
|
|
PERSIST=1
|
|
PACKAGES=(python3 nodejs)
|
|
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).
|
|
- `ROOT=1`: passwordless `sudo` inside the container (see below).
|
|
- `PERSIST=1`: keep the container, and system changes, between runs (see below).
|
|
- `PACKAGES`: extra Debian packages for this project (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.
|
|
|
|
## Root access
|
|
|
|
`ROOT=1` lets Claude (and you, in `claudio shell`) run `sudo` without a
|
|
password, for example to `apt-get install` a missing tool. It is off by default:
|
|
the image grants passwordless sudo to the `sudo` group, and claudio only adds
|
|
you to that group when `ROOT=1`.
|
|
|
|
- System changes last only as long as the container, which is removed after
|
|
every run unless `PERSIST=1` (see below).
|
|
- With rootless podman, root in the container is still your unprivileged host
|
|
user, so it gets no access to the host beyond what is already mounted. With
|
|
rootful podman it is real root (limited by the container's capabilities).
|
|
|
|
## Keeping system changes
|
|
|
|
There are two ways, and they combine well:
|
|
|
|
- `PACKAGES=(python3 nodejs)` builds a per-project image with those packages
|
|
on top of the base image (`localhost/claudio:pkgs-<hash>`). It is rebuilt
|
|
automatically when the list changes or after `claudio update`, so this is
|
|
the place for anything the project always needs. Projects with the same list
|
|
share the image.
|
|
- `PERSIST=1` keeps one container per project instead of a fresh one each run,
|
|
so anything done with `sudo` (or written outside the mounts) is still there
|
|
next time. All `claudio` and `claudio shell` sessions in the project share
|
|
it, and it is stopped when the last one exits. It is **recreated, losing
|
|
those changes**, when the image changes (`claudio update`, a new
|
|
`PACKAGES` list) or when the container's options change (`MOUNTS`, `GUI`,
|
|
`AUDIO`, `ROOT`, `PODMAN_ARGS`); editing `CLAUDE_ARGS` or comments does not. Run `claudio reset`
|
|
to start it over by hand. Background processes do not survive the stop, and
|
|
`-e VAR` values in `PODMAN_ARGS` are read when the container is created.
|
|
|
|
A good habit: let Claude install things ad hoc with `PERSIST=1`, and move the
|
|
ones worth keeping into `PACKAGES`.
|
|
|
|
## 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, unless `PERSIST=1`.
|
|
|
|
- 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 `/`.
|