cortex

# Cortex

[![CI](https://github.com/dinglebear-ai/cortex/actions/workflows/ci.yml/badge.svg)](https://github.com/dinglebear-ai/cortex/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/dinglebear-ai/cortex)](https://github.com/dinglebear-ai/cortex/releases)
[![npm](https://img.shields.io/npm/v/cortex-rmcp)](https://www.npmjs.com/package/cortex-rmcp)
[![crates.io](https://img.shields.io/crates/v/cortex)](https://crates.io/crates/cortex)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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, host heartbeats, fleet inventory, shell and agent activity, and Claude, Codex, and Gemini 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

| Area | What Cortex provides |
| --- | --- |
| Ingest | UDP/TCP syslog, OTLP/HTTP logs, Docker logs and events, managed file tails, host heartbeats, AI transcripts, shell history, agent command records, and fleet inventory |
| Storage | SQLite in WAL mode, FTS5 full-text search, bounded metadata, retention, storage budgets, maintenance jobs, checkpoints, and 43 sequential schema migrations |
| Investigation | Search, filtering, context, timelines, patterns, anomaly comparison, cross-source correlation, recurring error signatures, deterministic incident bundles, and graph explanations |
| Fleet intelligence | SSH and API inventory collectors, host state, service topology, container and route relationships, redacted evidence, and rebuildable graph projections |
| AI operations | Claude, Codex, and Gemini session indexing; skill, MCP, and hook event extraction; incident clustering; and guarded local LLM assessments |
| Interfaces | Native CLI, one action-dispatched MCP tool, authenticated REST APIs, MCP prompts and resources, an MCP Apps search widget, and a bundled investigation workspace |
| Operations | Setup and repair, diagnostics, Compose control, backup, integrity checks, WAL checkpoints, vacuum, update workflows, agents, and health endpoints |

> [!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](#quick-start)
- [How Cortex is built](#how-cortex-is-built)
- [Ingestion](#ingestion)
- [Investigation and intelligence](#investigation-and-intelligence)
- [Fleet inventory and graph](#fleet-inventory-and-graph)
- [AI session intelligence](#ai-session-intelligence)
- [Alerts and notifications](#alerts-and-notifications)
- [Interfaces](#interfaces)
- [Configuration](#configuration)
- [Authentication and trust boundaries](#authentication-and-trust-boundaries)
- [Storage and maintenance](#storage-and-maintenance)
- [Deployment and distribution](#deployment-and-distribution)
- [Operations](#operations)
- [Development and verification](#development-and-verification)
- [Documentation](#documentation)
- [Current boundaries](#current-boundaries)
- [License](#license)

## Quick start

### Install the CLI

The npm launcher is the fastest path for local CLI and stdio MCP use:

```bash
npx -y @dinglebear/cortex --help
npx -y @dinglebear/cortex mcp
```

Install it permanently with:

```bash
npm install --global @dinglebear/cortex
cortex --version
```

The launcher requires Node.js 18 or newer. It downloads a checksum-verified native release binary and currently supports Linux x64 and Windows x64.

Build from source with the current stable Rust toolchain:

```bash
git clone https://github.com/dinglebear-ai/cortex.git
cd cortex
mise install       # optional, but pins the repository tools
just build
./.cache/cargo/debug/cortex --version
```

### Start a local server

The full daemon starts UDP and TCP syslog receivers plus the shared HTTP server. Use separate MCP and REST tokens:

```bash
mkdir -p "$HOME/.cortex/data"
export CORTEX_DB_PATH="$HOME/.cortex/data/cortex.db"
export CORTEX_TOKEN="$(openssl rand -hex 32)"
export CORTEX_API_TOKEN="$(openssl rand -hex 32)"

cortex serve mcp
```

Defaults:

- Syslog: `0.0.0.0:1514` over UDP and TCP
- HTTP: `127.0.0.1:3100`
- MCP: `http://127.0.0.1:3100/mcp`
- REST: `http://127.0.0.1:3100/api/*`
- Investigation workspace: `http://127.0.0.1:3100/app`

Verify it from another terminal:

```bash
curl -fsS http://127.0.0.1:3100/health
logger -n 127.0.0.1 -P 1514 --tcp "cortex quickstart from $(hostname)"

export CORTEX_API_TOKEN="the-same-api-token"
cortex tail --limit 10
```

For a managed local deployment, `cortex setup repair` creates or repairs the Cortex home, Compose assets, data paths, and missing 64-character MCP and REST tokens without replacing existing token values.

### Connect an MCP client

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

```json
{
  "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:

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

A useful first call is:

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

```text
                         INGESTION

  Syslog UDP/TCP       OTLP logs          Docker agent / pull
  Managed file tails  Heartbeats         Claude / Codex / Gemini
  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, maintenance work, and ingest queues before checkpointing the WAL.

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 logs

Cortex accepts OTLP/HTTP log export requests at `POST /v1/logs` on the shared HTTP listener. Requests are bounded to 4 MiB and flow into the normal Cortex writer.

Current OTLP scope is intentionally narrow:

- Logs over HTTP are supported.
- OTLP traces are not accepted.
- OTLP metrics are not accepted.
- OTLP/gRPC is not implemented.

`POST /v1/logs` authenticates 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 `/v1/logs` exposure is rejecte