Fresh Install Checklist

Verification checklist for new Clawdie-AI installations (bare metal, bhyve VM, or jail-based). Run after firstboot completes. Each check includes the exact command and expected result.

Designed to work with the tmux-screenshot skill — capture each section for the installation record.

Timing milestones

Record wall-clock timestamps at each stage. On bhyve, the serial console shows boot messages with timestamps.

Milestone	Command / event	Record
Boot start	First kernel message	T0
first-boot setup consumed	[firstboot] seed loaded in log	T1 = T1 - T0
Firstboot complete	[firstboot] Complete. in log	T2 = T2 - T0
Desktop ready (Lumina)	lightdm login screen visible	T3 = T3 - T0
Agent responding	/ping on Telegram returns pong	T4 = T4 - T0

If the first-boot setup (setup.txt) was absent or invalid, the install falls back to the interactive TUI wizard at the equivalent of T1 — record the same milestone but note “TUI fallback” in the install record.

Check firstboot log for exact timestamps:

head -5 /var/log/${AGENT_NAME}-firstboot.log
tail -5 /var/log/${AGENT_NAME}-firstboot.log

1. Jails running

sudo bastille list

Expected jails depend on configuration:

Jail	When present
{agent}-controlplane	When agent runs inside a controlplane jail
git (shared, 10.0.0.2)	Shared across agents — one per host
cms (shared, 10.0.0.3)	Shared across agents — one per host
ollama / llama-cpp (10.0.0.4)	When Local AI Models are enabled
db (10.0.0.5)	Only when DB_RUNTIME=jail
{agent}_db_worker	Phase 7 isolation enabled
{agent}_git_worker	Phase 7 isolation enabled
{agent}_ctrl_worker	Phase 7 isolation enabled

With DB_RUNTIME=host there is no db jail — PostgreSQL runs on the host and jails connect via warden0 (10.0.N.1:5432).

If expected jails are missing:

grep -i 'fail\|error' /var/log/${AGENT_NAME}-firstboot.log

2. .env correctness

Before editing .env inside a bhyve guest, confirm you are in the guest filesystem and on the expected user/home path:

hostname
ifconfig | head -n 5
whoami
echo "$HOME"
pwd
ls -la /home

If the agent name is mevy, expect the repo at:

ls -la /home/mevy/clawdie-ai/.env

grep -E '^(AGENT_NAME|AGENT_GENDER|AGENT_DOMAIN|AGENT_INTERNAL_DOMAIN|AGENT_TMP_DIR|PI_TUI_PROVIDER|PI_TUI_MODEL|EMBED_BASE_URL|TELEGRAM_BOT_TOKEN)=' .env

Verify:

Key	Expected
AGENT_NAME	Lowercase, no spaces (e.g. clawdie, mevy)
AGENT_GENDER	f, m, or n
AGENT_DOMAIN	Public domain (e.g. clawdie.si) or {agent}.internal for VMs
AGENT_INTERNAL_DOMAIN	{agent}.home.arpa (Tailscale / local DNS)
AGENT_TMP_DIR	Writable path, not /tmp
PI_TUI_PROVIDER	zai, openrouter, anthropic, etc.
PI_TUI_MODEL	Valid model for the provider
EMBED_BASE_URL	URL ending in /v1
TELEGRAM_BOT_TOKEN	Non-empty if FEATURE_TELEGRAM=true

3. Watchdog IPC status

# Check socket exists
ls -la "${AGENT_TMP_DIR:-tmp}/ipc/"

# Query watchdog status
echo '{"cmd":"status"}' | nc -U "${AGENT_TMP_DIR:-tmp}/ipc/${AGENT_NAME}-watchdog.sock"

Expected: JSON response with mode, throttle, memory, activeJails.

If socket is missing, check if the agent process is running:

sudo bastille cmd "${AGENT_NAME}-controlplane" service clawdie status

4. Database connectivity

# DB_RUNTIME=host: PostgreSQL runs on the host
service postgresql status

# DB_RUNTIME=jail: PostgreSQL runs in the db jail
sudo bastille cmd db service postgresql status

# Test connection (uses .env credentials)
just setup -- --step verify

Expected: postgresql is running and verify step exits 0.

If tenant sites are already declared, verify may report publish state such as planned_only, partial, or available. Those are acceptable during the current manual publish phase. inconsistent is the state that needs operator attention before you treat publishing as healthy.

5. LLM provider connectivity

# Quick inference test via pi
pi --provider "${PI_TUI_PROVIDER}" --model "${PI_TUI_MODEL}" -e "reply with OK"

Expected: Model responds. If using ZAI (GLM), verify the API key:

grep '^ZAI_API_KEY=' .env | cut -c1-20

6. Telegram bot

# Check bot token is valid (should return bot info)
curl -s "https://api.telegram.org/bot$(grep '^TELEGRAM_BOT_TOKEN=' .env | cut -d= -f2)/getMe" | python3 -m json.tool

Expected: "ok": true with the bot username.

7. Lumina desktop (baremetal only)

service lightdm status
service dbus status

If Lumina fails to start, check:

# X11 log
tail -30 /var/log/Xorg.0.log

# LightDM log
tail -30 /var/log/lightdm/lightdm.log

# GPU driver loaded?
pciconf -lv | grep -B3 'VGA'

8. Network and firewall

# PF rules loaded
sudo pfctl -sr | head -10

# NAT working (from inside the db jail)
sudo bastille cmd db ping -c 1 1.1.1.1

# Bridge healthy
ifconfig warden0 | grep 'inet '

9. ZFS health

zpool status -x
zfs list -o name,used,avail -t filesystem | head -20

Expected: all pools are healthy.

10. Screenshot smoke test

Capture the final state as proof of successful install:

python3 .agent/skills/tmux-screenshot/tmux-screenshot.py \
  --session "${AGENT_NAME}" \
  --base-url "https://${AGENT_DOMAIN}/screenshots" \
  --publish

Verify the capture landed:

ls -la /usr/local/www/${AGENT_NAME}/screenshots/*.png | tail -3

Log paths reference

Log	Path
Firstboot orchestrator	/var/log/${AGENT_NAME}-firstboot.log
Firstboot progress	/var/log/${AGENT_NAME}-firstboot.progress
Agent (production)	logs/${AGENT_NAME}.log (relative to project)
Watchdog	Same as agent log (pino structured)
Preflight run	tmp/preflight/{runstamp}/
LightDM	/var/log/lightdm/lightdm.log
X11	/var/log/Xorg.0.log
PostgreSQL	/var/log/postgresql.log (inside db jail)
nginx	/var/log/nginx/error.log

Running the full preflight

The automated version of this checklist:

# As root (for jail and firewall steps)
sudo just preflight

# With onboarding wizard
sudo just preflight -- --with-onboarding

# Stop on first failure
sudo just preflight -- --fail-fast

Results are written to tmp/preflight/{timestamp}/summary.json.