clawdie-ai/docs/FRESH-INSTALL-CHECKLIST.md

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
Firstboot wizard shown	bsddialog prompt appears	T1 = T1 - T0
Wizard 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

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 (agent name may vary):

 JID             IP Address      Hostname                      Path
 {agent}-cont..  10.0.X.2        {agent}-controlplane          /usr/local/bastille/jails/...
 db              10.0.X.3        db                            /usr/local/bastille/jails/...
 cms             10.0.X.4        cms                           /usr/local/bastille/jails/...
 llamacpp        10.0.X.5        llamacpp                      /usr/local/bastille/jails/...

All four jails must be present and running. If any are missing:

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

2. .env correctness

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

# From host — test PostgreSQL in db jail
sudo bastille cmd db service postgresql status

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

Expected: postgresql is running and verify step exits 0.

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	logs/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 npm run preflight

# With onboarding wizard
sudo npm run preflight -- --with-onboarding

# Stop on first failure
sudo npm run preflight -- --fail-fast

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