---
name: sanoid
description: Manage policy-driven ZFS snapshots for Warden datasets on FreeBSD using Sanoid. Use when defining snapshot retention for clawdie-runtime, creating a sane control-plane snapshot policy, or validating automated rollback safety for Bastille datasets and future VM images.
---

# Sanoid

Use this skill for automated ZFS snapshot policy on the FreeBSD host.

## Scope

This skill covers:

- Sanoid policy selection
- `sanoid.conf` rendering
- snapshot retention for `clawdie-runtime`
- control-plane rollback safety
- future VM dataset snapshot policy
- role-aware rollback policy selection

This skill does not replace:

- `warden-zfs` for base dataset layout
- `warden-bootstrap` for jail creation
- `bastille-network` or `warden-pf` for host networking

## Canonical targets

- control-plane jail dataset:
  - `zroot/clawdie-runtime/jails/controlplane`
- future browser VM dataset family:
  - same host, separate image-backed datasets later

## Install baseline

- install on the FreeBSD host with `pkg install -y sanoid`
- primary config path: `/usr/local/etc/sanoid/sanoid.conf`
- sample config path: `/usr/local/etc/sanoid/sanoid.conf.sample`
- `sanoid --version` should work after installation

## Recommended baseline policy

- start with explicit policy classes by runtime role
- snapshot `controlplane` and `db` differently
- keep retention conservative until the runtime is proven
- do not apply normal Sanoid retention to disposable runners
- expand to VM datasets later by role, not by guesswork

## Workflow

1. Read `references/policy-model.md`
2. Read `references/example-config.md`
3. If troubleshooting is needed, read `references/troubleshooting.md`
4. Prefer the scripts in `scripts/` to render a starter `sanoid.conf`


## Observed FreeBSD quirk

- The shipped sample config can emit one benign placeholder warning on the first `sanoid --readonly --verbose` run because it still contains sample dataset names like `zpoolname/parent2`.
- That does not indicate a failure in the Clawdie policy block.
