Cortex

Cortex

Self-hosted homelab log intelligence over MCP, CLI, and REST with SQLite/FTS.

It collects logs and operational evidence, stores them in SQLite with FTS5 search, and exposes one shared intelligence layer through CLI, REST, MCP, and a bundled browser workspace.

Cortex began as a syslog receiver. It now covers network logs, Docker, managed files, OpenTelemetry logs, metrics, and traces, host heartbeats, fleet inventory, shell and agent activity, and Claude, Codex, Gemini CLI, and Antigravity transcripts. It correlates those sources into timelines, incidents, and an evidence-backed topology graph without making the graph a second source of truth.

At a glance

[!IMPORTANT]

Cortex is designed for a trusted homelab or small private fleet. It is not a clustered log warehouse, a general-purpose SIEM, or a safe place to expose unauthenticated administrative surfaces to the public internet.

Contents

• Quick start
• How Cortex is built
• Ingestion
• Investigation and intelligence
• Fleet inventory and graph
• AI session intelligence
• Alerts and notifications
• Interfaces
• Configuration
• Authentication and trust boundaries
• Storage and maintenance
• Deployment and distribution
• Operations
• Development and verification
• Documentation
• Current boundaries
• License

Quick start

Install and choose a role

curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/cortex/main/install.sh | sh

On Windows x64:

irm https://raw.githubusercontent.com/dinglebear-ai/cortex/main/install.ps1 | iex

The checksum-verified bootstrap supports Linux x64/ARM64, macOS ARM64, and Windows x64. It runs cortex setup start, which asks whether this machine is a server, a client, or a host agent. Server setup prepares configuration, distinct MCP/REST credentials, storage and managed Compose. Client setup connects selected MCP clients. Agent setup detects local collection prerequisites and enables only the capabilities you explicitly select. First server setup also asks for authentication mode, exposure, and an optional six-hour backup schedule.

Already have the CLI, or automating installation? Select the role explicitly:

cortex setup start --role server --clients codex,claude,gemini

cortex setup start --role client --server https://cortex.example.com \ --token-file /private/mcp-token --api-token-file /private/rest-token cortex setup start --role agent --server https://cortex.example.com \ --token-file /private/ingest-token --capabilities docker,transcripts

First-time noninteractive setup requires --role; subsequent setup reuses the saved choice. --dry-run --json previews configuration and capabilities without installing services. All advanced settings remain available through --set and --secret-file; sensitive collection requires explicit selection. --backup-schedule and --no-backup-schedule save the backup scheduling choice.

cortex setup effective --json

cortex setup verify --json cortex update

Verification proves authenticated MCP access and REST access when configured; source delivery still needs its own evidence. Updates use saved deployment settings and respect version pins. See the setup guide for capability selection, OAuth, prerequisites, source builds, manual native operation, and installer environment controls; see the deployment runbook for backup and recovery.

For guided agent assistance:

npx skills add dinglebear-ai/cortex --skill install-cortex

Start a fresh task and invoke $install-cortex.

The npm launcher remains available for local CLI and stdio MCP use with Node.js 18 or newer:

npx -y @dinglebear/cortex --help

npx -y @dinglebear/cortex mcp npm install --global @dinglebear/cortex

Connect an MCP client

Query-only stdio mode reads the configured local database and starts no network listeners:

{

"mcpServers": { "cortex": { "command": "npx", "args": ["-y", "cortex-rmcp", "mcp"], "env": { "CORTEX_DB_PATH": "/absolute/path/to/cortex.db" } } } }

Streamable HTTP mode connects to the persistent daemon:

{

"mcpServers": { "cortex": { "url": "http://127.0.0.1:3100/mcp", "headers": { "Authorization": "Bearer your-cortex-token" } } } }

A useful first call is:

{"action":"status"}

Then narrow the investigation with tail, errors, search, timeline, or context before using broader analysis operations.

How Cortex is built

Cortex is one Rust binary with multiple operating modes. The same application and service layer backs the CLI, REST handlers, and MCP handlers, so validation, limits, identity resolution, redaction, and business rules do not belong to one transport alone.

                         INGESTION

Syslog UDP/TCP OTLP signals Docker agent / pull Managed file tails Heartbeats Claude / Codex / Gemini / Antigravity Shell history Agent commands Fleet inventory \ | / \ | / +---- bounded parsing and enrichment ----+ | scrub, normalize, batch | SQLite WAL + FTS5 | +----------------+----------------+ | | authoritative records derived accelerators logs, heartbeats, rollups, signatures, inventory, sessions graph projections | | +----------------+----------------+ | shared service layer | CLI REST MCP Web workspace

The daemon supervises its receivers and background services with cooperative cancellation. Shutdown drains HTTP requests, gives maintenance tasks 10 seconds to finish before abort-and-join, gives ingest 5 seconds to flush, and then attempts a WAL checkpoint. Already-running blocking SQLite calls cannot be cancelled by Tokio.

Background services include:

• Retention and storage-budget enforcement
• WAL and FTS maintenance
• Docker ingest supervision
• File-tail supervision
• Error-signature scanning
• Notification evaluation, dispatch, and digest scheduling
• Inventory refresh and backfill
• Graph projection refresh
• AI-session and timeline rollups
• Database optimization and maintenance jobs

Heavy analytical reads and maintenance jobs have separate concurrency controls so one expensive investigation cannot starve the ingest path.

Ingestion

All log-like sources are normalized into the same durable log model, enriched where safe, scrubbed where configured, and written through bounded batch paths.

Syslog over UDP and TCP

Cortex listens on the same configurable port for UDP and TCP syslog. It parses common RFC 3164 and RFC 5424 shapes, preserves the raw frame, records sender identity, normalizes severity and facility, and enriches known application formats.

Relevant defaults:

• Bind: 0.0.0.0:1514
• Maximum message: 8 KiB
• Maximum concurrent TCP connections: 512
• TCP idle timeout: 300 seconds
• Writer batch: 100 records or 500 ms
• Write queue capacity: 10,000 records

Syslog has no application-layer authentication. Restrict senders with network controls and CORTEX_ALLOWED_SOURCE_CIDRS when the listener is reachable beyond a trusted network.

Built-in enrichment recognizes useful signals from AdGuard, Authelia, Docker lifecycle events, fail2ban, Linux kernel and OOM events, SWAG, reverse-proxy logs, and host-local Cortex Docker agent metadata. Source gates can restrict enrichment that would otherwise trust a marker inside an unauthenticated syslog body.

OpenTelemetry ingestion

Cortex accepts protobuf OTLP/HTTP export requests on the shared HTTP listener. Logs use POST /v1/logs with a 4 MiB body limit and flow through the normal writer. Metrics use POST /v1/metrics and traces use POST /v1/traces, each with an 8 MiB body limit and dedicated storage. Metric requests admit at most 5,000 points and also enforce a bounded normalized payload budget.

Current OTLP scope is intentionally narrow:

• Logs, traces, and metrics over HTTP/protobuf are supported.
• OTLP/gRPC is not implemented.

All three OTLP endpoints authenticate with `CORTEX_TOKEN` — the same static MCP bearer token that guards POST /mcp, read from the managed ~/.cortex/.env on a deployed host. It is not CORTEX_API_TOKEN (REST /api/*) and not CORTEX_API_ADMIN_TOKEN. Loopback and trusted-gateway policies skip the check. An OAuth-only deployment with no static token denies OTLP outright, because machine exporters have no OAuth flow — so a non-loopback OAuth-only OTLP exposure is rejected at startup unless CORTEX_TOKEN is set.

Docker logs and events

Cortex supports two Docker collection paths:

1. Host-local agent, the preferred multi-host path. The host-local cortex agent reads the local Docker socket, converts logs and lifecycle events into bounded records, and forwards them to the server without changing Docker's daemon logging driver.
2. Central pull compatibility mode, an optional server-side collector for explicitly configured Docker Engine or docker-socket-proxy HTTP endpoints. It records per-container checkpoints and reconnects with bounded exponential backoff.

Central pull is disabled by default. The CORTEX_DOCKER_HOSTS shorthand expands h