Beacon

The Beacon system provides auto-discovery and heartbeat monitoring for AI agents, giving enterprises real-time visibility into their agent fleet.

How It Works

┌─────────────┐         ┌──────────────────┐         ┌─────────────┐
│   Agent      │──────▶  │  Sekuire Backend │  ◀──────│  Dashboard  │
│              │ heartbeat│                  │  query  │             │
│  beacon loop │──────▶  │  stores status   │──────▶  │  shows fleet│
└─────────────┘         └──────────────────┘         └─────────────┘

1. Agent starts and registers with the Sekuire backend
2. Beacon loop sends periodic heartbeats (default: every 60 seconds)
3. Backend tracks liveness, status, and metadata
4. Dashboard shows real-time fleet status
5. If heartbeats stop, the agent is marked as unhealthy

---

Heartbeat Lifecycle

Phase	Action	Backend Response
Registration	Agent sends initial heartbeat with metadata	Returns lease duration and config
Running	Periodic heartbeats with status updates	Confirms lease renewal
Token refresh	Runtime token within 7 days of expiry	Returns new refreshed_token
Lease expiry	Agent misses heartbeat window	Marks agent as unhealthy
Revocation	Kill switch triggered	Returns revocation signal on next heartbeat
Shutdown	Agent sends final shutdown signal	Marks agent as stopped

---

Platform Detection

Beacon automatically detects the runtime platform and includes this in heartbeat metadata:

Platform	Detection Method	Metadata Reported
Docker	/.dockerenv file presence	Container ID, image name
Kubernetes	KUBERNETES_SERVICE_HOST env	Pod name, namespace, node
AWS Lambda	AWS_LAMBDA_FUNCTION_NAME env	Function name, region
Bare Metal	Default fallback	Hostname, OS, PID

---

Heartbeat Payload

POST /api/v1/installations/:id/heartbeat

{
  "status": "healthy",
  "uptime_seconds": 3600,
  "platform": {
    "type": "kubernetes",
    "pod_name": "my-agent-7f8a9b-xyz",
    "namespace": "production",
    "node": "node-pool-1-abc"
  },
  "metrics": {
    "requests_handled": 1500,
    "errors": 2,
    "avg_latency_ms": 145
  }
}

---

Heartbeat Response

The heartbeat response includes lease information and optional token refresh:

Heartbeat response

{
  "installation_id": "uuid",
  "lease_expires_at": "2026-02-03T12:05:00Z",
  "next_heartbeat_at": "2026-02-03T12:01:00Z",
  "command": null,
  "refreshed_token": {
    "runtime_token": "srt_new_xxx",
    "expires_at": "2026-05-03T12:00:00Z",
    "token_version": 2
  }
}

Field	Description
lease_expires_at	When the current lease expires
next_heartbeat_at	When to send the next heartbeat
command	Pending command from kill switch (pause/resume/terminate)
refreshed_token	New runtime token if current one is near expiry (within 7 days)

When refreshed_token is present, the SDK automatically updates its stored credentials.

---

Kill Switch Integration

The Beacon heartbeat response includes a revoked field. When the kill switch is triggered:

Heartbeat response (revoked)

{
  "lease_renewed": false,
  "revoked": true,
  "reason": "Emergency shutdown initiated by admin",
  "shutdown_timeout_ms": 5000
}

The agent SDK checks this field and initiates graceful shutdown.

note

See Kill Switch for details on revocation.

---

CLI Usage

Run with beacon enabled (default)

sekuire run --cmd "npm start"

Custom heartbeat interval

sekuire run --heartbeat-interval 30

Disable beacon (not recommended)

sekuire run --no-heartbeat

Next Steps

• Kill Switch - Emergency revocation
• sekuire run - CLI beacon options
• Beacon SDK - Programmatic beacon control