claudaris

Claudaris (klaw-DAR-iss): A moveable docker container for Claude code. using Arch btw.

Full documentation lives in docs/: getting started, the claudaris executable, and MCP servers.

Configure

Run the interactive wizard and answer its prompts (press enter to keep a default):

./claudaris config

It writes NAME, DATA_DIR, and WORKSPACE_DIR to .env (gitignored — every user keeps their own), which every other command sources. NAME should be something unique to you (e.g. claude-ten) if more than one person is running a container from this same repo checkout. DATA_DIR defaults to /data/$NAME; WORKSPACE_DIR (the host dir mounted as /projects in the container) defaults to /home/$USER/projects. config/configure can be re-run any time to update .env.

Build container

As root run build (always --no-cache --pull, so it picks up the latest Claude Code release):

sudo ./claudaris build

Start the container

Make sure the volumes are as you like and start the container.

sudo ./claudaris start

Connect to the container

sudo ./claudaris connect

Stop and remove the container

sudo ./claudaris remove

(aliases: stop, rm)

Optional: SSH access to other nodes

To let the container SSH out to other machines, create $DATA_DIR/ssh on the host and populate it with keys/config before running ./claudaris start. If present, it's bind-mounted read-only to /root/.ssh. It's off by default.

MCP servers

MCP servers for Gitea, n8n, and InvokeAI are baked into the image and registered with Claude Code (user scope) automatically on container start. To point them at your instances, uncomment and fill in the export lines at the bottom of your host-persisted $DATA_DIR/home/bash_aliases (GITEA_HOST, GITEA_ACCESS_TOKEN, N8N_API_URL, N8N_API_KEY, INVOKEAI_BASE_URL) — if yours was seeded before this feature existed, copy the block from files/bash_aliases. Tokens stay on the host, out of the image and repo. Note the services run elsewhere (not in this container), so use URLs reachable from inside it — 127.0.0.1 here means the container itself.

Notes

Claude Code is installed at build time under /root, so a rebuild always picks up the latest release. Two files are bind-mounted individually to survive that: ~/.claude/.credentials.json (the OAuth token) and ~/.claude.json (account/onboarding state — Claude Code checks this too, so persisting the token alone isn't enough to avoid a re-login prompt after a rebuild). ./claudaris start seeds both from empty on the host the first time it runs. Logging in once then survives rebuilds without carrying the CLI binary or the rest of ~/.claude (settings, history, projects, caches) along with it.

The container also stops itself once its tmux session ends (any shell exit — Ctrl+D, exit, crash) instead of running forever, and there's no Docker restart policy — ./claudaris connect and ./claudaris start both bring it back up automatically if you find it stopped.

.bashrc and bash_aliases are both bind-mounted as single files so they can be tweaked per-host (e.g. a coworker importing their own aliases) without a rebuild. ./claudaris start seeds them into $DATA_DIR/home/.bashrc and $DATA_DIR/home/bash_aliases from files/bashrc and files/bash_aliases the first time it runs, without overwriting later edits. Anything that needs to survive regardless (PATH, zoxide, git identity) lives in /etc/... inside the image instead of under /root.

The container is started with --hostname "$NAME", so the prompt reads root@claudaris (or whatever you set NAME to via ./claudaris config) instead of a random container ID.