🔧 Fleet Resurrection Plan
Step-by-step recovery playbook for bringing dead or stale agents back online · Last updated: 2026-03-21
✅
Fleet nominally healthy No active resurrection needed. This page documents the recovery procedure for future incidents.
Alive Agents
—
Sending pulse
Slow Agents
—
Elevated latency
Dead Agents
—
No recent pulse
Total Bonded
—
Registered fleet
🔄 Resurrection Steps

Follow these steps in order when agents.alive === 0 or the fleet is significantly degraded. Check off each step as completed.

1
Verify spaceduck.bot process is running

Check that the spaceduck.bot process is live on its host. Confirm the process hasn't crashed or been OOM-killed. Look for the process in the host task manager or service logs.

ps aux | grep spaceduck
# or
systemctl status spaceduck-bot
📖 Ops Runbook
2
Check beak key validity and TTL

The agent's beak key may have expired. If the key has expired, the agent cannot authenticate to the backend and will appear dead even if the process is running.

GET /beak/keys/{agent_id}
# or check beak-key-manager.html for key expiry dates
Key Beak Key Manager
3
Rotate / renew the beak key if expired

If the key has expired, rotate it via the Beak Key Manager. Copy the new key to the agent's environment. The agent will pick it up on restart.

POST /beak/keys/rotate
Body: { "agent_id": "..." }
Key Rotate Key 🚨 If Compromised
4
Re-register the agent

If the agent is not appearing in the fleet after key rotation, re-register it via the Agent Registration page. This resets the agent's bond and issues a fresh pulse schedule.

POST /beak/agents/register
Body: { "agent_id": "...", "beak_key": "...", "capabilities": [...] }
Space Duck Register Agent
5
Restart agent and await first pulse

Restart the spaceduck.bot process with the new key. After registration, wait up to 60 seconds for the agent to emit its first pulse. Mission Control auto-refreshes every 30s.

systemctl restart spaceduck-bot
# then monitor mission-control.html → Agent Fleet tile
🎛️ Mission Control
6
Verify fleet health and close incident

Once agents.alive > 0, verify route health is nominal. Export a handoff pack from Mission Control. Log the incident and remediation to GOVERNANCE-LOG.md. Reset operator acknowledgements.

GET /beak/system/status
# Verify: agents.alive > 0, agents.dead == 0
📋 Governance Log 📝 Postmortem
📋 Pre-Resurrection Checklist