clawdie-ai/docs/INSTALL.md

Install Orchestrator

File: setup/install.ts Script: npm run install-all Status: current main — replaces manual step-by-step sequence

---

Quick start

npm run install-all

Resume from a specific step after a failure:

npm run install-all -- --from db

Print the step plan without running anything:

npm run install-all -- --dry-run

Skip ZFS checkpoints (e.g. no ZFS pool):

npm run install-all -- --no-snapshots

---

Step flow

npm run install-all
        │
        ▼
  ┌─────────────────────────────────────────────────────────┐
  │  Detect ZFS dataset (zroot/bastille)                    │
  │  Parse --from / --no-snapshots / --dry-run              │
  └─────────────────────────────────────────────────────────┘
        │
        ▼
 [ 1] onboarding        bsdinstall-style TUI wizard         REQUIRED
        │
 [ 2] environment       host pkg baseline, bridge, locale   REQUIRED
        │
 [ 3] pi-config         detect/write LLM provider to .env   optional ─── no pi binary → STOP
        │                                                        └── no API key → warn, continue
 [ 4] pf                write pf.conf, NAT + rdr rules      REQUIRED
        │                         └── 📸 snapshot: post-pf
 [ 5] jails             create worker jail (--create)        REQUIRED
        │                         └── 📸 snapshot: post-jails
 [ 6] db                PostgreSQL jail + memory schema      REQUIRED
        │                         └── 📸 snapshot: post-db
 [ 7] skills-memory     import artifacts/skills.db           optional ─── file absent → skip
        │
 [ 8] git               git jail                             REQUIRED
        │                         └── 📸 snapshot: post-git
 [ 9] cms               Strapi CMS jail + seed               REQUIRED
        │                         └── 📸 snapshot: post-cms
 [10] browser-vm        bhyve GUI VM                         optional ─── FEATURE_BHYVE_GUI≠YES → skip
        │
 [11] hosts             /etc/hosts + jail hostnames          REQUIRED
        │
 [12] mounts            validate jail mounts                 REQUIRED
        │
 [13] telegram-auth     verify bot token                     optional ─── TELEGRAM_BOT_TOKEN unset → skip
        │
 [14] service           write + enable rc.d script           REQUIRED
        │
 [15] hostd             root daemon on clawdie-hostd.sock    REQUIRED
        │
 [16] verify            integrity check, skills freshness    optional
        │                         └── 📸 snapshot: install-complete
        │
        ▼
  ┌─────────────────────────────────────────────────────────┐
  │  Summary: N ok  N warnings  N skipped  N failed         │
  │  Snapshots taken: zroot/bastille@post-pf-…  …          │
  │  LLM providers: anthropic ✓  openai ✗  ollama ✗  …     │
  └─────────────────────────────────────────────────────────┘

---

ZFS snapshots

Snapshots are taken after each milestone step if a Bastille ZFS dataset is detected. Two paths:

Context	Method
Running as root	zfs snapshot zroot/bastille@<tag> directly
Non-root, hostd socket present	nc -U /var/run/clawdie-hostd.sock (hostd zfs-snapshot op)
Neither	skip silently

Snapshot tags are suffixed with a Unix timestamp to prevent collisions on re-runs.

---

LLM providers

The orchestrator never exits on a missing LLM key. At the end of the run it prints a table of all known providers:

△ LLM providers
  anthropic     ANTHROPIC_API_KEY         ✓ configured
  openai        OPENAI_API_KEY            ✗ not set
  openrouter    OPENROUTER_API_KEY        ✗ not set
  groq          GROQ_API_KEY              ✗ not set
  deepseek      DEEPSEEK_API_KEY          ✗ not set
  azure         AZURE_OPENAI_API_KEY      ✗ not set
  ollama        OLLAMA_HOST               ✗ not set

If no key is found, it prints instructions:

  No LLM keys found. Add to .env and restart:
    ANTHROPIC_API_KEY=sk-ant-...
    sudo service clawdie restart

The entire infrastructure (PF, jails, PostgreSQL, nginx, ZFS) has zero LLM dependency. The key is only consumed when the jail-runner spawns a live response. Install and service start succeed without it.

---

Required vs optional steps

Step	Required	Skip condition
onboarding	yes	—
environment	yes	—
pi-config	no	warn on missing key; exit only if pi binary absent
pf	yes	—
jails	yes	—
db	yes	—
skills-memory	no	artifacts/skills.db not present
git	yes	—
cms	yes	—
browser-vm	no	FEATURE_BHYVE_GUI ≠ YES
hosts	yes	—
mounts	yes	—
telegram-auth	no	TELEGRAM_BOT_TOKEN not set
service	yes	—
hostd	yes	—
verify	no	warn on any check failure

A required step failure stops the install immediately and prints the resume command.

Optional step prerequisites

browser-vm requires UEFI firmware for bhyve:

pkg install edk2-bhyve

This is included in the recommended host baseline in README.md. Without edk2-bhyve, the browser-vm step will skip silently.

---

Individual steps

The orchestrator calls each step through setup/index.ts as a subprocess (spawnSync with tsx). This isolates process.exit(1) calls in individual step modules from killing the orchestrator.

Individual steps can still be run directly:

npm run setup -- --step db
npm run setup -- --step verify

See setup/index.ts for the full step registry.