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

text

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

Agent starts and registers with the Sekuire backend
Beacon loop sends periodic heartbeats (default: every 60 seconds)
Backend tracks liveness, status, and metadata
Dashboard shows real-time fleet status
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
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/heartbeatjson

{
  "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
  }
}

Kill Switch Integration

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

Heartbeat response (revoked)json

{
  "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.

ℹ️See Kill Switch for details on revocation.

CLI Usage

Run with beacon enabled (default)bash

sekuire run --cmd "npm start"

Custom heartbeat intervalbash

sekuire run --heartbeat-interval 30

Disable beacon (not recommended)bash

sekuire run --no-heartbeat

Next Steps

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