Cortex RMCP

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, 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

[!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 the CLI

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

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

Install it permanently with:

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:

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:

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:

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:

{
  "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 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 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 hosts into insecure http://host:2375 endpoints and should only be used on a tightly controlled private network. A hosts file supports explicit base URLs and safer endpoint configuration.

Managed file tails

Managed file-tail sources are persisted in a registry and supervised by the daemon. Add, remove, list, and inspect sources through the CLI, REST, or the file_tails MCP admin action.

The path policy rejects unsafe targets, including paths outside configured roots, symlink escapes, non-regular files, and sensitive mounts. Container deployments expose an explicit read-only file-tail root rather than the entire host filesystem.

Host heartbeats

The host agent can post bounded JSON snapshots to POST /v1/heartbeats. Heartbeats include host state such as load, memory, disks, networking, processes, and container summaries. They power host_state, fleet_state, and correlate_state.

Heartbeat request bodies are capped at 256 KiB. Heartbeat data has short operational retention separate from the main log-retention policy.

AI transcripts

Cortex indexes local and forwarded transcript data from:

• Claude Code projects under ~/.claude/projects
• Codex sessions and worktrees under ~/.codex/sessions and ~/.codex/worktrees
• Gemini chat data under ~/.gemini/tmp

The scanner supports incremental checkpoints, parse-error records, bounded chunks, broad-path rejection, and safe recovery from changed files. It extracts normalized transcript rows plus dedicated skill, MCP tool-call, and hook events.

A satellite agent can send already-parsed records to POST /v1/ai-transcripts, which prevents transcript collection from depending on the database living on the same host as the AI client.

Shell and agent activity

Satellite agents can forward additional operational evidence to the shared server:

• POST /v1/agent-commands for deduplicated agent command-spool records
• POST /v1/shell-history for parsed Bash, Zsh extended-history, and Atuin records

These records use the same storage and correlation model as the rest of Cortex, which makes an agent change or shell command visible beside the service failure that followed it.

Fleet inventory

Inventory collection builds a redacted fleet snapshot from local files, SSH probes, Docker endpoints, and optional service APIs, then projects safe relationships into the investigation graph.

Investigation and intelligence

Cortex exposes bounded workflows rather than a raw SQL console.

Search and context

• FTS5 full-text search with host, app, severity, source, project, session, and time filters
• Structured filter-only retrieval for indexed fields
• Recent tails and single-row retrieval with raw-frame evidence
• Surrounding context around a log ID or timestamp
• Host, app, and source-IP inventories
• Clock-skew measurement using event and receive timestamps

Time and volume analysis

• Bucketed timelines
• Ingest-rate and queue-pressure state
• Near-duplicate message pattern clustering
• Recent-versus-baseline anomaly detection
• Side-by-side time-range comparison
• Silent-host and silent-stream detection
• Database, storage, and runtime statistics

Correlation

• Cross-host correlation around a timestamp
• AI-session anchor correlation against infrastructure logs
• Topic resolution through the entity graph before timeline construction
• Host-state correlation across logs, heartbeats, and inventory
• Historical incident similarity using FTS5
• Deterministic incident context bundles with bounded evidence

Recurring errors

An optional background scanner groups repeating error signatures into durable records. Operators can inspect unaddressed signatures, acknowledge them, revoke acknowledgements, and correlate a signature with logs and graph evidence.

Error detection is disabled by default. When enabled, it scans bounded batches, records lower-severity recurrences without paging, and can notify only above a configured severity floor.

Fleet inventory and graph

Inventory collectors

The native inventory subsystem can collect and normalize evidence from:

• Local and remote Compose, reverse-proxy, and AdGuard Home configuration
• Local process, storage, project, and raw configuration inventories
• SSH sessions to remote fleet hosts
• Local and remote Docker endpoints
• Tailscale
• UniFi
• Unraid
• Media-stack services and related APIs

SSH collection uses strict host-key verification, bounded concurrency, timeouts, and retry backoff. Sensitive fields are redacted before persistence.

The cache lives under ~/.cortex/inventory by default and includes:

• normalized/homelab.json: the typed normalized fleet snapshot
• collection-state.json: collector health, timing, and warning state
• raw/<run-id>/...: raw-but-redacted supporting artifacts

The map action reads the normalized cache. It does not trigger a collection run and does not return raw config bodies or credential-bearing URLs.

Derived investigation graph

The graph connects canonical entities such as:

• Hosts and source identities
• Logical services and concrete service instances
• Applications and containers
• Domains, routes, and endpoints
• AI projects and sessions
• Error signatures and operational findings

Relationships carry confidence, trust, reason codes, timestamps, and bounded evidence references. The graph supports entity resolution, neighborhoods, topology questions, evidence lookup, and explanation paths.

The graph is a rebuildable projection. Raw logs, heartbeats, inventory records, error signatures, and AI session data remain authoritative. Projection rebuilds use staging tables and a short serialized swap, record watermarks and metrics, and preserve explicit degraded state when refresh fails.

AI session intelligence

Cortex treats AI transcripts as operational evidence, not merely chat archives.

Deterministic session analysis

The shared service layer can:

• List and search sessions by project
• Measure activity in five-hour usage blocks
• Summarize project context
• List observed tools and projects
• Detect frustration or abuse signals
• Group those signals into scored incidents
• Correlate AI activity with non-AI infrastructure logs
• Extract skill invocations
• Extract MCP server and tool-call events
• Extract hook configuration and runtime events
• Build skill-first, MCP-first, and hook-first investigation bundles

The deterministic query and incident workflows are available through CLI, REST, and MCP.

Guarded local assessments

LLM-backed assessments are deliberately local-only. They run through cortex assess and are not exposed as MCP actions or REST routes because they spawn a local Gemini subprocess.

The shared LLM runner enforces:

• A global kill switch
• Global and per-action concurrency limits
• Per-minute and per-hour rate limits
• Per-action circuit breakers and cooldowns
• Invocation timeouts
• Prompt and output byte caps
• An explicit background-enrichment gate, disabled by default
• Durable audit records for successes, failures, timeouts, and policy denials

Default guard values allow one concurrent invocation, three per minute and thirty per hour per action, a 120-second timeout, a 1 MiB prompt cap, and a 256 KiB output cap.

Prompt scrubbing is enabled by default. Skill, MCP, and hook event extraction happens before scrubbed transcript text is persisted, so structured operational signals are retained without requiring raw prompt storage.

Alerts and notifications

Notifications are optional and disabled by default. When enabled, Cortex uses Apprise as the delivery bridge and a durable SQLite outbox for retry, deduplication, and dead-letter handling.

Built-in evaluators cover:

• OOM kills
• Containers exiting nonzero
• fail2ban bans
• Authelia MFA failures
• Disk-fill and storage guardrail pressure
• Ingest queue pressure
• Complete ingest silence
• Heartbeat silence
• Silence from previously active continuous streams

The notification subsystem includes:

• Configurable evaluator cadence
• Per-rule toggles and thresholds
• Deduplication windows
• Outage-scoped silence keys
• Bounded retry with dead-letter state
• Recent-firing history
• Test notifications
• A scheduled daily digest

By default, continuous stream-silence tracking covers UDP/TCP syslog, agent Docker, Docker stream and event records, and managed file tails. Sporadic sources such as transcripts and shell history are intentionally excluded.

Interfaces

CLI

Run cortex --help and command-specific --help for the generated command tree.

Examples: