code
90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# 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.
|