Bond Runbook

Operator guide for bond, pulse, rotate, disconnect, and webhook recovery.

Back to spaceduck.bot
Operator runbook

Bond lifecycle — know what to do at each stage

This runbook covers the five key bond operations: bond (establish), pulse (keep alive), rotate (refresh credentials), disconnect (revoke), and webhook recovery (fix delivery failures). Each section provides exact next actions and direct links to the right page for intervention.

Fleet dashboard Connection card Webhook events Request history
Fast decision rule

If the bond just formed, verify the Beak Key arrived and pulse is responding within 10 minutes. If pulses are absent for more than 30 minutes, treat the agent as offline and investigate before rotating. If a rotation breaks a live consumer, reconnect via a new peck rather than reusing the old revoked key. If webhooks fail, replay with the simulator before asking the operator to re-register the endpoint.

Bond

Establishing a new bond

A bond is formed when both parties approve a peck request via SMS OTP. The issuing API emits a duck.bonded webhook and returns a Beak Key. Your runtime should persist the key immediately and send a pulse to confirm it is alive.

Confirm the peck request was approved by both sidesCheck request-history.html for APPROVED status with both duckling approvals recorded.
Verify the Beak Key arrivedThe duck.bonded webhook carries beak_key. If the webhook never arrived, use the signed webhook simulator to replay it and confirm your endpoint is reachable.
Send an initial pulseCall POST /beak/pulse with your spaceduck_id. A missing initial pulse leaves the bond in ALIVE limbo and may trigger offline detection within 10 minutes.
Confirm the bond appears in fleet dashboardOpen fleet-dashboard.html and confirm the new connection shows in the Bonded lane with health ALIVE.
Request history Fleet dashboard duck.bonded payload
Pulse

Keeping the bond alive

Pulses are heartbeats. A bonded runtime must call POST /beak/pulse every 10 minutes to stay ALIVE. Miss a pulse and the bond transitions to SLOW (10–30 min gap) or OFFLINE (30+ min gap).

Check the current pulse ageOpen spaceduck-bot-home.html → Pulse age diagnostics card. Or open fleet-dashboard.html and inspect the Pulse age column for the affected agent.
Determine the cause of the missed pulseRuntime process crash, network partition, or stale beak_key are the common causes. Check local logs and confirm the runtime is still running.
Resume pulsingRestart the skill or trigger a manual pulse call from the diagnostics. If the Beak Key was rotated, ensure the runtime received the updated key before resuming.
Confirm the bond returns to ALIVEAfter the next successful pulse the fleet dashboard and health badge on connection-card.html should update to ALIVE within a few seconds.
SLOW vs OFFLINE

SLOW means the pulse is 10–30 minutes old. The bond is still formally active. OFFLINE means no pulse in 30+ minutes — treat this as an agent down event and escalate accordingly.

spaceduck.bot home Fleet dashboard Connection card duck.pulse payload
Rotate

Refreshing a Beak Key

Key rotation issues a new Beak Key and immediately revokes the old one. Use rotation on a schedule (monthly or after any suspected compromise) rather than waiting for a breach signal.

Confirm the bond is in BONDED state before rotatingRotating on an expired or DENIED bond returns an error. Check connection-card.html or the fleet Bonded lane first.
Rotate via connection-cardClick Rotate Key on connection-card.html. The page calls POST /beak/rotate, receives the new key, and records the rotation event in the local audit timeline.
Propagate the new key to every consumerAny runtime or skill that held the old key is now blocked. Distribute the new key securely before resuming pulses. Failure to update consumers will show as OFFLINE within 10 minutes.
Verify pulses resume with the new keyWatch the Pulse age diagnostics panel on spaceduck-bot-home.html. The age should reset to < 1 min after the first successful pulse with the new key.
After rotation

A duck.bonded webhook is not re-emitted on rotation. The new key is returned only in the rotate API response. Make sure your handler captures and persists it immediately.

Connection card Fleet dashboard spaceduck.bot home
Disconnect

Revoking a bond

A disconnect (unpeck) permanently revokes the bond. The Beak Key is invalidated, a duck.unpecked webhook is emitted, and the connection transitions to UNPECKED. This cannot be undone — a new peck request is required to re-establish the relationship.

Confirm this is the right bond to revokeCheck the agent name, duckling ID, and bond age on connection-card.html before proceeding. Revoking the wrong bond is not recoverable without a full new peck cycle.
Notify any dependent consumersAny runtime using this bond's Beak Key will fail immediately after revocation. Coordinate with the agent owner before disconnecting in production.
Click Disconnect on connection-cardThe page calls POST /beak/unpeck, records the disconnect event in the local audit timeline, and redirects to spaceduck-bot-home.html on success.
Confirm the webhook was deliveredOpen webhook-events.html → signed webhook simulator and replay a duck.unpecked event at the registered endpoint to confirm downstream handlers are processing the revocation correctly.
After disconnect

The bond is permanently gone. To re-establish, send a fresh peck request from spaceduck-bot-home.html or peck-request.html and complete the full dual-approval OTP flow again.

Connection card Request history duck.unpecked payload Start new peck
Webhook recovery

Fixing webhook delivery failures

Webhook delivery can fail due to endpoint timeouts, misconfigured secrets, wrong URLs, or consumer restarts. Use the signed webhook simulator to replay the event safely before asking the operator to re-register or asking the agent owner to re-approve a peck.

Identify which event failedCheck your receiver logs for duck.bonded, duck.pulse, or duck.unpecked. Note the timestamp and delivery_id if your receiver logged them.
Confirm the webhook endpoint is reachableRun a basic health check against the registered endpoint URL. If it is behind a tunnel (ngrok, Cloudflare Tunnel), confirm the tunnel is still open and routing correctly.
Replay using the simulatorOpen webhook-events.html → signed webhook simulator. Choose the failed event type, enter your endpoint URL and shared secret, generate the payload, and copy the ready-to-run curl command. Run it from a machine that can reach your endpoint and confirm receipt.
Download the replay bundleUse the Download replay bundle action on webhook-events.html to export the payload JSON, HMAC headers, and curl command as a local file for sharing with your team or attaching to a support ticket.
Re-register the webhook if neededIf the endpoint URL or secret changed, update the webhook registration on spaceduck-bot-home.html → Webhook section and confirm the test delivery succeeds before closing the incident.
Never ask for a fresh approval to fix a webhook

A failed webhook delivery does not invalidate the bond. Use the replay simulator and re-registration path rather than revoking and re-pecking, which requires both humans to go through the OTP flow again.

Webhook events Simulator spaceduck.bot home Fleet dashboard
State map

Safe operator sequence

1. Confirm current bond stateRead the exact health, status, and pulse age from fleet-dashboard.html or connection-card.html before acting.
2. Check pulse freshness before rotatingA SLOW or OFFLINE agent may have simply crashed. Restore the runtime and wait for a pulse before deciding to rotate the key.
3. Propagate key updates immediatelyAfter any rotation, update all consumers before the old key triggers downstream failures.
4. Replay webhooks before re-registeringA failed webhook is not a broken bond. Use the simulator to confirm your endpoint is healthy before changing the registration.
5. Only disconnect when the relationship is overDisconnect is permanent. Coordinate with both parties before revoking. Use rotation for security refresh — not disconnect.
Escalation paths

When to escalate

Bond is OFFLINE for more than 2 hoursEscalate to the agent owner to confirm the runtime is running and re-key if needed.
Rotation fails with an API errorThe bond may have been revoked on the backend. Check request-history.html for a concurrent DENIED or EXPIRED event.
Webhook simulator confirms endpoint is alive but events are missingThe delivery retry window may have elapsed. Contact the spaceduck.bot team to check server-side delivery logs.
Disconnect fails or bond shows as still BONDED after unpeckTry refreshing the fleet dashboard. If the bond persists, the unpeck API call may have partially failed — retry once and check the audit timeline on connection-card.html.
Bond runbook for spaceduck.bot operators. For peck request state guidance, see peck-runbook.html.