Skip to content
Home

Architecture

The whole platform runs in your cloud.

Cardinal UI, the mcp-gateway your agents call, and the Lakerunner query engine: one deployment, inside your VPC, addressed by your IAM and your KMS keys. The diagram below shows how the pieces fit.

System overview

solid · request · dashed · response · dotted · OTLP

YOUR CLOUD · BYOCDEVELOPERCardinal UIdashboards · agent investigationsmcp-gatewaymulti-tenant MCP · lakerunner · kubeLakerunnerOTLP ingest · query engine · storageprocess-logsprocess-metricsprocess-tracesquery-apiquery-workeralert-evaluatorsweeperadmin-apiYOUR OBJECT STORAGE · S3 · GCS · AZURE BLOB.lkrn segments · years of retentionPostgres · segment metadata · tenant config · auditCoding agentClaude · Codex · Cursor · Gemini+ cardinal-plugin (hooks · skills)SentinelsCompiled DAGs · runnabletool callevidencequeryqueryplugin OTLP · agent-session telemetryYOUR APPS · KUBE · HOSTSalso emit OTLP → Lakerunner

Your coding agent calls the mcp-gateway; mcp-gateway runs typed queries against Lakerunner and streams evidence back. Cardinal UI opens the same lake in your team's browser. In parallel, the plugin emits OTLP about the session itself into your Lakerunner tenant, so agent behaviour shows up in the same lake as your services' telemetry, and none of it leaves your VPC.

Four layers

The running components.

01 · Ingest & storage

Lakerunner: observability storage and query in your object store.

OpenTelemetry pipes logs, metrics, and traces into your object store. Lakerunner reacts to S3 object notifications, packs raw signal into native .lkrn segments, and rolls it through a 10s → 1h → 24h compaction ladder. Runs inside your cloud, addressed by your KMS keys.

  • · Object store: S3 · GCS · Azure Blob
  • · Metadata: Postgres
  • · Notifications: SQS · GCP Pub/Sub · Azure Queue
  • · Runs on Kubernetes via Helm
Components6 pieces
  • process-logslog ingest, compaction, rollup
  • process-metricsDDSketch percentiles, rollups
  • process-tracestrace ingest, service graph
  • sweeperretention · GC
  • alert-evaluatorPromQL / LogQL alerts
  • monitoringInternal metrics and health monitoring

02 · Query surface

One distributed query engine, several consumers.

A stateless query tier fronts the lake. query-api takes PromQL, LogQL, and MCP tool calls, hashes work across query-workers, and streams results back over SSE. Humans consume through Cardinal UI; agents consume through mcp-gateway; teams already on Grafana can point the Lakerunner datasource plugin at the same query API.

  • · PromQL & LogQL supported
  • · Grafana datasource plugin available as an optional consumer
  • · Rendezvous-hashed work assignment across workers
  • · Multi-tenant · organization_id partitioning
Components4 pieces
  • query-apigRPC control · SSE streaming
  • query-workerLKRN query execution
  • admin-apiconfig · org · bucket
  • lakerunner-clishell query client

03 · Cardinal UI & gateway

Cardinal UI and the MCP gateway, one deployment in your cloud.

Cardinal UI is where humans open dashboards and drive agent-run investigations. Alongside it, the MCP gateway exposes a typed, multi-tenant interface for coding agents on local machines. Both ship in one image, sit behind Keycloak / SSO, and talk to Lakerunner over your cluster's own network.

  • · Ships as one image · Cardinal UI + mcp-gateway
  • · Runs in your Kubernetes cluster, behind your ingress
  • · Auth: OIDC · SSO · SCIM
  • · Deployed with Helm
Components4 pieces
  • Cardinal UIReact SPA + agent server
  • mcp-gatewaymulti-tenant MCP over Lakerunner + Kube
  • SSOOIDC · SSO · SCIM · RBAC
  • Postgresthread state · decisions · audit

04 · In-agent runtime

Plugins and sentinels: the agent surface, plus compounding memory.

The Cardinal plugin drops into your coding agent's harness as hooks, skills, and subagents. Hooks emit OTLP back into your Lakerunner tenant; skills give the agent slash-commands for install, mechanize, and status. The /mechanize skill compiles a completed investigation into a typed, immutable Sentinel DAG: reusable software your team's next question can call.

  • · Runs inside your agent's own process
  • · Stdlib-only Python 3.11+ · zero pip install for users
  • · Sentinel node kinds: tool · function · llm · condition · emit · ask_human
  • · Store: .mechanize/ · sentinels · variations · runs · captures
Components6 pieces
  • adapters/claudehooks · skills · subagents
  • adapters/codexequivalent surface for Codex CLI
  • adapters/cursorCursor rules + MCP wiring
  • adapters/geminiGemini CLI hooks
  • cardinal_coreOTLP · limits · session · pricing
  • sentinelstyped executable DAGs · variations

Deployment model

The platform, in your cloud.

There is no hosted control plane brokering your telemetry. Cardinal ships as one deployment you run inside your Kubernetes cluster. Cardinal, the company, never holds your data.

What runs in your cloud

BYOC
  • Cardinal UI + mcp-gateway + Lakerunner: one Kubernetes deployment
  • Telemetry lands in your S3 / GCS / Azure Blob
  • Postgres for segment metadata, tenant config, and audit (yours)
  • Bring your own KMS keys · your IAM · your VPC
  • Keycloak-hosted SSO / SAML / SCIM, inside your perimeter
  • AWS · GCP · Azure: same image, IaC per cloud
  • On-prem too: any Kubernetes with Postgres, S3-compatible storage, and room to scale

What never leaves the perimeter

Never leaves
  • Raw telemetry: logs, metrics, traces
  • Query results and evidence returned to agents
  • Tenant configuration, API keys, audit trail
  • The KMS-encrypted segments in object storage

Go deeper

How the storage layer works.

The pieces above are the map. These go a level down into the data path, the file format underneath it, and what it costs to keep that format query-shaped.

Data path

Observability Without Kafka, Hot Storage, or a Vendor Backend

How telemetry moves: collectors write to object storage, stateless ingest workers turn it into LKRN, and query workers read it back. What the shape buys you, and what it deliberately leaves out.

Read →

Storage format

Why We Replaced Parquet + DuckDB with a Custom Format Called LKRN

Why a general-purpose columnar format wasn't enough for observability data, and what an OpenTelemetry-native format changes about compaction, planning, and memory.

Read →

Mechanics

Compaction Ate Half Our Compute. So We Made Merging Files a Byte Copy.

Merging files is close to a byte copy, and publishing the result is one database transaction, which is why compaction runs continuously without ever disturbing a query.

Read →

Query path

S3 Isn't Slow: You're Reading It Wrong

Object storage is not a slow disk, it is a different shape. Prune in Postgres before reading an object, fetch in parallel range reads, and route repeat queries back to a warm cache.

Read →

Deployment

The Invisible Line Item: What Telemetry Egress Actually Costs

A collector per cluster writing to its own bucket, one Lakerunner reading them all. Every hop stays inside your account, which removes the egress line item you never negotiated.

Read →

See it in your own cloud, in a few minutes.

The install flow stands Cardinal UI, mcp-gateway, and Lakerunner up in your account, wires the OpenTelemetry Collector, and connects your agent. No vendor-hosted copy of your telemetry, no per-agent credentials.

Get started freeRead the docsEnterprise BYOC →