colibri/docs/guide/install/install.md

title	description
Install	Provision the Clawdie host service with the clawdie binary.

Command: clawdie apply --yes

Colibri-based Clawdie is installed by the clawdie binary (crate crates/clawdie). It discovers the host's ZFS layout and provisions the clawdie service: storage datasets, a service user, and the rc.d (FreeBSD) or systemd (Linux) unit that runs colibri-daemon.

This repo is a Cargo workspace — there is no just/npm install flow here. Build the installer from the workspace:

cargo build -p clawdie --release

Commands

clawdie discover            # read-only: OS, ZFS pools, datasets, spare disks
clawdie plan [--pool NAME]  # show the deploy plan (dry-run, no writes)
clawdie apply [--pool NAME] # dry-run unless --yes is given
clawdie apply --yes         # provision: storage layout + install the service

apply is a dry-run by default and prints the full step plan; it writes to disk only with --yes. When the host has exactly one ZFS pool it is selected automatically; with several, pass --pool NAME.

Storage strategy

Host	Behavior
FreeBSD	ZFS is required; datasets are created under the chosen pool.
Linux + ZFS + pool	Same — datasets under the pool.
Linux, no ZFS/pool	Falls back to plain directories, and reports the ZFS benefits plus any spare disks that could host a pool.

ZFS layout under the pool:

<pool>/clawdie        (container, canmount=off)
<pool>/clawdie/db     -> /var/db/clawdie
<pool>/clawdie/log    -> /var/log/clawdie

What apply --yes provisions

1. Storage — the datasets above (or plain /var/db/clawdie + /var/log/clawdie on the plain-dirs fallback).
2. Service user — clawdie (nologin), owning the state directories (clawdie:clawdie).
3. Service — the rc.d script (FreeBSD, via daemon -u clawdie) or systemd unit (Linux, User=clawdie), installed and enabled to run /usr/local/bin/colibri-daemon.

Creating a pool (destructive)

On a host with a spare disk and no usable pool:

clawdie apply --pool NAME --create-pool /dev/DEV --yes

--create-pool runs zpool create on DEV and destroys all data on it, so it is refused unless the disk is detected as empty (no partitions/filesystem/ mount, not the root disk). Override that guard with --force only if you are certain.

Safety

Disk-touching steps (zfs/zpool create, service install) run as root on the target host. discover, plan, and a bare apply never write — preview with plan first.

Scope

clawdie provisions the host service. Jail, DB, CMS, and Git provisioning are not yet in the installer.

FreeBSD validation

Service wrapper scripts

The rc.d service (/usr/local/etc/rc.d/${AGENT_NAME}) runs run-${AGENT_NAME}.sh which is generated by just setup-service at install time. It is not tracked in git (run-*.sh is in .gitignore). If missing, re-run just setup-service to regenerate it.

Local LLM runtime is optional and configured via:

LOCAL_LLM_PROVIDER=none|ollama|llama_cpp
FEATURE_OLLAMA=YES|NO
FEATURE_LLAMA_CPP=YES|NO
FEATURE_OLLAMA_HPP=YES|NO   # optional C++ bindings for Ollama clients

---

Required vs optional steps

Steps are required (failure stops install), default (runs out of the box but can be disabled), or optional (skipped unless explicitly enabled).

Step	Status	Skip condition
onboarding	required	—
environment	required	—
agent-config	optional	warn on missing provider auth or missing agent binary
pf	required	—
jails	required	—
git	default	DB_RUNTIME=host or install-from hosts
forgejo	default	FEATURE_GITEA = NO
db	default	DB_RUNTIME=host skips jail, provisions on host instead
skills-memory	default	bootstrap/skills-memory/artifact.sql not present
skills-init	default	—
cms	default	install-from hosts skips; cms is a shared service, not per-agent
ollama	optional	FEATURE_OLLAMA ≠ YES
llama-cpp	optional	FEATURE_LLAMA_CPP ≠ YES
hosts	required	—
mounts	required	—
telegram-auth	optional	TELEGRAM_BOT_TOKEN not set
service	required	—
hostd	required	—
identity-restore	optional	SUPABASE_URL not set
verify	optional	warn on most check failures; fail on compromised runtime integrity

A required step failure stops the install immediately and prints the resume command. Default steps ship enabled (FEATURE_GITEA=YES, artifact.sql bundled) — they run unless the operator explicitly opts out.

---

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:

just setup-db
just setup -- --step verify

verify checks more than the shared docs build. If tenant sites are declared, it also checks their served output and publish-manifest consistency in the CMS webroot. A site that is merely declared but not yet manually published does not fail the step by itself; an inconsistent live publish state does.

The step registry is implemented in setup/index.ts.