claudaris/docs/getting-started.md

Getting started

Claudaris runs Claude Code inside an Arch Linux container, with your project workspace bind-mounted in and your login persisted on the host. Everything is driven by the ./claudaris executable at the repo root.

Prerequisites

• Docker installed and running on the host.
• Root (or equivalent Docker) access — the examples below use sudo.
• A Claude account to log in with on first run.

1. Configure

From the repo root, run the interactive wizard and answer its prompts (press enter to keep a default):

./claudaris config

It asks for three values and writes them to .env (gitignored — every user of a shared checkout keeps their own):

Variable	Default	Meaning
NAME	claudaris	Image and container name. Pick something unique to you (e.g. chris-claude) if several people run containers from the same repo checkout.
DATA_DIR	/data/$NAME	Host directory for everything that must survive rebuilds: dotfiles, Claude login, optional SSH keys.
WORKSPACE_DIR	/home/$USER/projects	Host directory mounted as /projects inside the container — this is where Claude Code works.

Re-run config any time to change these.

2. Build the image

sudo ./claudaris build

The build always runs with --no-cache --pull, so every rebuild picks up the latest Arch packages and the latest Claude Code release. Claude Code is installed into the image itself (not a volume) — rebuilding is how you upgrade it.

3. Start and connect

sudo ./claudaris start
sudo ./claudaris connect

start creates the container (seeding host-side copies of the dotfiles and login files on first run); connect attaches you to its tmux session. You land in a shell at /projects as root@$NAME.

On first connect, run claude and log in. The two files that carry the login (~/.claude/.credentials.json and ~/.claude.json) are bind-mounted from $DATA_DIR/claude/ on the host, so you stay logged in across container rebuilds and re-creations.

4. Daily use

• Attach: sudo ./claudaris connect — also restarts the container if it stopped. The container exits on its own when the tmux session ends (last shell exits via Ctrl+D, exit, or a crash); there is no Docker restart policy, so connect bringing it back up is the normal flow.
• Detach without stopping anything: standard tmux detach (Ctrl+b d).
• Upgrade Claude Code / packages: sudo ./claudaris remove, then sudo ./claudaris build and sudo ./claudaris start. Login, dotfiles, and MCP registration all survive this.

Customizing your shell

~/.bashrc and the aliases file are bind-mounted single files living at $DATA_DIR/home/.bashrc and $DATA_DIR/home/bash_aliases on the host. Edit them there (or inside the container) and the changes persist across rebuilds — no image change needed. They're seeded from files/bashrc and files/bash_aliases the first time start runs and never overwritten after that.

This is also where you configure the MCP servers: the bottom of bash_aliases has commented export lines for the Gitea/n8n/InvokeAI URLs and tokens.

Optional: SSH access to other machines

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