claudaris/AGENTS.md

AGENTS.md

Purpose

Docker scaffold for running Claude Code in an isolated container (see README.md).

Structure

• .env — gitignored, per-user, written by claudaris config. Holds NAME (image/container name — the default claudaris is meant to be overridden per person, e.g. chris-claude, so multiple users can each run their own container off this same repo), DATA_DIR, and WORKSPACE_DIR. claudaris sources it if present.
• Dockerfile — archlinux base image with bash, git, nodejs/npm, tmux, vim, fastfetch, etc. files/bash_aliases is baked in at /opt/dotfiles/bash_aliases and files/bashrc becomes the image's default /root/.bashrc — both are rebuild-time defaults, but the host shadows both with its own single-file bind mounts at runtime (see claudaris start below). Claude Code is installed at build time straight into /root ($HOME), so a rebuild always picks up the latest release. Staying logged in across rebuilds is handled entirely by claudaris start, which bind-mounts two individual host files onto ~/.claude/.credentials.json (the OAuth token) and ~/.claude.json (account/onboarding state) — see claudaris start below for why these are per-file mounts rather than a directory volume. Three MCP servers for Claude Code are also installed at build time: n8n-mcp (npm, /usr/local/bin/n8n-mcp), the official gitea-mcp (latest release binary, /usr/local/bin/gitea-mcp), and invokeai-mcp-server (PyPI via uv tool install; upstream hardcodes the InvokeAI URL, so the Dockerfile sed-patches it to honor $INVOKEAI_BASE_URL, with a grep that fails the build if upstream changes and the patch stops landing). They're only installed by the Dockerfile — registration happens in files/entrypoint.sh on every container start (claude mcp add --scope user, skipped per-server if already present), because user-scope MCP config lives in ~/.claude.json, which is bind-mounted from the host and would shadow anything registered at build time. Consequence of the "add if missing" guard: hand edits to a server's config survive restarts, but a server removed with claude mcp remove is re-added on the next container start. The servers read their instance URLs/tokens (GITEA_HOST, GITEA_ACCESS_TOKEN, N8N_API_URL, N8N_API_KEY, INVOKEAI_BASE_URL) from the environment Claude Code runs in — commented export templates live in files/bash_aliases, which is host-persisted, so tokens stay out of the image and the repo. git config --system --add safe.directory '*' is set so git works on /projects repos bind-mounted from the host (which the container, always running as root, would otherwise treat as untrusted). files/entrypoint.sh starts the tmux server and creates a main session, then polls and exits once the session ends (tmux's defaults apply: remain-on-exit off, exit-empty on, so a shell exiting — Ctrl+D, exit, crash — tears the session down) rather than running forever; there's no --restart policy, so a stopped container needs claudaris connect or claudaris start to bring it back up (both do this automatically). /etc/profile.d/nix_path.sh points PATH at /root/.local/bin. files/tmux is copied in as a /usr/local/bin/tmux wrapper that shadows the real tmux binary so that plain docker exec -it "$NAME" tmux runs tmux new-session -A -s main (attaches to main if it exists, creates it otherwise) instead of always starting a new session.
• claudaris — single entry point with subcommands:
  • config (alias configure) — interactive wizard prompting for NAME, DATA_DIR, WORKSPACE_DIR (showing current/default values, enter to keep) and writing them to .env. Re-run any time to update it.
  • build — builds the image, tagged $NAME (see .env above).
  • start — runs the container as $NAME with --hostname "$NAME" (so the shell prompt reads root@$NAME, e.g. root@claudaris, instead of a random container ID). /root/.bashrc, /opt/dotfiles/bash_aliases, and the two auth files (~/.claude/.credentials.json, ~/.claude.json) are each bind-mounted individually — seeded once (empty, for the auth files; from files/bashrc/files/bash_aliases, for the dotfiles) into $DATA_DIR/home/{.bashrc,bash_aliases} and $DATA_DIR/claude/{credentials,claude}.json on the host, so they can be edited/persist without a rebuild — including a coworker dropping in their own aliases. Individual-file mounts matter for the auth files specifically: Claude Code likely saves them atomically (write a temp file, then rename() over the target), and rename() onto a symlink replaces the symlink instead of writing through it — silently breaking persistence after the first write. A bind mount doesn't have that failure mode, which is why these aren't just symlinked from a directory volume the way an earlier version of this setup did it. $WORKSPACE_DIR is mounted at /projects. Also offers an opt-in /root/.ssh mount (read-only) for reaching other nodes: create $DATA_DIR/ssh on the host and populate it before starting the container to enable it. DATA_DIR defaults to /data/$NAME; WORKSPACE_DIR defaults to /home/$USER/projects (override via claudaris config).
  • connect — docker starts $NAME (a no-op if it's already running) then attaches to its tmux session, so it also works right after the container has auto-exited (see Dockerfile/entrypoint above).
  • remove (aliases stop, rm) — stops and removes the container so a subsequent start recreates it fresh.
  • help — usage.
• files/ — plain (non-dot) source files COPY'd into the image at build time: bashrc/bash_aliases (dotfiles — see Dockerfile above), entrypoint.sh, and the tmux wrapper. Kept dotless so they're easy to see/edit directly in a normal directory listing; the Dockerfile adds the leading dot back on for bashrc's destination. Both bashrc and bash_aliases are also seeded onto the host by claudaris start so their bind-mounted copies can diverge without a rebuild.
• README.md — usage instructions.
• docs/ — user documentation in markdown: README.md (index), getting-started.md (setup and daily use), claudaris.md (the executable, subcommand by subcommand, including the mount table), mcp.md (the baked-in MCP servers and their env vars). Keep these in sync when changing the script, Dockerfile, or entrypoint.

Common commands

# build the image
docker build -t "$NAME" .

# start the container
docker run -d \
  --name "$NAME" \
  --hostname "$NAME" \
  -v "$DATA_DIR/home/.bashrc:/root/.bashrc" \
  -v "$DATA_DIR/home/bash_aliases:/opt/dotfiles/bash_aliases" \
  -v "$DATA_DIR/claude/credentials.json:/root/.claude/.credentials.json" \
  -v "$DATA_DIR/claude/claude.json:/root/.claude.json" \
  -v "$WORKSPACE_DIR:/projects" \
  "$NAME"

# attach to the running container's tmux session
docker exec -it "$NAME" tmux

Notes

No test suite or CI — this is infra/config, not application code. Verify changes by rebuilding the image (./claudaris build) and exec'ing in (./claudaris connect) to confirm the container behaves as expected.