Heartbeat Protocol

The Heartbeat Protocol (heartbeat.py, 13,661 bytes) is Clawpy's autonomous operational pulse. Every 30 minutes (configurable), the heartbeat fires, evaluates pending tasks using an LLM, and executes approved actions inside Docker sandbox worker lanes.

This is what makes Clawpy proactive — the system doesn't wait for human input to act. It reads its own task list, decides whether action is needed, and executes — all autonomously.

Pulse Lifecycle

Every 30 minutes:
  ┌─────────────────────────────┐
  │   1. Parse heartbeat.md     │  ← Read pending tasks
  └──────────┬──────────────────┘
             │
  ┌──────────▼──────────────────┐
  │   2. Filter by cron schedule │  ← Only run tasks due this tick
  └──────────┬──────────────────┘
             │
  ┌──────────▼──────────────────┐
  │   3. LLM evaluation         │  ← "Should I act on this right now?"
  │      Returns: shell command  │
  │      or NO_ACTION           │
  └──────────┬──────────────────┘
             │
  ┌──────────▼──────────────────┐
  │   4. Execute in Docker       │  ← Sandboxed worker lane
  │      sandbox (120s timeout)  │
  └──────────┬──────────────────┘
             │
  ┌──────────▼──────────────────┐
  │   5. Log result to MEMORY.md │  ← Append timestamped entry
  └─────────────────────────────┘

Task Format

The Heartbeat reads from heartbeat.md, parsing Markdown checkbox items with optional metadata:

- [ ] Check API health endpoint {id: api_health, cron: every_hour}
- [ ] Pull latest config from git {id: config_sync, cron: daily}
- [x] Run database backup {id: db_backup, cron: daily}

Metadata Fields

Tasks marked [x] are skipped (already completed).

Cron Evaluation

The Heartbeat uses a tick-based cron system instead of wall-clock scheduling:

LLM-Gated Execution

The Heartbeat doesn't blindly execute tasks. For each due task, it asks the LLM:

"Given this task description, should an automated shell action be taken right now? If yes, respond with ONLY a valid single-line shell command. If no, respond with NO_ACTION."

This means the LLM acts as an intelligent gate — it evaluates whether action is actually needed based on the current context and time.

Sandbox Worker Lanes

Approved commands execute inside Docker containers provisioned by make_sandbox_worker():

cfg = SandboxConfig(
    network="bridge",      # Allow network for git, pip, curl
    memory="256m",         # 256MB memory limit
    cpus=0.5,              # Half a core
    read_only_root=False,  # Workers need write access
    scope="agent",         # One container per agent
)

• Timeout: 120 seconds per command
• Output: stdout + stderr captured and truncated to 500 characters for memory logging
• Failure handling: Errors are logged but don't halt the heartbeat cycle

Background Maintenance Jobs

The Heartbeat scheduler also manages maintenance tasks:

Ephemeral Token Reaping (Every 5 minutes)

self.scheduler.add_job(
    self._reap_ephemeral_tokens,
    "interval", minutes=5, id="clawpy_ephemeral_reap"
)

Purges expired temporary API credentials from the SecretsManager vault.

Sandbox Pruning (Every 24 hours)

self.scheduler.add_job(
    self._prune_sandboxes,
    "interval", hours=24, id="clawpy_sandbox_prune"
)

Removes Docker containers that have been idle for 24+ hours.

Wisdom Teaching (Configurable, opt-in)

if self._wisdom_teacher and self._wisdom_teacher.config.enable_m2:
    self.scheduler.add_job(
        self._wisdom_teacher.run_teaching_cycle,
        "interval", seconds=interval_s, id="clawpy_wisdom_teaching"
    )

Runs the Mechanism 2 soul enrichment cycle for worker agents.

Memory Logging

Every heartbeat action is appended to MEMORY.md:

## Heartbeat Log [2026-04-19 22:00 UTC]
- **Task**: `api_health`
- **Command**: `curl -s https://api.clawpy.ai/health`
- **Result**:
​```
{"status": "healthy", "uptime": 432000}
​```

This creates a persistent, human-readable audit trail of everything the heartbeat has done.

Cost Awareness

The Heartbeat is cost-aware by design:

• LLM evaluation uses the cheapest available model — only enough intelligence to decide yes/no
• NO_ACTION responses cost tokens but no execution — preventing unnecessary container spin-ups
• All costs are tracked via the Budget Service — heartbeat costs count against the agent's budget
• If budget is exhausted, heartbeat continues but skips LLM evaluation — preventing cost overruns