Control plane and agent

Chalupa does not control droplets over SSH. The agent installed by cloud-init observes the environment and sends data to an HTTPS endpoint. This constraint keeps the control plane compatible with Vercel and reduces its privileges.

Signal flow

1. task up delivers the control-plane URL and an ingest key to the droplet.
2. The agent observes uptime, containers, disk, and reaper state.
3. It serializes a v1 JSON payload.
4. It signs the method, path, timestamp, nonce, and body hash.
5. It sends the request over HTTPS.
6. The control plane validates the signature and rejects replays.
7. The observation updates the environment detail view.

The normal interval is 30 seconds. Reasonable delays do not imply destruction; an old enough signal changes the state to stale.

Heartbeat payload

This example is entirely synthetic:

{
  "version": "1",
  "environmentSlug": "demo-harbor",
  "environmentName": "Demo Harbor",
  "observedAt": "2026-07-23T18:20:00.000Z",
  "deployment": {
    "provider": "digitalocean",
    "providerId": "10001",
    "region": "nyc3",
    "sizeSlug": "s-2vcpu-4gb",
    "launchedAt": "2026-07-23T17:50:00.000Z"
  },
  "ip": "192.0.2.44",
  "uptimeSeconds": 1800,
  "containers": [
    {
      "name": "api",
      "state": "running",
      "memoryMiB": 312,
      "cpuPercent": 4.8
    },
    {
      "name": "postgres",
      "state": "running",
      "memoryMiB": 486
    }
  ],
  "reaper": {
    "idleChecks": 2,
    "checkIntervalSeconds": 300,
    "limitMinutes": 45,
    "lastActivityAt": "2026-07-23T18:08:00.000Z"
  },
  "disk": {
    "mountedGiB": 20,
    "usedGiB": 1.4
  },
  "agentVersion": "1"
}

The addresses in this guide come from the RFC 5737 documentation ranges. Do not publish real IP addresses in documentation, metadata, or screenshots.

HMAC signature

Each request includes:

The canonical string is:

v1
POST
/api/ingest
<timestamp>
<nonce>
<sha256-of-body>

The control plane accepts limited clock skew and claims each nonce exactly once. The request signs the exact body bytes; serializing the body again after signing invalidates the request.

Visible states

Chalupa shows the time of the latest observation. unknown is preferable to inventing a healthy state.

Payload privacy

The heartbeat accepts container names, resource metrics, and deployment data. It does not accept:

• environment variables;
• application logs;
• credentials;
• database contents;
• sensitive arguments;
• artifact files.

If you need to attach larger evidence, report an artifact reference in a suite run.

Explicit events

The agent and lifecycle integrations can send batches to /api/ingest/events to record transitions such as launched, sunk, reaper-warning, reaper-destroyed, or seed-restored. In particular, task down emits sunk after a successful destroy. If Chalupa is unavailable, the task warns you. Subsequent reconciliation can confirm absence only when Chalupa already observed that deployment; verify short-lived missed cycles against the provider invoice.

Each event carries a stable sourceEventId. Repeating the same batch must not duplicate the event.