added gitea, n8n and invokeai MCP servers, plus docs/

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-14 20:47:29 +00:00
parent 06fcf6bab7
commit bcd7e012ba
9 changed files with 375 additions and 1 deletions
@@ -0,0 +1,89 @@
+# 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.