{"id":50746326,"url":"https://github.com/jmagar/cortex","last_synced_at":"2026-06-10T21:30:26.755Z","repository":{"id":347668399,"uuid":"1194132851","full_name":"jmagar/cortex","owner":"jmagar","description":"Homelab syslog receiver plus MCP server for searching, tailing, and correlating logs across hosts.","archived":false,"fork":false,"pushed_at":"2026-06-08T00:02:56.000Z","size":8594,"stargazers_count":1,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T00:21:45.935Z","etag":null,"topics":["ai","claude-code","claude-code-plugins","codex","gemini","homelab","llm","logs","mcp","mcp-server","model-context-protocol","observability","rust","self-hosted","sqlite","syslog"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmagar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-28T00:44:31.000Z","updated_at":"2026-06-06T06:33:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jmagar/cortex","commit_stats":null,"previous_names":["jmagar/syslog-mcp","jmagar/cortex"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/jmagar/cortex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmagar%2Fcortex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmagar%2Fcortex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmagar%2Fcortex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmagar%2Fcortex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmagar","download_url":"https://codeload.github.com/jmagar/cortex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmagar%2Fcortex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34172196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","claude-code-plugins","codex","gemini","homelab","llm","logs","mcp","mcp-server","model-context-protocol","observability","rust","self-hosted","sqlite","syslog"],"created_at":"2026-06-10T21:30:24.291Z","updated_at":"2026-06-10T21:30:26.722Z","avatar_url":"https://github.com/jmagar.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cortex\n\n[![crates.io](https://img.shields.io/crates/v/cortex)](https://crates.io/crates/cortex) [![ghcr.io](https://img.shields.io/badge/ghcr.io-jmagar%2Fcortex-blue?logo=docker)](https://github.com/jmagar/cortex/pkgs/container/cortex)\n\nRust syslog receiver and MCP server for homelab log intelligence. Ingests syslog over UDP and TCP, stores it in SQLite with FTS5 full-text indexing, and exposes action-based log search, inventory, correlation, status, and analysis tools through MCP, REST, and CLI adapters backed by the shared service layer.\n\ncortex also maintains derived projection tables for future investigation graph\nfeatures. Those graph tables connect source IPs, claimed hosts, apps, services,\ncontainers, AI projects/sessions, and error signatures with evidence, but raw\nlogs, heartbeats, inventory, signatures, and session rows remain the source of\ntruth. The graph projection is rebuildable and intentionally has no ingest\ntriggers. Graph rebuilds use staging tables plus a short serialized swap and\nrecord explicit projection status, source watermarks, row counts, runtime\nmetrics, and degraded failure state.\n\n## Overview\n\n```\n                    ┌─────────────────────────────────┐\n  rsyslog/syslog-ng ─▶  UDP :1514 / TCP :1514          │\n  network devices   ─▶  ┌──────────────────────────┐   │\n                    │   │  parse → batch writer     │   │\n                    │   │  SQLite + FTS5 (WAL mode) │   │\n                    │   └──────────────────────────┘   │\n  Claude / MCP ◀──── ▶  RMCP HTTP :3100/mcp             │\n  local MCP client ◀──▶  syslog mcp query process       │\n                    └─────────────────────────────────┘\n```\n\nThe daemon listens on a single port for both UDP and TCP syslog (default `1514`). All inbound messages are parsed, batched, and written to SQLite with full-text indexing. The MCP HTTP server runs on a separate port (default `3100`) and uses RMCP Streamable HTTP in stateless JSON-response mode. Local stdio-only MCP clients can launch `cortex mcp`, a query-only MCP process that reads the same SQLite database without starting syslog listeners or the HTTP server.\n\nMCP is an exposure surface, not the owner of log-intelligence business policy. Shared defaults, limits, validation, audit identity, correlation behavior, and safety gates should live in `SyslogService` or service-owned operation models so MCP, REST, and CLI remain consistent.\n\n---\n\n## Tools\n\nOne MCP tool, `cortex`, is exposed. Use the required `action` argument to run `search`, `filter`, `tail`, `errors`, `hosts`, `map`, `sessions`, `search_sessions`, `abuse`, `abuse_incidents`, `abuse_investigate`, `ai_correlate`, `usage_blocks`, `project_context`, `list_ai_tools`, `list_ai_projects`, `correlate`, `stats`, `status`, `apps`, `source_ips`, `timeline`, `patterns`, `context`, `get`, `ingest_rate`, `silent_hosts`, `clock_skew`, `anomalies`, `compare`, `compose_status`, `compose_doctor`, `unaddressed_errors`, `ack_error`, `unack_error`, `notifications_recent`, `notifications_test`, `similar_incidents`, `ask_history`, `incident_context`, `graph`, or `help`.\n\nFor the complete action-specific parameter reference, see [`docs/mcp/SCHEMA.md`](docs/mcp/SCHEMA.md). For correlation behavior and AI/non-AI inclusion rules, see [`docs/mcp/CORRELATION.md`](docs/mcp/CORRELATION.md).\n\n| Action | Purpose |\n| --- | --- |\n| `search` | Full-text search with filters |\n| `filter` | Structured filter-only log retrieval |\n| `tail` | Recent log entries |\n| `errors` | Error/warning summary by host and severity |\n| `hosts` | Host registry with first/last seen |\n| `map` | Cached homelab inventory plus graph-backed topology answers |\n| `sessions` | AI transcript sessions by project |\n| `search_sessions` | Ranked grouped session search |\n| `abuse` | Abuse hits in AI transcripts with same-session context |\n| `abuse_incidents` | Groups abuse hits into scored incident candidates |\n| `abuse_investigate` | Expands incidents into deterministic evidence bundles |\n| `ai_correlate` | AI transcript anchors cross-referenced against non-AI logs |\n| `usage_blocks` | AI activity in 5-hour UTC windows |\n| `project_context` | Summary for one AI project path |\n| `list_ai_tools` | Distinct AI tools with counts |\n| `list_ai_projects` | Distinct AI projects with counts |\n| `correlate` | Cross-host event correlation in a time window |\n| `stats` | Database statistics and storage health |\n| `status` | Lightweight runtime and DB health |\n| `apps` | Distinct application names with log and host counts |\n| `source_ips` | Distinct source identifiers with hostname breakdown |\n| `timeline` | Bucketed counts over time |\n| `patterns` | Near-duplicate message template clusters |\n| `context` | Surrounding logs around a log id or timestamp |\n| `get` | One log entry by id, including raw frame |\n| `ingest_rate` | Recent ingest throughput and write-block state |\n| `silent_hosts` | Hosts whose last_seen is older than a threshold |\n| `clock_skew` | Per-host received_at minus timestamp distribution |\n| `anomalies` | Recent vs baseline volume/error comparison |\n| `compare` | Side-by-side comparison of two time ranges |\n| `compose_status` | Redacted read-only Compose deployment diagnostics |\n| `compose_doctor` | Strict Compose deployment health diagnostics |\n| `unaddressed_errors` | Repeating unacknowledged error signatures |\n| `ack_error` | Acknowledge an error signature |\n| `unack_error` | Revoke an error acknowledgement |\n| `notifications_recent` | Recent notification firings |\n| `notifications_test` | Send a test notification via Apprise |\n| `similar_incidents` | FTS5 cluster search over historical system logs |\n| `ask_history` | Search AI transcript history with nearby log context |\n| `incident_context` | Full context bundle for a known time window |\n| `graph` | Resolve graph entities, neighborhoods, and evidence-backed explanations |\n| `help` | Markdown reference for all actions |\n\n## Homelab Inventory\n\n`cortex inventory refresh --json` collects native Rust inventory into\n`~/.cortex/inventory` and writes:\n\n- `normalized/homelab.json` — typed `cortex.homelab_inventory.v1` cache\n- `collection-state.json` — per-collector status, warnings, timings, and artifact refs\n- `raw/\u003crun_id\u003e/*.txt` — raw-but-redacted Compose and reverse proxy artifacts\n\n`cortex inventory status --json` reports cache freshness and warnings without\nopening SQLite. The MCP `map` action is read-only: it reads the normalized cache\nand overlays bounded live Cortex host/heartbeat data, but never triggers refresh\nor returns raw artifact bodies.\n\n`map` defaults to the inventory snapshot. Graph-backed modes add a typed\n`graph_answer` envelope with `answer_status`, bounded topology `rows`, safe\nevidence samples, map follow-up queries, and graph proof queries:\n\n```json\n{\"action\":\"map\",\"mode\":\"host_services\",\"host\":\"squirts\"}\n{\"action\":\"map\",\"mode\":\"domain_routes\",\"domain\":\"adguard.tootie.tv\"}\n{\"action\":\"map\",\"mode\":\"service_dependencies\",\"host\":\"squirts\",\"service\":\"swag\"}\n{\"action\":\"map\",\"mode\":\"findings\",\"finding_types\":[\"potential_public_route\",\"risky_mounts\",\"collector_health\"]}\n```\n\n`mode=findings` returns bounded topology risk and hygiene findings derived from\nthe graph plus normalized inventory/cache state. Findings include severity,\nconfidence, reason code, affected entities, safe evidence IDs/excerpts, and\nremediation hints. They deliberately avoid raw config contents, raw artifact or\ncache paths, credential-bearing upstream URLs, and raw collector warning text;\n`potential_public_route` means configured reverse-proxy routing, not proof of\nunauthenticated public internet exposure.\n\nWhen the server is running, inventory refresh also projects topology evidence\ninto the investigation graph. The baseline refresh interval is 5 minutes, with\nlocal Compose/proxy config watchers as lower-latency refresh triggers. Remote\nDocker `events` streams over SSH are opt-in via\n`CORTEX_INVENTORY_REMOTE_DOCKER_EVENTS=true`.\n\nOn first run, before `normalized/homelab.json` exists, `map` and\n`cortex inventory status --json` report `cache_status: \"missing\"`. Run\n`cortex inventory refresh --json` to seed `~/.cortex/inventory` and clear that\nmissing-cache state.\n\n## Prompts\n\nThe MCP server also exposes reusable prompts for common infrastructure debugging\nworkflows: `infra.incident-triage`, `infra.host-health`,\n`infra.service-outage`, `infra.security-auth-review`,\n`infra.noise-reduction`, and `infra.agent-change-correlation`.\n\nFor the prompt catalog and argument reference, see\n[`docs/mcp/PROMPTS.md`](docs/mcp/PROMPTS.md).\n\n### `cortex search`\n\nFull-text search across all syslog messages with optional filters. Uses SQLite FTS5 with porter stemming.\n\n**Parameters**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | no | — | FTS5 search query (see [FTS5 query syntax](#fts5-query-syntax)) |\n| `hostname` | string | no | — | Exact hostname match. Use `cortex` with `action: \"hosts\"` to enumerate. |\n| `source_ip` | string | no | — | Exact source identifier. Syslog entries use the verified network sender address (`IP:port`); OTLP rows use the verified peer IP; Docker ingest stream rows use `docker://host/container/stream`; Docker lifecycle event rows use `docker-event://host/container/action`. |\n| `severity` | string | no | — | One of: `emerg alert crit err warning notice info debug` |\n| `app_name` | string | no | — | Application name, e.g. `sshd`, `dockerd`, `kernel` |\n| `from` | string | no | — | Start of time range (ISO 8601 / RFC 3339, e.g. `2025-01-15T00:00:00Z`) |\n| `to` | string | no | — | End of time range (ISO 8601) |\n| `limit` | integer | no | 100 | Max results (hard cap: 1000) |\n\n**Response**\n\n```json\n{\n  \"count\": 3,\n  \"logs\": [\n    {\n      \"id\": 12345,\n      \"timestamp\": \"2025-01-15T14:30:00Z\",\n      \"hostname\": \"router\",\n      \"facility\": \"kern\",\n      \"severity\": \"err\",\n      \"app_name\": \"kernel\",\n      \"process_id\": null,\n      \"message\": \"kernel panic: unable to mount root\",\n      \"received_at\": \"2025-01-15T14:30:01.123Z\",\n      \"source_ip\": \"10.0.0.1:51234\"\n    }\n  ]\n}\n```\n\n**FTS5 examples**\n\n```\nquery: \"kernel panic\"           # implicit AND: both terms must appear\nquery: \"OOM AND killer\"        # explicit AND\nquery: \"sshd OR pam\"           # boolean OR\nquery: \"failed NOT sudo\"       # boolean NOT\nquery: '\"connection refused\"'  # exact phrase (bypasses stemming)\nquery: \"error*\"                # prefix wildcard\nquery: \"restart*\"              # matches restart, restarted, restarting\n```\n\n### `cortex filter`\n\nStructured filter-only retrieval for correlation workflows. This action rejects `query`; use `search` for FTS5 message-body search.\n\nCommon filters match `search`: `hostname`, `source_ip`, `severity`, `app_name`, `facility`, `exclude_facility`, `process_id`, `from`, `to`, `received_from`, `received_to`, and `limit`.\n\nCorrelation aliases include `source_kind` (`docker-stream`, `docker-event`, `agent-command`, `shell-history`, `transcript`, `claude`, `codex`, `gemini`), plus `tool`, `project`, `session_id`, `container`, `docker_host`, `stream`, and `event_action`.\n\n---\n\n### `cortex tail`\n\nReturn the N most recent log entries. Equivalent to `tail -f` across all hosts.\n\n**Parameters**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `hostname` | string | no | — | Filter to a specific host |\n| `source_ip` | string | no | — | Filter to an exact source identifier. Syslog entries use the verified network sender address (`IP:port`); OTLP rows use the verified peer IP; Docker ingest stream rows use `docker://host/container/stream`; Docker lifecycle event rows use `docker-event://host/container/action`. |\n| `app_name` | string | no | — | Filter to a specific application |\n| `n` | integer | no | 50 | Number of recent entries (hard cap: 500) |\n\n**Response**\n\nSame structure as `cortex search`: `{ \"count\": N, \"logs\": [...] }`.\n\n---\n\n### `cortex errors`\n\nSummarize warnings and errors across all hosts in a time window. Groups by hostname and severity, showing counts. Use this for quick health assessments.\n\n**Parameters**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `from` | string | no | all time | Start of time range (ISO 8601) |\n| `to` | string | no | now | End of time range (ISO 8601) |\n\nSeverities included: `emerg`, `alert`, `crit`, `err`, `warning`.\n\n**Response**\n\n```json\n{\n  \"summary\": [\n    { \"hostname\": \"router\",  \"severity\": \"err\",     \"count\": 42 },\n    { \"hostname\": \"router\",  \"severity\": \"warning\",  \"count\": 17 },\n    { \"hostname\": \"storage\", \"severity\": \"crit\",     \"count\":  3 }\n  ]\n}\n```\n\n---\n\n### `cortex hosts`\n\nList all hosts that have sent syslog messages, with first/last seen timestamps and total log counts.\n\n**Parameters:** none\n\n**Response**\n\n```json\n{\n  \"hosts\": [\n    {\n      \"hostname\": \"router\",\n      \"first_seen\": \"2025-01-01T00:00:00.000Z\",\n      \"last_seen\":  \"2025-01-15T14:30:00.000Z\",\n      \"log_count\":  18432\n    }\n  ]\n}\n```\n\n---\n\n### `cortex sessions`\n\nList AI transcript sessions grouped by project, tool, session, and host.\n\n**Parameters**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `project` | string | no | — | Exact project path, e.g. `/home/jmagar/workspace/cortex` |\n| `tool` | string | no | — | AI tool filter: `claude`, `codex`, or `gemini` |\n| `hostname` | string | no | — | Restrict to one host |\n| `from` | string | no | — | Start of time range (ISO 8601) |\n| `to` | string | no | — | End of time range (ISO 8601) |\n| `limit` | integer | no | 100 | Max sessions (hard cap: 1000) |\n\n**Response**\n\n```json\n{\n  \"count\": 1,\n  \"sessions\": [\n    {\n      \"project\": \"/home/jmagar/workspace/cortex\",\n      \"tool\": \"codex\",\n      \"session_id\": \"019e1506-dc81-7881-9926-4d6d4efda1ac\",\n      \"hostname\": \"dookie\",\n      \"first_seen\": \"2026-05-11T03:13:51.745Z\",\n      \"last_seen\": \"2026-05-11T04:10:00.000Z\",\n      \"event_count\": 42\n    }\n  ]\n}\n```\n\n---\n\n### `cortex correlate`\n\nSearch for related events across multiple hosts within a ±N minute window around a reference timestamp. Useful for debugging cascading failures. Results are grouped by host and ordered by time.\n\n**Parameters**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `reference_time` | string | **yes** | — | Center timestamp (ISO 8601, e.g. `2025-01-15T14:30:00Z`) |\n| `window_minutes` | integer | no | 5 | Minutes before and after `reference_time` (max 60) |\n| `severity_min` | string | no | `warning` | Minimum severity to include. `warning` returns `warning/err/crit/alert/emerg`. `debug` returns everything. |\n| `hostname` | string | no | — | Limit correlation to one host |\n| `source_ip` | string | no | — | Limit correlation to an exact source identifier. Syslog entries use the verified network sender address (`IP:port`); OTLP rows use the verified peer IP; Docker ingest stream rows use `docker://host/container/stream`; Docker lifecycle event rows use `docker-event://host/container/action`. |\n| `query` | string | no | — | FTS5 query to narrow results |\n| `limit` | integer | no | 500 | Max total events (hard cap: 999) |\n\n**Response**\n\n```json\n{\n  \"reference_time\": \"2025-01-15T14:30:00Z\",\n  \"window_minutes\": 5,\n  \"window_from\": \"2025-01-15T14:25:00+00:00\",\n  \"window_to\":   \"2025-01-15T14:35:00+00:00\",\n  \"severity_min\": \"warning\",\n  \"total_events\": 12,\n  \"truncated\": false,\n  \"hosts_count\": 3,\n  \"hosts\": [\n    {\n      \"hostname\": \"router\",\n      \"event_count\": 7,\n      \"events\": [...]\n    }\n  ]\n}\n```\n\n**Note on clock skew:** `cortex correlate` uses the `timestamp` field from the syslog message, which reflects the sending device's clock. If a device clock is skewed, events may fall outside the correlation window. See [Time synchronization](#time-synchronization).\n\n---\n\n### `cortex stats`\n\nReturn database statistics including total logs, total hosts, time range covered, logical and physical DB size, free disk, configured thresholds, current write-block status, and runtime ingest observability.\n\n**Parameters:** none\n\n**Response**\n\n```json\n{\n  \"total_logs\": 284917,\n  \"total_hosts\": 12,\n  \"oldest_log\": \"2024-10-15T00:00:01Z\",\n  \"newest_log\": \"2025-01-15T14:30:00Z\",\n  \"logical_db_size_mb\": \"312.45\",\n  \"physical_db_size_mb\": \"328.00\",\n  \"free_disk_mb\": \"14200.00\",\n  \"max_db_size_mb\": 1024,\n  \"min_free_disk_mb\": 0,\n  \"write_blocked\": false,\n  \"runtime_observability\": {\n    \"syslog_udp_packets_received\": 280000,\n    \"syslog_tcp_connections_active\": 3,\n    \"ingest_entries_enqueued\": 284917,\n    \"ingest_queue_depth\": 0,\n    \"ingest_queue_capacity\": 10000,\n    \"ingest_queue_utilization_pct\": \"0.00\",\n    \"writer_batches_flushed\": 2850,\n    \"writer_logs_written\": 284917,\n    \"writer_flush_failures\": 0,\n    \"writer_logs_retained\": 0,\n    \"writer_logs_discarded\": 0,\n    \"writer_storage_blocked\": false,\n    \"last_ingest_at\": \"2025-01-15T14:30:05.123Z\",\n    \"last_write_at\": \"2025-01-15T14:30:05.400Z\",\n    \"last_error_at\": null\n  },\n  \"otlp\": {\n    \"logs_received\": 42,\n    \"decode_errors\": 0\n  }\n}\n```\n\n`write_blocked: true` means the storage budget is exceeded and new log ingestion is paused. See [Storage budget enforcement](#storage-budget-enforcement).\n\n---\n\n### `cortex status`\n\nReturn lightweight runtime status without the heavier DB statistics query. Use this for dashboards and doctor checks that need current queue depth, backpressure, writer failure/drop state, listener counters, and last activity timestamps.\n\n**Parameters:** none\n\n---\n\n### `cortex help`\n\nReturn markdown documentation for all tools in this toolset.\n\n**Parameters:** none\n\n---\n\nThe sections above document only the most common actions in detail. For the full 45-action surface with per-action parameters, see [`docs/mcp/SCHEMA.md`](docs/mcp/SCHEMA.md) or call `action=help` against a running server.\n\n---\n\n## FTS5 Query Syntax\n\nThe `cortex search` and `cortex correlate` actions use SQLite FTS5 with porter stemming (`tokenize='porter unicode61'`). Valid query forms:\n\n| Syntax | Example | Matches |\n|--------|---------|---------|\n| Single term | `panic` | Any message containing \"panic\" or stemmed variants |\n| Porter stemming | `restart` | restart, restarted, restarting, restarts |\n| AND (default) | `disk error` or `disk AND error` | Both terms present |\n| OR | `sshd OR pam` | Either term present |\n| NOT | `failed NOT sudo` | \"failed\" present, \"sudo\" absent |\n| Phrase | `\"connection refused\"` | Exact phrase in that order |\n| Prefix wildcard | `error*` | Any word starting with \"error\" |\n| Grouped | `(kernel OR oom) AND panic` | Grouped boolean logic |\n\n**Limits:** max 512 characters, max 16 whitespace-separated terms.\n\n**Porter stemming** means `connect`, `connected`, `connecting`, and `connection` all match the query `connect`. Phrase queries (`\"...\"`) bypass stemming and require exact token order.\n\n---\n\n## Log Schema\n\nEach stored log entry has these fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | integer | Auto-increment primary key |\n| `timestamp` | text | Message timestamp (RFC 3339, UTC). From the syslog message header. |\n| `hostname` | text | Hostname from the syslog message (user-controlled, not verified) |\n| `facility` | text\\|null | Syslog facility name (see facilities below) |\n| `severity` | text | Syslog severity level name |\n| `app_name` | text\\|null | Application/process name from the syslog message |\n| `process_id` | text\\|null | PID from the syslog message |\n| `message` | text | Log message body (FTS5-indexed) |\n| `received_at` | text | Server-side receipt timestamp (RFC 3339, UTC). Used for retention. |\n| `source_ip` | text | Source identifier. Syslog entries use the exact network sender address (`IP:port`) captured from the packet/connection peer. OTLP rows use the peer IP without the ephemeral source port. Docker ingest stream rows use `docker://host/container/stream`; Docker lifecycle event rows use `docker-event://host/container/action`. |\n| `ai_tool` | text\\|null | AI tool name (e.g. `claude`, `codex`) |\n| `ai_project` | text\\|null | AI project path |\n| `ai_session_id` | text\\|null | AI session unique identifier |\n| `ai_transcript_path` | text\\|null | Full path to the source transcript file |\n| `metadata_json` | text\\|null | Source-specific JSON metadata. Syslog rows include parser/source provenance; OTLP rows include resource/log attributes plus trace/span ids; Docker rows include host/container/image/compose/action details; transcript rows include source kind, file path, line number, record key, and scrub status. |\n\n### AI transcript indexing\n\n`cortex ai index` scans the default local transcript roots\n`~/.claude/projects` and `~/.codex/sessions`; `cortex ai index --path PATH`\ncan scan a known transcript directory or one explicit `.jsonl` file, and\n`cortex ai add --file FILE` imports one file. Recursive scans are limited to\n`~/.claude/projects`, `~/.codex/sessions`, or their children; broad roots such\nas `/`, `$HOME`, and the current repo root are rejected before walking. The\nscanner skips symlinks, counts unsupported non-`.jsonl` files without parsing\nthem, and streams transcript files line-by-line in bounded SQLite chunks. Use\n`--force` to reimport a transcript path from scratch after parser changes,\n`--since RFC3339` to scan only recently modified files, and\n`cortex ai checkpoints --errors` plus `cortex ai errors` to inspect structured\nscanner failures.\n\nFor real-time local Claude/Codex transcript ingestion, install the host-local\nwatch service:\n\n```bash\ncortex setup ai-watch-service install\ncortex setup ai-watch-service check\ncortex setup ai-watch-service remove\n```\n\nThe watcher runs outside Docker because it needs host access to\n`~/.claude/projects` and `~/.codex/sessions`. It writes to the configured live\nSQLite DB and delegates every stable changed `.jsonl` file to the same scanner\npath used by `cortex ai add --file FILE`. Installing the watcher disables the\nolder polling timer so both helpers do not scan the same files.\n\nThe optional polling fallback is still available:\n\n```bash\ncortex setup ai-index-timer install\ncortex setup ai-index-timer check\ncortex setup ai-index-timer remove\n```\n\nBoth helpers are deliberately not inside the Docker container. Docker Compose\nowns only the server/query runtime.\n\nImported AI transcript messages are scrubbed for known credential/token patterns\nbefore storage and FTS indexing. The rows still live in the main `logs` table,\nso raw actions such as `search`, `tail`, `context`, and `get` can return\nscrubbed transcript text and local `ai_transcript_path` values within seconds of\nthe transcript write. Scrubbing is best-effort, not a compliance boundary.\nIf storage guardrails cannot recover enough space, indexing fails before\ncommitting additional chunks.\n\n### Shell and agent command history\n\nLocal command history can be correlated with system logs without introducing a\nseparate table:\n\n```bash\ncortex shell index --path ~/.zsh_history --shell zsh\ncortex setup agent-command install\nexport CLAUDE_CODE_SHELL_PREFIX=\"$HOME/.local/bin/cortex-agent-command-wrapper\"\ncortex agent-command ingest-spool --path ~/.local/state/cortex/agent-command.jsonl\n```\n\n`cortex shell index` imports zsh extended history lines with timestamps and\ndurations as `source_kind=\"shell-history\"` rows. Plain untimestamped history is\nskipped because it cannot support time-window correlation.\n\n`cortex setup agent-command install` writes a small local wrapper for Claude\nCode's `CLAUDE_CODE_SHELL_PREFIX`. Claude Code invokes that prefix for spawned\nshell commands, including Bash tool calls, hook commands, and stdio MCP server\nstartup commands. The wrapper preserves stdio and exit code, appends one\nscrubbed JSONL record under `~/.local/state/cortex/`, and\n`cortex agent-command ingest-spool` imports those records as\n`source_kind=\"agent-command\"` rows, then truncates the locked spool after a\nsuccessful import so repeated runs only process new commands. The wrapper\nrecords command text, cwd, duration, exit status, agent name, PID, host/user, and\n`CLAUDE_CODE_SESSION_ID` when present. It does not capture environment\nvariables, stdout, or stderr by default.\n\nBoth command import paths run the AI scrubber plus command-specific redaction\nfor token flags, sensitive assignments, Authorization headers, URL userinfo,\n`curl -u`, and private-key blocks before storage. Scrubbing is best-effort, not\na compliance boundary.\n\n**Important:** `hostname` is taken from the syslog message body, which any LAN device can set to an arbitrary value over UDP. For syslog entries, `source_ip` is the only trustworthy network identifier. For Docker ingest entries, `source_ip` identifies the configured Docker ingest host/container/stream and should be trusted only as far as the configured docker-socket-proxy endpoint and network path are trusted. `metadata_json` preserves source-specific context for debugging and correlation, but it is not an authorization boundary. Retention cutoffs use `received_at` (server clock) so that devices with misconfigured clocks cannot cause premature or indefinite log retention.\n\n### Severity levels\n\nOrdered from most to least severe:\n\n| Level | Numeric | Meaning |\n|-------|---------|---------|\n| `emerg` | 0 | System is unusable |\n| `alert` | 1 | Action must be taken immediately |\n| `crit` | 2 | Critical conditions |\n| `err` | 3 | Error conditions |\n| `warning` | 4 | Warning conditions |\n| `notice` | 5 | Normal but significant condition |\n| `info` | 6 | Informational messages |\n| `debug` | 7 | Debug-level messages |\n\n### Facilities\n\n`kern`, `user`, `mail`, `daemon`, `auth`, `cortex`, `lpr`, `news`, `uucp`, `cron`, `authpriv`, `ftp`, `ntp`, `audit`, `alert`, `clock`, `local0`–`local7`.\n\n---\n\n## Installation\n\n### One-line installer\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/jmagar/cortex/main/install.sh | sh\n```\n\nThe installer puts the host `cortex` binary in `~/.local/bin` and then runs\n`cortex setup`. Setup is idempotent and owns the shared host layout:\n\n- `~/.cortex/.env` — secrets, ports, Compose interpolation, runtime values\n- `~/.cortex/compose/docker-compose.yml` — Docker Compose deployment assets\n- `~/.cortex/data/cortex.db` — SQLite database and WAL/SHM sidecars\n\nSetup writes the compose project name used by the shared host deployment.\nExisting installations may still use the legacy `syslog-jmagar-lab` project\nname for container-label compatibility; prefer `cortex compose ...` commands\nbecause they resolve the live owner before mutating the stack.\n\nUseful installer controls:\n\n```bash\nCORTEX_INSTALL_DRY_RUN=1 ./install.sh\nCORTEX_INSTALL_PREFIX=/opt/cortex ./install.sh\nCORTEX_VERSION=\u003cversion\u003e ./install.sh\nCORTEX_INSTALL_SKIP_SETUP=1 ./install.sh\n```\n\nUseful setup commands:\n\n```bash\ncortex setup          # first-run or normal repair\ncortex setup check    # inspect only; does not mutate files or start services\ncortex setup repair   # repair env/assets and restart the Docker stack\ncortex deploy preflight       # clearer alias for setup check\ncortex deploy local           # clearer local Compose deploy/reconcile command\ncortex deploy local --dry-run # run the deploy preflight without mutating Docker\ncortex setup ai-watch-service install  # host-local real-time transcript watcher\ncortex doctor binary  # check host/container binary freshness\n```\n\n### Claude Code plugin (recommended)\n\nInstall as a Claude Code plugin. The plugin handles deployment automatically — you choose between server mode (this machine hosts the syslog receiver + MCP server) and client mode (connect to a remote server).\n\n**Prompted at install time** (via `userConfig`):\n\n| Field | Required | Default | Notes |\n|-------|----------|---------|-------|\n| `is_server` | yes | `true` | Server mode hosts the receiver; client mode connects to a remote server |\n| `server_url` | no | `http://localhost:3100` | Server mode: leave default. Client mode: remote host URL (e.g. `http://shart:3100`) |\n| `api_token` | yes | — | Bearer token used by the plugin MCP client. Server mode: this becomes the token the server enforces unless `no_auth=true`. Client mode: token from the server admin. Stored in the system keychain. |\n| `syslog_host` / `syslog_port` | no | `0.0.0.0` / `1514` | Syslog listener bind (server mode) |\n| `mcp_host` / `mcp_port` | no | `0.0.0.0` / `3100` | MCP HTTP server bind (server mode) |\n| `data_dir` | no | `~/.cortex/data` | Optional SQLite directory override; default shared setup data persists outside plugin cache |\n| `max_db_size_mb` | no | `8192` | DB size cap; oldest logs deleted when exceeded |\n| `retention_days` | no | `90` | `0` = keep forever |\n| `batch_size` | no | `100` | Number of parsed messages per SQLite batch |\n| `write_channel_capacity` | no | `10000` | Internal parsed-message queue capacity before listener backpressure |\n| `docker_ingest_enabled` | no | `false` | Pull container logs from remote `docker-socket-proxy` endpoints |\n| `fleet_hosts` | no | — | SSH aliases of fleet hosts. Used for Docker ingest (when enabled, each becomes `http://\u003calias\u003e:2375`) and the `cortex-deploy-dropins` skill |\n\n**SessionStart hook automation** (in server mode):\n\n- Ensures the host `cortex` binary is on `PATH`; the installer defaults to `~/.local/bin`\n- Exports plugin userConfig as `CORTEX_*` / `CORTEX_*` environment values\n- Runs `cortex setup repair`, the same setup path used by the one-line installer\n- Repairs shared assets under `~/.cortex` and removes stale user-level `cortex.service` units/drop-ins left by older plugin versions\n- All idempotent — safe to run on every session\n\n**Bundled skills** (all 9, from `plugins/cortex/skills/`):\n\n- `cortex` — primary log-intelligence skill: search, tail, errors, correlate, stats, and the rest of the MCP action surface\n- `cortex-dr` — health check covering MCP, service status, syslog port, fleet drop-ins, and live log flow; tails service logs on failure\n- `cortex-deploy-dropins` — SSH-based one-shot rsyslog drop-in deployment to every host in `fleet_hosts`\n- `cortex-frustration-assessment` — analyze an `abuse_investigate` evidence bundle into a frustration/abuse report\n- `cortex-logs` — Docker Compose service log tailing (the service's own stdout/stderr, not client syslog)\n- `cortex-redeploy` — re-run plugin setup after config or plugin changes\n- `cortex-report` — time-bounded homelab health/log-analysis markdown reports\n- `cortex-troubleshoot` — diagnose connection failures, missing logs, unhealthy containers, and restart loops\n- `cortex-version-check` — check whether the running Docker container matches the local Compose image; add `--pull` to pull first, otherwise checks only the local image cache\n\nThe plugin deploys the server with Docker Compose through the same `cortex setup`\npath as the one-line installer. You can still build and run the binary locally\nfor development, but automated deployment is Compose-only.\n\n`cortex deploy local` is the operator-facing name for the same local\nCompose-backed reconcile path. It exists so deploy workflows do not need to call\na command named `setup repair` directly.\n\n### Docker\n\n```bash\ngit clone https://github.com/jmagar/cortex\ncd cortex\ncp .env.example .env\n# Edit .env — set CORTEX_TOKEN at minimum\ndocker compose up -d\n```\n\nThe container binds:\n- `UDP :1514` and `TCP :1514` for syslog ingestion (published on all interfaces — senders must reach it)\n- `TCP :3100` for the MCP HTTP API, published on `127.0.0.1` only by default. Set `CORTEX_MCP_BIND=0.0.0.0` (plus `CORTEX_TOKEN`) to expose it; containers on the same Docker network (e.g. the Labby gateway) reach `http://cortex:3100` either way.\n\n### Local build\n\nRequires Rust 1.86+.\n\n```bash\ncargo build --release\n./target/release/cortex serve mcp\n```\n\n---\n\n## Authentication\n\ncortex supports two auth modes, selectable via `CORTEX_AUTH_MODE`.\n\n**Bearer-only (default)** — set `CORTEX_TOKEN` and all `/mcp` requests must present that token as `Authorization: Bearer \u003ctoken\u003e`. No OAuth routes are mounted.\n\n**Loopback no-auth** — set `CORTEX_NO_AUTH=true` only for local development on loopback binds.\n\n**Gateway-protected no-auth (TrustedGatewayUnscoped)** — on non-loopback binds, set both `CORTEX_NO_AUTH=true` and `CORTEX_TRUSTED_GATEWAY_NO_AUTH=true` only when an upstream gateway or reverse proxy enforces auth before traffic reaches cortex. This intentionally disables service-local MCP auth **and the read/admin scope gates** — every caller can run the write actions `ack_error`, `unack_error`, and `notifications_test`. **Never combine this mode with host-published ports**; keep `CORTEX_MCP_BIND=127.0.0.1` (the default) so only the gateway's Docker network path reaches cortex. See [docs/SECURITY.md](docs/SECURITY.md).\n\n**OAuth (Google)** — set `CORTEX_AUTH_MODE=oauth`, the OAuth provider env vars, and an allowlisted admin email. The server issues RS256 JWTs after users authenticate via Google. Bearer tokens and OAuth JWTs can coexist (OAuth mode disables the static token by default; set `CORTEX_AUTH_DISABLE_STATIC_TOKEN_WITH_OAUTH=false` or `disable_static_token_with_oauth = false` in `config.toml` for break-glass access).\n\nBoth modes leave `/health` unauthenticated so health probes always work.\n\nSee [docs/OAUTH.md](docs/OAUTH.md) for full setup instructions, architecture diagram, and operator FAQ.\n\n---\n\n## Configuration\n\nConfiguration is loaded from three sources in priority order (highest wins):\n\n1. Environment variables\n2. `config.toml` (if present)\n3. Built-in defaults\n\n### Environment variables\n\n#### MCP server\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CORTEX_TOKEN` | no | — | Bearer token for `/mcp`. Omit to disable auth (loopback binds only). Required when exposing port 3100 beyond loopback. |\n| `CORTEX_HOST` | no | `127.0.0.1` | Bind host for the MCP HTTP server (loopback by default) |\n| `CORTEX_PORT` | no | `3100` | Bind port for the MCP HTTP server |\n| `CORTEX_MCP_BIND` | no | `127.0.0.1` | Docker Compose only: host interface port 3100 is published on. Set `0.0.0.0` together with `CORTEX_TOKEN` to expose it. |\n| `CORTEX_ALLOWED_HOSTS` | no | — | Extra comma-separated Host header values accepted by RMCP Host validation |\n| `CORTEX_ALLOWED_ORIGINS` | no | — | Extra comma-separated browser origins accepted by RMCP Origin validation |\n\n#### Non-MCP API\n\nThe plain JSON API is always mounted under `/api/*` on the same HTTP listener and requires its own bearer token — the server fails to start (on the server path) without it. `cortex setup repair` generates one if missing.\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CORTEX_API_TOKEN` | yes | — | Bearer token for `/api/*` routes |\n\n#### Syslog listener\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CORTEX_RECEIVER_HOST` | no | `0.0.0.0` | Bind host for UDP + TCP syslog listeners |\n| `CORTEX_RECEIVER_PORT` | no | `1514` | Bind port for UDP + TCP syslog listeners |\n| `CORTEX_RECEIVER_HOST_PORT` | no | `1514` | Docker Compose host port published to container port `1514` |\n| `CORTEX_MAX_MESSAGE_SIZE` | no | `8192` | Max bytes per UDP datagram or newline-delimited TCP frame. Oversized newline-delimited TCP frames are dropped and the connection stays open; oversized unterminated frames are dropped and the connection is closed. |\n| `CORTEX_MAX_TCP_CONNECTIONS` | no | `512` | Maximum simultaneous TCP syslog connections |\n| `CORTEX_TCP_IDLE_TIMEOUT_SECS` | no | `300` | Idle timeout per TCP read before closing inactive connections |\n| `CORTEX_BATCH_SIZE` | no | `100` | Number of messages per batch write |\n| `CORTEX_FLUSH_INTERVAL` | no | `500` | Batch flush interval in milliseconds |\n| `CORTEX_WRITE_CHANNEL_CAPACITY` | no | `10000` | Internal parsed-message queue capacity |\n\n#### Docker socket-proxy ingest\n\nOptional pull-based Docker log ingestion keeps each remote host on its normal Docker logging driver and has cortex read container stdout/stderr through read-only `docker-socket-proxy` endpoints. This avoids configuring Docker's daemon-level syslog driver and does not block container startup when cortex is down.\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CORTEX_DOCKER_INGEST_ENABLED` | no | `false` | Enable remote Docker log ingestion |\n| `CORTEX_DOCKER_HOSTS` | one of the two | — | Comma-separated hostnames; each becomes `http://\u003cname\u003e:2375` with `allow_insecure_http = true`. Takes priority over `CORTEX_DOCKER_HOSTS_FILE`. |\n| `CORTEX_DOCKER_HOSTS_FILE` | one of the two | — | Path to a TOML file with a `[[hosts]]` array (use when you need per-host `base_url` or TLS). If the file does not exist, a warning is logged and no hosts are loaded — the container will not crash. Mount the file into the container (e.g. under `/cortex-home` via `CORTEX_HOME_VOLUME`). |\n| `CORTEX_DOCKER_RECONNECT_INITIAL_MS` | no | `1000` | Initial reconnect delay after host stream failure |\n| `CORTEX_DOCKER_RECONNECT_MAX_MS` | no | `30000` | Maximum reconnect delay after repeated failures |\n\nThe hosts file uses this shape:\n\n```toml\n[[hosts]]\nname = \"edge-host-a\"\nbase_url = \"http://edge-host-a:2375\"\nallow_insecure_http = true\n\n[[hosts]]\nname = \"app-host-b\"\nbase_url = \"http://app-host-b:2375\"\nallow_insecure_http = true\n```\n\nThe docker-socket-proxy side only needs read access to containers, events, ping, and version endpoints: `CONTAINERS=1`, `EVENTS=1`, `PING=1`, `VERSION=1`, `POST=0`. `CONTAINERS=1` exposes the broader read-only Docker container API to anything that can reach the proxy, so bind it only on a trusted private network, firewall it to cortex, or put it behind authenticated TLS. Plain `http://` endpoints require `allow_insecure_http = true` in the hosts file so that this trust decision is explicit.\n\nDocker ingest is intentionally not part of the default smoke test because it needs a live docker-socket-proxy-compatible endpoint and container log stream. For integration testing, run cortex with `CORTEX_DOCKER_INGEST_ENABLED=true` against a disposable docker-socket-proxy or mocked Docker HTTP fixture, emit a unique line from a short-lived container, then verify it with `cortex search` or `mcporter call ... action=search`. Container stdout/stderr rows use `source_ip=docker://\u003chost\u003e/\u003ccontainer\u003e/\u003cstream\u003e`. Container lifecycle rows for actions such as `create`, `start`, `restart`, `die`, `stop`, `destroy`, `rename`, `oom`, and `health_status:*` use `source_ip=docker-event://\u003chost\u003e/\u003ccontainer\u003e/\u003csanitized-action\u003e`, `facility=docker`, and preserve the raw Docker event JSON.\n\n#### Storage\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CORTEX_DB_PATH` | no | `/data/cortex.db` | SQLite database path |\n| `CORTEX_POOL_SIZE` | no | `4` | SQLite connection pool size. MCP/REST reads get `pool_size - 1` permits; one connection is reserved for the ingest writer. |\n| `CORTEX_RETENTION_DAYS` | no | `90` | Days to retain logs. `0` = keep forever. Purge runs hourly; err+ severities are exempt (see [Retention Policy](#retention-policy)). |\n| `CORTEX_MAX_DB_SIZE_MB` | no | `1024` | Logical DB size trigger: breach deletes oldest logs. `0` = disabled. |\n| `CORTEX_RECOVERY_DB_SIZE_MB` | no | `900` | Cleanup target after DB size trigger. Must be less than max. |\n| `CORTEX_MIN_FREE_DISK_MB` | no | `0` | Free disk threshold. **Disabled by default.** A breach blocks writes (it does not delete data). |\n| `CORTEX_RECOVERY_FREE_DISK_MB` | no | `0` | Hysteresis target before writes resume after a free-disk breach. Must be greater than min when enabled. |\n| `CORTEX_CLEANUP_INTERVAL_SECS` | no | `60` | Storage budget enforcement interval. Minimum `5`. |\n| `CORTEX_CLEANUP_CHUNK_SIZE` | no | `2000` | Rows deleted per enforcement chunk |\n| `CORTEX_ERR_FLOOR_WINDOW_HOURS` | no | `24` | err+ rows received within this window are protected from disk-pressure deletion. `0` = disable the floor. |\n| `CORTEX_ERR_FLOOR_PER_SOURCE_CAP` | no | `10000` | Max protected err+ rows per source IP within the window. `0` = disable the floor. |\n\n#### Container\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CORTEX_UID` | no | `1000` | Container user ID for data volume ownership |\n| `CORTEX_GID` | no | `1000` | Container group ID for data volume ownership |\n| `CORTEX_DATA_VOLUME` | no | `cortex-data` | Docker volume name or bind-mount path |\n| `CORTEX_HOME_VOLUME` | no | `~/.cortex` | Shared cortex home (inventory cache, setup env) mounted at `/cortex-home` |\n| `CORTEX_SSH_VOLUME` | no | `~/.cortex/ssh` | Dedicated SSH key dir mounted read-only at `/home/cortex/.ssh`. Never point at `~/.ssh` — see Security Model |\n| `DOCKER_NETWORK` | no | `cortex` | Docker network name (must exist) |\n| `RUST_LOG` | no | `info` | Log level (`trace`, `debug`, `info`, `warn`, `error`) |\n| `TZ` | no | `UTC` | Container timezone |\n\n### config.toml\n\nPlace `config.toml` next to the binary (or in the working directory). Environment variables override values set here.\n\n```toml\n[syslog]\nhost = \"0.0.0.0\"\nport = 1514\nmax_message_size = 8192\nmax_tcp_connections = 512\ntcp_idle_timeout_secs = 300\n\n[storage]\ndb_path = \"data/cortex.db\"\npool_size = 4\nretention_days = 90   # 0 = keep forever\nwal_mode = true\nmax_db_size_mb = 1024\nrecovery_db_size_mb = 900\nmin_free_disk_mb = 0      # 0 = free-disk guard disabled (default)\nrecovery_free_disk_mb = 0\ncleanup_interval_secs = 60\n\n[mcp]\nhost = \"127.0.0.1\"\nport = 3100\nserver_name = \"cortex\"\n# api_token = \"your-secret-token\"\n\n[docker_ingest]\nenabled = false\nreconnect_initial_ms = 1000\nreconnect_max_ms = 30000\n\n[[docker_ingest.hosts]]\nname = \"edge-host-a\"\nbase_url = \"http://edge-host-a:2375\"\nallow_insecure_http = true\n```\n\n---\n\n## Security Model\n\n### Syslog ingest is unauthenticated by design\n\nThe UDP and TCP syslog listeners (port 1514) accept log frames from **any reachable host** with no authentication. This matches the RFC 3164/5424 syslog protocol design and is intentional for homelab deployments where the network perimeter is the trust boundary.\n\nConsequences:\n- **`hostname` in stored records is caller-controlled** for vendor formats (CEF/UniFi). Any host on the network can claim any hostname. Use `source_ip` for trusted origin identification.\n- **Log injection is possible** from any host that can reach port 1514. Do not use cortex for security-critical audit trails without network-level access controls.\n- **Retention exemption**: `severity=err` and above are excluded from time-based purge. A host flooding with high-severity frames can exhaust disk space.\n\n**Mitigations**: Bind the syslog port to a specific interface, use a firewall rule to restrict sources, or set `CORTEX_ALLOWED_SOURCE_CIDRS` (comma-separated CIDR list) to allowlist sending hosts.\n\n### MCP API authentication\n\nThe MCP query API (port 3100, default loopback) supports two auth modes:\n\n| Mode | Config | Effect |\n|------|--------|--------|\n| Bearer token | `CORTEX_TOKEN=\u003ctoken\u003e` | Static token grants `cortex:read` by default; set `CORTEX_STATIC_TOKEN_ADMIN=true` to also grant `cortex:admin` |\n| Google OAuth | `CORTEX_AUTH_MODE=oauth` | OAuth users authenticated via `CORTEX_AUTH_ADMIN_EMAIL` |\n\n**Important**: Admin actions such as `ack_error`, `unack_error`, and `notifications_test` require `cortex:admin`. Static bearer tokens are read-only unless `CORTEX_STATIC_TOKEN_ADMIN=true` is explicitly set.\n\nThe MCP port defaults to `127.0.0.1:3100` (loopback only), and the Docker Compose files publish container port 3100 on `127.0.0.1` by default (`CORTEX_MCP_BIND` overrides the host interface). The Labby gateway reaches cortex over the Docker network at `http://cortex:3100` regardless of the host publish address. To expose port 3100 on a network interface, set `CORTEX_MCP_BIND=0.0.0.0` (Compose) or `CORTEX_HOST=0.0.0.0` (bare binary), **set `CORTEX_TOKEN`**, and put a TLS-terminating reverse proxy in front of it.\n\n### SSH key exposure (inventory mount)\n\nThe Compose files mount an SSH key directory read-only at `/home/cortex/.ssh` for the fleet inventory collectors. The default source is a **dedicated key dir, `~/.cortex/ssh`** (override with `CORTEX_SSH_VOLUME`). **Never point `CORTEX_SSH_VOLUME` at `~/.ssh`** — mounting your personal SSH directory gives the container every identity you own and creates a lateral-movement path across the fleet.\n\nProvision a least-privilege deploy key instead: generate a dedicated keypair in `~/.cortex/ssh`, write a minimal `config` listing only the hosts cortex should collect from, curate a `known_hosts` file (`ssh-keyscan`), and restrict the key on each fleet host with a `restrict,command=\"...\"` `authorized_keys` entry under a low-privilege user. Full walkthrough: [docs/SECURITY.md](docs/SECURITY.md) \"SSH Key Exposure\".\n\n---\n\n## Command modes\n\n```bash\ncortex serve mcp  # UDP/TCP syslog ingest plus HTTP MCP on /mcp\ncortex mcp        # query-only MCP stdio transport\ncortex setup      # install/repair shared ~/.cortex Docker Compose setup\ncortex deploy preflight  # check deploy prerequisites without mutating Docker\ncortex deploy local      # reconcile local Compose deployment\ncortex stats      # query the SQLite DB directly from the CLI\ncortex db status  # inspect SQLite maintenance state\ncortex db backup  # create a WAL-safe SQLite backup\ncortex compose doctor          # diagnose live Compose/listener ownership\ncortex compose status --json   # inspect canonical cortex container/project\n```\n\nBoth modes use the same config and environment variable loader. `cortex mcp` is for local child-process MCP clients that can read `CORTEX_DB_PATH`; it does not bind network ports or run retention/storage cleanup jobs.\n\nThe direct CLI uses the same shared service layer as the MCP tool, so results and validation match the MCP actions without needing an MCP client:\n\n```bash\ncortex search 'error AND nginx' --hostname proxy --limit 10\ncortex tail -n 20 --app-name kernel\ncortex errors --from 2026-01-01T00:00:00Z\ncortex hosts\ncortex correlate --reference-time 2026-01-01T12:00:00Z --window-minutes 10 --severity-min warning\ncortex entity host tootie\ncortex graph around host tootie --limit 25\ncortex graph explain host tootie --depth 2\ncortex stats --json\ncortex db integrity            # run PRAGMA integrity_check\ncortex db checkpoint --mode full\ncortex db vacuum --pages 1000\ncortex compose pull            # pull image for resolved Compose project\ncortex compose up              # run docker compose up -d for resolved service\ncortex compose restart         # restart resolved service\ncortex compose logs --tail 20  # bounded compose logs\n\n# Surface parity (2026-05-22) — each is also a REST GET on /api/\u003ccommand\u003e\ncortex silent-hosts --silent-minutes 60\ncortex clock-skew   --since 2026-05-20T00:00:00Z\ncortex anomalies    --recent-minutes 30 --baseline-minutes 720\ncortex compare      --a-from 2026-05-20T00:00:00Z --a-to 2026-05-20T23:59:59Z \\\n                    --b-from 2026-05-21T00:00:00Z --b-to 2026-05-21T23:59:59Z\ncortex apps         --hostname dookie --limit 50\n```\n\n### REST endpoints (2026-05-22 surface parity)\n\nThe 12 new routes mirror existing MCP actions one-for-one. All require the\n`CORTEX_API_TOKEN` bearer; AI endpoints with `terms[]=` parameters are served\nvia `serde_qs` to handle repeated keys.\n\n```\nGET  /api/silent-hosts?silent_minutes=60\nGET  /api/clock-skew?since=\u003cRFC3339\u003e\nGET  /api/anomalies?recent_minutes=15\u0026baseline_minutes=360\nGET  /api/compare?a_from=...\u0026a_to=...\u0026b_from=...\u0026b_to=...\nGET  /api/apps?hostname=\u0026from=\u0026to=\u0026limit=\u0026offset=\nGET  /api/similar-incidents?query=...\u0026window_minutes=30\nGET  /api/incident-context?from=...\u0026to=...\nGET  /api/ai/ask-history?query=...\nGET  /api/ai/incidents?terms[]=foo\u0026terms[]=bar\nGET  /api/ai/investigate?correlation_window_minutes=30\nGET  /api/graph/entity?entity_type=host\u0026key=tootie\nGET  /api/graph/around?entity_type=host\u0026key=tootie\u0026depth=1\nGET  /api/graph/explain?entity_type=host\u0026key=tootie\u0026depth=2\nGET  /api/compose/status\nGET  /api/compose/doctor\n```\n\n`/api/compose/status` is a redacted read-only projection and can report\n`runtime_state=\"docker_unavailable\"` when Docker inspection is unavailable from\ninside the container. `/api/compose/doctor` is stricter: unready Docker,\nownership, or runtime states return HTTP 503 with the same structured projection.\n\n`cortex compose` commands resolve the live Compose owner before mutation. They refuse ambiguous cwd fallback, stale Compose labels, listener conflicts, and destructive `down` without `--yes`.\n\nSee [docs/CLI.md](docs/CLI.md) for the full direct CLI reference, including flags, JSON output, and how CLI commands map to MCP actions.\n\n---\n\n## Syslog Forwarder Setup\n\nThe server listens on port `1514` by default. Configure senders to forward to this port. If a device cannot use a non-privileged port, see [Exposing port 514](#exposing-port-514).\n\n### rsyslog\n\nCreate `/etc/rsyslog.d/99-remote.conf` on each host:\n\n```conf\n# TCP (reliable, recommended for persistent connections)\n*.* @@CORTEX_SERVER:1514\n\n# UDP (lower overhead, no delivery guarantee)\n# *.* @CORTEX_SERVER:1514\n```\n\nRestart: `sudo systemctl restart rsyslog`\n\nFor hosts running pure journald without rsyslog, first enable forwarding in `/etc/systemd/journald.conf`:\n\n```ini\n[Journal]\nForwardToSyslog=yes\n```\n\nThen install and configure rsyslog as above.\n\n### syslog-ng\n\nAdd to `/etc/syslog-ng/conf.d/remote.conf`:\n\n```conf\ndestination d_remote_tcp {\n    network(\"CORTEX_SERVER\"\n        port(1514)\n        transport(\"tcp\")\n    );\n};\n\ndestination d_remote_udp {\n    network(\"CORTEX_SERVER\"\n        port(1514)\n        transport(\"udp\")\n    );\n};\n\nlog {\n    source(s_src);\n    destination(d_remote_tcp);\n};\n```\n\nRestart: `sudo systemctl restart syslog-ng`\n\n### WSL2 (systemd enabled)\n\nEnable systemd in `/etc/wsl.conf`:\n\n```ini\n[boot]\nsystemd=true\n```\n\nInstall rsyslog and use the rsyslog config above. Use the Tailscale IP of the cortex host — WSL has its own network namespace and cannot reach the Docker host IP directly.\n\n### UniFi Cloud Gateway\n\nOption A — via SSH:\n\n```bash\nssh admin@\u003cgateway-ip\u003e\n# Create /etc/rsyslog.d/remote.conf (persists on newer firmware):\necho \"*.* @CORTEX_SERVER:1514\" | sudo tee /etc/rsyslog.d/remote.conf\nsudo systemctl restart rsyslog\n```\n\nOption B — via UI (survives firmware updates):\n\nSettings → System → Advanced → Remote Syslog Server. Set host and port `1514`.\n\n### Routers and appliances (UDP-only devices)\n\nSet the syslog server address to your `CORTEX_SERVER` and port to `1514` in the device's syslog settings. Most consumer routers and network appliances expose this under Diagnostics or Logging settings.\n\n### Exposing port 514\n\nSyslog's privileged port 514 requires root or `CAP_NET_BIND_SERVICE`. The recommended approach is to redirect at the host with iptables:\n\n```bash\n# Redirect UDP and TCP 514 → 1514 on the host\nsudo iptables -t nat -A PREROUTING -p udp --dport 514 -j REDIRECT --to-port 1514\nsudo iptables -t nat -A PREROUTING -p tcp --dport 514 -j REDIRECT --to-port 1514\n\n# Persist across reboots (Debian/Ubuntu)\nsudo apt install iptables-persistent\nsudo netfilter-persistent save\n```\n\nFor Docker Compose, set `CORTEX_RECEIVER_HOST_PORT=514` to publish host port `514` while the container keeps binding unprivileged port `1514`. On Unraid, map host port `514` to container port `1514` for both UDP and TCP in the Docker template (`514:1514/udp` and `514:1514/tcp`).\n\n### Firewall rules\n\nOpen the syslog port on the Docker host firewall:\n\n```bash\n# ufw\nsudo ufw allow 1514/udp\nsudo ufw allow 1514/tcp\n\n# firewalld\nsudo firewall-cmd --permanent --add-port=1514/udp\nsudo firewall-cmd --permanent --add-port=1514/tcp\nsudo firewall-cmd --reload\n```\n\n---\n\n## Heartbeats\n\nThe heartbeat agent is a small host-local loop (the same `cortex` binary) that collects bounded system state (load, memory, disk, top processes) and POSTs it to the server's `POST /v1/heartbeats` endpoint on port 3100 every 30 seconds. Heartbeat rows feed the `host_state`, `fleet_state`, and `correlate_state` MCP actions and are retained for 14 days.\n\nInstall it as a user systemd service on each fleet host:\n\n```bash\ncortex setup heartbeat-agent install   # write + enable the systemd unit\ncortex setup heartbeat-agent check     # inspect unit/env state\ncortex setup heartbeat-agent remove    # remove the unit\ncortex heartbeat agent --once --emit   # one-shot foreground run for debugging\n```\n\nConfiguration:\n\n- `CORTEX_HEARTBEAT_TARGET` — server base URL (default `http://127.0.0.1:3100`; falls back to `CORTEX_URL`)\n- `CORTEX_HEARTBEAT_TOKEN` — bearer token sent with each POST (falls back to `CORTEX_TOKEN`)\n\nWhen the server has `CORTEX_TOKEN` set, heartbeat POSTs must carry that token; on an unauthenticated loopback-only server no token is needed.\n\n---\n\n## OTLP Ingest\n\nThe shared HTTP listener on port 3100 also accepts OpenTelemetry logs at `POST /v1/logs` (logs only — `/v1/metrics` and `/v1/traces` return 404). The endpoint decodes **binary protobuf** (`ExportLogsServiceRequest`; OTLP/JSON is not supported) and enforces a **4 MiB** request body limit (413 responses include `Retry-After: 86400`).\n\nAuth matches MCP: when `CORTEX_TOKEN` is set, requests need `Authorization: Bearer \u003ctoken\u003e`. Exposing `/v1/logs` on a non-loopback bind without a static bearer token is blocked at startup (OAuth JWTs do not authorize OTLP ingest today).\n\nMinimal OpenTelemetry Collector exporter config:\n\n```yaml\nexporters:\n  otlphttp/cortex:\n    endpoint: http://CORTEX_SERVER:3100\n    encoding: proto\n    headers:\n      Authorization: \"Bearer ${env:CORTEX_TOKEN}\"\n\nservice:\n  pipelines:\n    logs:\n      exporters: [otlphttp/cortex]\n```\n\n---\n\n## Retention Policy\n\nLogs are retained for `CORTEX_RETENTION_DAYS` days (default `90`). Set to `0` to disable the global age-based purge (the AdGuard and heartbeat caps below still apply).\n\nThe retention purge runs **hourly** (the separate storage-budget enforcement loop runs on `CORTEX_CLEANUP_INTERVAL_SECS`). It deletes logs in chunks of 10,000 rows, releasing the write lock between chunks so ingest can proceed. Retention cutoff uses `received_at` (the server-side ingestion timestamp), not the `timestamp` in the message. This prevents devices with misconfigured clocks from causing premature or indefinite retention.\n\nSeverity-based exemptions and per-source caps:\n\n- **err+ exemption** — rows with `severity IN (err, crit, alert, emerg)` are never aged out by retention. They can still be deleted under DB-size pressure, but only outside the err+ floor (`CORTEX_ERR_FLOOR_WINDOW_HOURS=24`, `CORTEX_ERR_FLOOR_PER_SOURCE_CAP=10000`).\n- **AdGuard tags** — `adguard-allowed` / `adguard-query` / `adguard-rewrite` rows are hard-capped at **7 days** regardless of `retention_days` (DNS query volume would otherwise dominate the FTS index).\n- **Heartbeats** — heartbeat telemetry rows are capped at **14 days**.\n\nAfter large deletions, an incremental FTS5 merge runs to reclaim index space without long write-lock durations.\n\n---\n\n## Storage Budget Enforcement\n\nTwo independent guards protect against disk exhaustion:\n\n**DB size guard** (`CORTEX_MAX_DB_SIZE_MB`, default 1024 MB — enabled)\n\nWhen the logical SQLite DB size exceeds `max_db_size_mb`, the oldest logs are deleted in chunks of `CORTEX_CLEANUP_CHUNK_SIZE` rows until the size drops below `recovery_db_size_mb`. High-severity rows inside the err+ floor (`CORTEX_ERR_FLOOR_WINDOW_HOURS=24`, capped at `CORTEX_ERR_FLOOR_PER_SOURCE_CAP=10000` rows per source IP) are excluded from the deletable set.\n\n**Free disk guard** (`CORTEX_MIN_FREE_DISK_MB`, default 0 — **disabled**)\n\nWhole-filesystem free space is an external condition cortex cannot fix by deleting its own data, so a free-disk breach **blocks new writes** rather than self-trimming. Writes resume once free disk rises above `recovery_free_disk_mb` (hysteresis prevents oscillation). Enable by setting both `min_free_disk_mb` and a higher `recovery_free_disk_mb`.\n\n**Write-blocking behavior**\n\nIf enforcement cannot free enough space (or the free-disk guard trips), the batch writer enters write-blocked state. New log messages accumulate in an in-memory buffer (`CORTEX_WRITE_CHANNEL_CAPACITY`, default 10,000 messages). Writes resume automatically when space recovers. The `write_blocked` field in `cortex stats` reflects the current state.\n\nDisable either guard by setting its trigger to `0` (also set the recovery target to `0`).\n\n### Heavy SQLite migrations\n\nMost schema setup runs automatically during startup. Heavy migrations, such as creating a new index on a populated multi-million-row `logs` table, can hold SQLite's write lock for several minutes before syslog listeners and `/health` are available. During that window TCP senders may back up and UDP packets may be dropped by kernel buffers.\n\nBefore upgrading a populated database:\n\n1. Take a WAL-safe backup with `scripts/backup.sh` or `sqlite3 /data/cortex.db \".backup /data/syslog-pre-upgrade.db\"`.\n2. Schedule a short ingest maintenance window for large databases.\n3. Start the new version and monitor logs for `Migration N: starting ...` and `Migration N: ... created`.\n4. Keep the previous image or binary available until `/health` returns `ok` and `cortex stats` reports sane counts.\n\nSee [docs/RELEASE.md](docs/RELEASE.md) for the current release and deploy\ngate checklist.\n\n---\n\n## Batch Writer\n\nThe batch writer improves throughput by collecting parsed syslog messages into batches before writing to SQLite.\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CORTEX_BATCH_SIZE` | `100` | Write when this many messages are queued |\n| `CORTEX_FLUSH_INTERVAL` | `500` ms | Write every N ms even if batch is not full |\n| `CORTEX_WRITE_CHANNEL_CAPACITY` | `10000` | Parsed-message queue capacity before listener backpressure |\n\nBatches are written in a single SQLite transaction. If the DB is busy (locked), the writer retries up to 3 times with exponential backoff (25 ms, 100 ms, 250 ms). Batches that fail insertion are retained in memory and retried on the next flush cycle. If a retained batch grows beyond 1,000 entries, it is discarded to prevent unbounded memory growth.\n\nThe internal write channel holds up to `CORTEX_WRITE_CHANNEL_CAPACITY` parsed messages. When the channel is full, backpressure is logged and further UDP/TCP receives block until space is available.\n\n---\n\n## Multi-Host Deployment\n\nPoint multiple hosts at the same cortex instance. Each sender's `hostname` field (from the syslog message) is recorded and indexed. Use `cortex hosts` to see all senders. Filter by `hostname` in `cortex search` and `cortex tail`. Use `cortex correlate` to find related events across hosts within a time window.\n\nFor large fleets, consider:\n- Increasing `CORTEX_POOL_SIZE` (default 4) for higher read concurrency\n- Increasing `CORTEX_BATCH_SIZE` and `CORTEX_FLUSH_INTERVAL` to reduce write overhead\n- Setting `CORTEX_RETENTION_DAYS` to balance history depth against disk cost\n\n---\n\n## Time Synchronization\n\nAll timestamps are stored in UTC. `cortex correlate` uses the `timestamp` field from the syslog message, which reflects the sending device's clock. Devices with drifted clocks will have their events shifted relative to the correlation window. Run NTP on all senders to minimize skew. `received_at` (the server-side ingestion time) is unaffected by sender clock drift and is used for retention.\n\n---\n\n## HTTPS / Reverse Proxy\n\nAdd a SWAG proxy conf to expose the MCP API over TLS:\n\n```nginx\n# /config/nginx/proxy-confs/cortex.subdomain.conf\nserver {\n    listen 443 ssl;\n    server_name cortex.*;\n\n    include /config/nginx/ssl.conf;\n\n    location / {\n        include /config/nginx/proxy.conf;\n        include /config/nginx/resolver.conf;\n\n        # RMCP Streamable HTTP in stateless JSON-response mode.\n        # Clients use POST /mcp; GET/DELETE /mcp are not supported.\n        proxy_http_version 1.1;\n\n        set $upstream_app cortex;\n        set $upstream_port 3100;\n        set $upstream_proto http;\n        proxy_pass $upstream_proto://$upstream_app:$upstream_port;\n    }\n}\n```\n\n---\n\n## Development\n\n```bash\njust dev       # cargo run -- serve mcp\njust check     # cargo check\njust lint      # cargo clippy -- -D warnings\njust fmt       # cargo fmt\njust test      # cargo test\njust build     # cargo build\njust release   # cargo build --release\n```\n\nDocker:\n\n```bash\njust up        # docker compose up -d\njust logs      # docker compose logs -f\njust down      # docker compose down\njust restart   # docker compose restart\ncortex compose doctor\ncortex compose status --json\ncortex compose logs --tail 20\n```\n\nGenerate a bearer token:\n\n```bash\njust gen-token   # openssl rand -hex 32\n```\n\n---\n\n## Verification\n\nAfter deploying, verify the stack:\n\n```bash\n# Health probe (no auth required)\ncurl -sf http://localhost:3100/health | jq .\n# → {\"status\":\"ok\"}\n\n# Send a test message from any Linux host\nlogger -n CORTEX_SERVER -P 1514 --tcp \"test from $(hostname)\"\n\n# Tail recent logs via MCP (replace token if auth is enabled)\ncurl -s -X POST http://localhost:3100/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n      \"method\": \"tools/call\",\n      \"params\": {\n      \"name\": \"cortex\",\n      \"arguments\": {\"action\": \"tail\", \"n\": 10}\n    }\n  }' | jq .\n\n# DB stats\ncurl -s -X POST http://localhost:3100/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 2,\n    \"method\": \"tools/call\",\n    \"params\": {\"name\": \"cortex\", \"arguments\": {\"action\": \"stats\"}}\n  }' | jq .result.content[0].text | jq -r . | jq .\n```\n\nRun the full test suite:\n\n```bash\njust check\njust lint\njust test\n```\n\nRun the live smoke test against a running server:\n\n```bash\nbash scripts/smoke-test.sh\n```\n\nThe smoke test seeds UDP and TCP syslog messages and verifies MCP search/tail results. Docker ingest coverage is handled by the explicit integration path described in the Docker socket-proxy ingest section because it requires an external Docker-compatible log endpoint.\n\n---\n\n## Performance\n\nAt typical homelab scale (1–20 hosts, thousands of messages per day):\n\n- SQLite with WAL mode handles concurrent reads and writes without contention\n- The batch writer sustains thousands of messages per second on commodity hardware\n- FTS5 with porter stemming adds minimal overhead over plain SQL queries\n- `PRAGMA cache_size=-64000` allocates ~64 MB page cache per connection\n- `PRAGMA synchronous=NORMAL` balances durability and throughput\n- Connection pool (default 4) satisfies concurrent MCP requests without blocking\n\nFor higher ingest rates (IoT, high-traffic network devices):\n\n- Increase `CORTEX_BATCH_SIZE` (e.g. `500`) to reduce transaction overhead\n- Increase `CORTEX_FLUSH_INTERVAL` (e.g. `1000` ms) to widen batch windows\n- Increase `CORTEX_WRITE_CHANNEL_CAPACITY` (e.g. `100000`) to absorb bursts\n- Increase `CORTEX_POOL_SIZE` (e.g. `8`) for more read concurrency\n- Place the database on an SSD or tmpfs-backed volume\n\n---\n\n## MCP Transport\n\nThe daemon implements MCP through RMCP Streamable HTTP in stateless JSON-response mode.\n\n- `POST /mcp` — RMCP Streamable HTTP request/response endpoint\n- `GET /mcp` and `DELETE /mcp` — `405 Method Not Allowed` in stateless mode\n- `GET /health` — unauthenticated health probe\n- `cortex mcp` — local query-only stdio MCP mode for clients that launch MCP servers as child processes\n\nWhen `CORTEX_TOKEN` is set, `/mcp` requires:\n\n```\nAuthorization: Bearer \u003ctoken\u003e\n```\n\n`/health` is always unauthenticated (required for Docker health checks and reverse-proxy probes).\n\nStdio mode does not use bearer auth because it is local child-process access. It does require `CORTEX_DB_PATH` to point at the same SQLite database populated by the daemon:\n\n```json\n{\n  \"mcpServers\": {\n    \"cortex\": {\n      \"command\": \"/path/to/cortex\",\n      \"args\": [\"mcp\"],\n      \"env\": {\n        \"CORTEX_DB_PATH\": \"/data/cortex.db\",\n        \"RUST_LOG\": \"warn\"\n      }\n    }\n  }\n}\n```\n\nUse `mcp-remote` instead of direct stdio when the database is only reachable through the running HTTP daemon or a reverse proxy.\n\nThe Docker image remains daemon-focused and exposes HTTP MCP via `cortex serve mcp`; use `cortex mcp` on a host that can read the SQLite DB for direct local stdio.\n\n---\n\n## Related Files\n\n| File | Description |\n|------|-------------|\n| `Cargo.toml` | Crate metadata and dependency surface |\n| `config.toml` | Default runtime configuration |\n| `.env.example` | Canonical environment variable reference |\n| `docs/SETUP.md` | Per-device syslog forwarder setup notes |\n| `CHANGELOG.md` | Release history |\n| `config/Dockerfile` | Container image definition |\n| `docker-compose.yml` | Docker Compose stack |\n| `Justfile` | Development command shortcuts |\n| `src/main.rs` | `cortex` binary entrypoint for HTTP and stdio MCP modes |\n| `src/lib.rs` | Reusable library boundary |\n| `src/app/` | Shared typed log application service |\n| `src/runtime.rs` | Config, DB, syslog, and maintenance orchestration |\n| `src/api.rs` | Always-on non-MCP JSON API routes (`/api/*`, token-gated) |\n| `src/config.rs` | Configuration loading and validation |\n| `src/db.rs` + `src/db/` | SQLite schema, FTS5, retention, storage budget |\n| `src/syslog.rs` + `src/syslog/` | UDP/TCP listeners, syslog parser, batch writer |\n| `src/mcp.rs` + `src/mcp/` | MCP HTTP server, RMCP adapter, auth middleware, tools, health endpoint |\n| `.claude-plugin/plugin.json` | Claude plugin manifest |\n\n---\n\n## Related plugins\n\n| Plugin | Category | Description |\n|--------|----------|-------------|\n| [homelab-core](https://github.com/jmagar/claude-homelab) | core | Core agents, commands, skills, and setup/health workflows for homelab management. |\n| [overseerr-mcp](https://github.com/jmagar/overseerr-mcp) | media | Search movies and TV shows, submit requests, and monitor failed requests via Overseerr. |\n| [unraid-mcp](https://github.com/jmagar/unraid-mcp) | infrastructure | Query, monitor, and manage Unraid servers: Docker, VMs, array, parity, and live telemetry. |\n| [unifi-mcp](https://github.com/jmagar/unifi-mcp) | infrastructure | Monitor and manage UniFi devices, clients, firewall rules, and network health. |\n| [gotify-mcp](https://github.com/jmagar/gotify-mcp) | utilities | Send and manage push notifications via a self-hosted Gotify server. |\n| [swag-mcp](https://github.com/jmagar/swag-mcp) | infrastructure | Create, edit, and manage SWAG nginx reverse proxy configurations. |\n| [synapse-mcp](https://github.com/jmagar/synapse-mcp) | infrastructure | Docker management (Flux) and SSH remote operations (Scout) across homelab hosts. |\n| [arcane-mcp](https://github.com/jmagar/arcane-mcp) | infrastructure | Manage Docker environments, containers, images, volumes, networks, and GitOps via Arcane. |\n| [plugin-lab](https://github.com/jmagar/plugin-lab) | dev-tools | Scaffold, review, align, and deploy homelab MCP plugins with agents and canonical templates. |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmagar%2Fcortex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmagar%2Fcortex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmagar%2Fcortex/lists"}