Skip to content
EdgePlane

Real-Time Events

EdgePlane emits a chunked Server-Sent Events (SSE) feed on /events/stream describing inbox events, approvals, governance signals, and mission state changes.

SSE Endpoint

Section titled “SSE Endpoint”
GET /events/stream
Authorization: Bearer <token>

Each SSE chunk is a JSON object sent via data: lines:

{
  "type": "approval" | "inbox" | "matrix",
  "domain_id": "...",
  "mission_id": "...",
  "agent_id": "...",
  "status": "pending" | "approved" | "rejected",
  "payload": { },
  "rate_limit": {
    "limit": 60,
    "remaining": 42,
    "reset_at": "2026-03-10T15:42:00Z"
  }
}

The optional rate_limit block lets local consumers back off when the server is throttling.

Event Types

Section titled “Event Types”
typeDescription
approvalA governance approval request or resolution
inboxAgent inbox message
matrixMission state change or telemetry event

Backoff and Resilience

Section titled “Backoff and Resilience”

Recommended client behavior:

  • Start with 1s backoff on disconnect, double up to ~30s
  • On reconnect, send the last known id to resume without gaps
  • Pause fan-out retransmission while rate_limit.remaining == 0; resume after reset_at plus a small buffer
  • Log reconnect timestamps for observability (edgeplane system doctor surfaces rate-limit throttling)

Local Fan-Out

Section titled “Local Fan-Out”

edgeplaned can run a local SSE/WebSocket fan-out server that replays every structured event to local consumers. Local event fan-out is configured via edgeplaned configuration. See the edgeplaned daemon reference for details.

Local clients (CLI panels, dashboards, local controllers) connect to the fan-out at /events and receive the same stream without expensive polling.

The fan-out:

  • Respects the upstream rate limit — pauses retransmission when remaining hits zero
  • Emits event: matrix-down when upstream returns non-200, so UIs can show a reconnection banner
  • Optionally accepts MQTT topics and re-emits them on the same stream

WebSocket Endpoint

Section titled “WebSocket Endpoint”

An optional WebSocket mirror is available at /events/ws for clients that prefer WebSocket over SSE.

Schema Pack Validation

Section titled “Schema Pack Validation”

edgeplane validates payloads against the same schema pack the backend enforces:

Terminal window
export EP_SCHEMA_PACK_FILE=docs/schema-packs/main.json

With EP_SCHEMA_PACK_FILE set, the daemon validates domain, mission, task, doc, and artifact payloads before invoking /mcp/call. Invalid packs fall back to embedded defaults at startup.

Planner Booster (Advanced)

Section titled “Planner Booster (Advanced)”

For faster-than-LLM validation loops, supply a Wasm module with --booster-wasm:

Terminal window
edgeplane daemon --booster-wasm /path/to/validate.wasm

The module implements validate(ptr, len) and runs before every MCP tool call. It can short-circuit the HTTP request with instant success while still emitting structured telemetry. The embedded default validates that payloads are non-empty.

Environment Variables

Section titled “Environment Variables”
VariablePurpose
EP_ALLOW_INSECUREAllow HTTP (no TLS) for dev proxy setups
EP_SCHEMA_PACK_FILEPath to schema pack file for booster validation

Operational Notes

Section titled “Operational Notes”
  • Keep OIDC session tokens and service account tokens rotation-ready — the SSE stream authenticates per-connection
  • edgeplane system doctor probes health, tools, and matrix endpoints and emits a structured JSON report with repair hints
  • edgeplane system doctor --fix ensures EP_HOME/EP_SKILLS_HOME exist and seeds a stable agent_id for local swarms

See Also

Section titled “See Also”