# 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](claudaris.md) 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):

```bash
./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

```bash
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

```bash
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](mcp.md): 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.