Fabric Runbook

Operational checks and recovery paths.

Sanity checks

# Check service health
fabric start &
curl -s http://localhost:3000/healthz

# Verify config exists
cat ~/.optimalos/config.json

# Check agent service (Linux)
systemctl --user status optimalos-agent

Common commands

Command	Description
fabric init	Create default config at ~/.optimalos/
fabric start	Start the server (default)
fabric pair <token>	Pair this device with a cloud controller
fabric hooks install	Install Claude Code hooks → fabric-agent
fabric hooks status	Check hook status
fabric hooks uninstall	Remove installed hooks
fabric --help	Show all available commands

Agent daemon setup

The fabric-agent daemon runs as a user-mode systemd service on Linux:

# Install agent service
bash scripts/install-agent.sh install

# Check status
systemctl --user status optimalos-agent

# View logs
journalctl --user -u optimalos-agent -f

Pairing devices

1. Mint a pairing token from the cloud controller (if using cloud mode)
2. On the device to pair: fabric pair <token>
3. Verify pairing: check ~/.config/optimalos/device.jwt exists

Troubleshooting

Agent won't start

# Check if paired
ls -la ~/.config/optimalos/device.jwt

# Check journal
journalctl --user -u optimalos-agent

# Restart
systemctl --user restart optimalos-agent

Hooks not working

# Check hook status
fabric hooks status

# Reinstall
fabric hooks uninstall
fabric hooks install

Port conflicts

# Check what's on 3000
lsof -i :3000

# Start on different port
fabric start -p 3001

Files and paths

Path	Purpose
~/.optimalos/config.json	Main configuration
~/.optimalos/sessions.json	Agent session persistence
~/.config/optimalos/	Device identity (keys, JWT)
~/.config/systemd/user/optimalos-agent.service	Agent systemd unit

Source

• Repository: ~/optimal/fabric (or your local checkout)
• Main entry: bin/cli.ts
• Agent service: bin/fabric-agent.ts