Event Ingestion

How the edge daemon delivers events to the cloud — batching, overflow, SNS/SQS fan-out

Event Ingestion

The edge daemon delivers events to the cloud via a single HTTP endpoint: POST https://api.quintai.dev/v1/ingest. The ingest service authenticates the deploy token, validates the payload, stamps org_id, and publishes to an SNS FIFO topic for fan-out.

Earlier versions of Quint used NATS JetStream for fan-out. In 2026-Q1 the cloud was redesigned around SNS FIFO + SQS for managed delivery and simpler ops. NATS has been removed from the production path.

Edge-side forwarder

internal/cloud/forwarder.go in the daemon:

Setting	Value
Buffer capacity	5,000 events
Batch size	500 events (cap: 10 MB per request)
Flush interval	1 second
Max retries	5 (exponential backoff 1s → 5min)
Overflow	JSONL file on disk (~/.quint/forwarder-overflow.jsonl)
Recovery	On next successful flush, recovered events are prepended

The forwarder is non-blocking. If the buffer fills faster than it drains, oldest events are dropped — telemetry is lossy under pathological load, never the critical path.

Wire format

Each request body:

{
  "events": [
    {
      "schema_version": 2,
      "event_id": "uuid-v4",
      "timestamp": "2026-04-25T03:09:32.138Z",
      "source": "proxy",
      "platform": "claude-code",
      "action_type": "tools/call",
      "session_id": "59247-1777085379101",
      "agent_id": "ne-pid-59247",
      "tool_name": "Bash",
      "arguments_json": "{...}",
      "decision": "allow",
      "labels": {"process_name": "claude", "process_pid": "59247"}
    },
    ...
  ]
}

Schema validated server-side at ingest. Max 500 events per request, max 10 MB payload.

Authentication

Header: Authorization: Bearer <deploy_token>

The ingest service SHA256-hashes the token and looks it up in Redis (write-through cache backed by the api_tokens Postgres table). The response carries the org_id, which is stamped on every event before fan-out.

Token types:

Type	Use	Lifetime
install	First-contact token shipped with .pkg installer	Single-use
enrollment	Exchanged during POST /v1/machines/register	Single-use
service	Long-lived token used for subsequent ingest	Rotatable
personal	Developer tokens for CLI / dashboard	Manual

See Auth Overview for the full token hierarchy.

Fan-out

After validation, each event is published to SNS FIFO topic quint-events-{env}. Three SQS queues subscribe:

• quint-events-pipeline → pipeline service → writes to Postgres actions (partitioned by month)
• quint-events-sessions → session-processor → upserts sessions table
• quint-events-alerts → alert-processor → evaluates rules → writes alerts

FIFO ordering is per-session (MessageGroupId = session_id), so the session-processor sees a session’s lifecycle events in order even under parallel consumption.

Session lifecycle events

Separate endpoint: POST /v1/sessions/ingest. Payload is a single LifecycleEvent:

{
  "event_type": "session_start",
  "session_id": "59247-1777085379101",
  "agent_id": "ne-pid-59247",
  "platform": "claude-code",
  "working_dir": "/Users/you/project",
  "started_at": "2026-04-25T03:09:11Z"
}

Types: session_start, session_resume, session_end. The session-processor service upserts the cloud sessions row and emits an SSE event to connected dashboard clients.

Observability

Metric	Where
Edge forwarder queue depth	Daemon /debug/flows endpoint
Overflow file size	ls -la ~/.quint/forwarder-overflow.jsonl
Ingest 4xx/5xx rate	CloudWatch alarm on quint-prod-ingest
SQS depth per queue	CloudWatch ApproximateNumberOfMessagesVisible