---
title: Install
description: 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:

```bash
cargo build -p clawdie --release
```

## Commands

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

```text
<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:

```bash
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: what the installer does _not_ do (yet)

`clawdie` provisions the **host service** only. The wider service mesh — PF
egress, worker jails, PostgreSQL, Forgejo/Git, and the CMS/web service — is
**not yet part of the colibri installer**. Pages that reference `just install`,
`just setup-db`, `just doctor`, and similar describe a previous orchestrator;
they are being reconciled to the `clawdie` model.

## FreeBSD validation

The disk-touching and service-install paths are validated on real FreeBSD/Linux
hosts; discovery, plan, and disk-candidacy logic are unit-tested. See
`docs/CLAWDIE-INSTALLER-VALIDATION.md` for the FreeBSD validation runbook.