SQLite와 FTS5 검색을 사용하여 홈랩 로그, 메트릭 및 AI 트랜스크립트를 위한 셀프 호스팅 지능형 레이어를 제공합니다.
다른 이름 dinglebear-ai/cortex, cortex, @dinglebear/cortex
- 스타
- 4
- Tools
- —
- 다운로드, 30일
- 486
- 최신 버전
- 3.13.2
- 마지막 커밋
- 2026년 11월 9일
- 라이선스
- AGPL-3.0
Cortex MCP란?
SQLite와 FTS5 검색을 사용하여 홈랩 로그, 메트릭 및 AI 트랜스크립트를 위한 셀프 호스팅 지능형 레이어를 제공합니다.
프로젝트 README에서 생성된 요약
Cortex MCP server 정보
Cortex RMCP는 홈랩 환경과 소규모 프라이빗 플릿을 위해 설계된 셀프 호스팅 지능형 레이어를 제공합니다. 로그, 메트릭, 트레이스 및 AI 세션 트랜스크립트를 하나의 검색 가능한 저장소로 중앙 집중화합니다. FTS5 전체 텍스트 검색 기능이 있는 SQLite를 사용하여 Docker 이벤트, syslog, OpenTelemetry 신호와 같은 다양한 데이터 소스를 통합된 타임라인 및 인시던트 번들로 상관 분석할 수 있습니다.
개발자는 네이티브 CLI, REST API 또는 MCP server를 통해 데이터와 상호작용할 수 있습니다. MCP 구현은 두 가지 모드를 지원합니다. 로컬 데이터베이스를 읽기 위한 쿼리 전용 stdio 모드와 bearer token을 통해 지속적인 데몬에 연결하는 streamable HTTP 모드입니다. UDP/TCP syslog, OTLP/HTTP 및 호스트 하트비트를 포함한 다양한 수집 유형을 처리하도록 구축되어, 대규모 클러스터형 웨어하우스의 복잡성 없이 운영 증거를 관리할 수 있는 전문 도구입니다.
활용 사례
- 1다중 소스 로그 상관 분석AI에게 특정 시간 동안의 Docker 라이프사이클 이벤트와 네트워크 syslog 엔트리 간의 연결 고리를 찾도록 요청합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Cortex MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Cortex MCP 설치
$ claude mcp add --env 'CORTEX_API_TOKEN=<YOUR_CORTEX_API_TOKEN>' --env 'CORTEX_TOKEN=<YOUR_CORTEX_TOKEN>' cortex -- npx -y @dinglebear/cortexCursor에 Cortex MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"cortex": {
"command": "npx",
"args": [
"-y",
"@dinglebear/cortex"
],
"env": {
"CORTEX_API_TOKEN": "<YOUR_CORTEX_API_TOKEN>",
"CORTEX_TOKEN": "<YOUR_CORTEX_TOKEN>"
}
}
}
}VS Code에 Cortex MCP 설치
.vscode/mcp.json
{
"servers": {
"cortex": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@dinglebear/cortex"
],
"env": {
"CORTEX_API_TOKEN": "<YOUR_CORTEX_API_TOKEN>",
"CORTEX_TOKEN": "<YOUR_CORTEX_TOKEN>"
}
}
}
}VS Code CLI에 Cortex MCP 설치
$ code --add-mcp '{"name":"cortex","type":"stdio","command":"npx","args":["-y","@dinglebear/cortex"],"env":{"CORTEX_API_TOKEN":"<YOUR_CORTEX_API_TOKEN>","CORTEX_TOKEN":"<YOUR_CORTEX_TOKEN>"}}'Claude Desktop에 Cortex MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"cortex": {
"command": "npx",
"args": [
"-y",
"@dinglebear/cortex"
],
"env": {
"CORTEX_API_TOKEN": "<YOUR_CORTEX_API_TOKEN>",
"CORTEX_TOKEN": "<YOUR_CORTEX_TOKEN>"
}
}
}
}Codex에 Cortex MCP 설치
$ codex mcp add cortex --env 'CORTEX_API_TOKEN=<YOUR_CORTEX_API_TOKEN>' --env 'CORTEX_TOKEN=<YOUR_CORTEX_TOKEN>' -- npx -y @dinglebear/cortexCodex config.toml에 Cortex MCP 설치
~/.codex/config.toml
[mcp_servers.cortex] command = "npx" args = ["-y", "@dinglebear/cortex"] [mcp_servers.cortex.env] CORTEX_API_TOKEN = "<YOUR_CORTEX_API_TOKEN>" CORTEX_TOKEN = "<YOUR_CORTEX_TOKEN>"
Gemini CLI에 Cortex MCP 설치
$ gemini mcp add -s user -e 'CORTEX_API_TOKEN=<YOUR_CORTEX_API_TOKEN>' -e 'CORTEX_TOKEN=<YOUR_CORTEX_TOKEN>' cortex npx -- -y @dinglebear/cortexGemini settings.json에 Cortex MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"cortex": {
"command": "npx",
"args": [
"-y",
"@dinglebear/cortex"
],
"env": {
"CORTEX_API_TOKEN": "<YOUR_CORTEX_API_TOKEN>",
"CORTEX_TOKEN": "<YOUR_CORTEX_TOKEN>"
}
}
}
}구성
CORTEX_API_TOKEN비밀Bearer token for Cortex REST API routes when running daemon/API mode.
CORTEX_TOKEN비밀Optional bearer token for Cortex MCP HTTP mode; also used by some shared configs.
CORTEX_DB_PATHCORTEX_HOMEOptional Cortex home directory containing configuration and local SQLite data.
CORTEX_RMCP_RELEASE_BASE_URLOptional release download base URL override.
CORTEX_RMCP_REPOOptional GitHub owner/repo override for release asset downloads.
CORTEX_RMCP_VERSIONOptional GitHub release tag override for the downloaded Cortex binary.
RUST_LOGTracing filter for Cortex logs.
| 이름 | 설명 | 유형 |
|---|---|---|
| CORTEX_API_TOKEN | Bearer token for Cortex REST API routes when running daemon/API mode. | 비밀 |
| CORTEX_TOKEN | Optional bearer token for Cortex MCP HTTP mode; also used by some shared configs. | 비밀 |
| CORTEX_DB_PATH | — | |
| CORTEX_HOME | Optional Cortex home directory containing configuration and local SQLite data. | |
| CORTEX_RMCP_RELEASE_BASE_URL | Optional release download base URL override. | |
| CORTEX_RMCP_REPO | Optional GitHub owner/repo override for release asset downloads. | |
| CORTEX_RMCP_VERSION | Optional GitHub release tag override for the downloaded Cortex binary. | |
| RUST_LOG | Tracing filter for Cortex logs. |
자동 검사
2026년 11월 13일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기Cortex
Self-hosted homelab log intelligence over MCP, CLI, and REST with SQLite/FTS.
It collects logs and operational evidence, stores them in SQLite with FTS5 search, and exposes one shared intelligence layer through CLI, REST, MCP, and a bundled browser workspace.
Cortex began as a syslog receiver. It now covers network logs, Docker, managed files, OpenTelemetry logs, metrics, and traces, host heartbeats, fleet inventory, shell and agent activity, and Claude, Codex, Gemini CLI, and Antigravity transcripts. It correlates those sources into timelines, incidents, and an evidence-backed topology graph without making the graph a second source of truth.
At a glance
| Area | What Cortex provides |
|---|---|
| Ingest | UDP/TCP syslog, OTLP/HTTP logs, metrics, and traces, 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 63 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, Gemini CLI, and Antigravity session indexing; skill, MCP, and hook event extraction where each provider exposes them; 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
- How Cortex is built
- Ingestion
- Investigation and intelligence
- Fleet inventory and graph
- AI session intelligence
- Alerts and notifications
- Interfaces
- Configuration
- Authentication and trust boundaries
- Storage and maintenance
- Deployment and distribution
- Operations
- Development and verification
- Documentation
- Current boundaries
- License
Quick start
Install and choose a role
curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/cortex/main/install.sh | sh
On Windows x64:
irm https://raw.githubusercontent.com/dinglebear-ai/cortex/main/install.ps1 | iex
The checksum-verified bootstrap supports Linux x64/ARM64, macOS ARM64, and
Windows x64. It runs cortex setup start, which asks whether this machine is a
server, a client, or a host agent. Server setup prepares configuration, distinct
MCP/REST credentials, storage and managed Compose. Client setup connects selected
MCP clients. Agent setup detects local collection prerequisites and enables only
the capabilities you explicitly select. First server setup also asks for
authentication mode, exposure, and an optional six-hour backup schedule.
Already have the CLI, or automating installation? Select the role explicitly:
cortex setup start --role server --clients codex,claude,gemini
cortex setup start --role client --server https://cortex.example.com \
--token-file /private/mcp-token --api-token-file /private/rest-token
cortex setup start --role agent --server https://cortex.example.com \
--token-file /private/ingest-token --capabilities docker,transcripts
First-time noninteractive setup requires --role; subsequent setup reuses the
saved choice. --dry-run --json previews configuration and capabilities without
installing services. All advanced settings remain available through --set and
--secret-file; sensitive collection requires explicit selection.
--backup-schedule and --no-backup-schedule save the backup scheduling choice.
cortex setup effective --json
cortex setup verify --json
cortex update
Verification proves authenticated MCP access and REST access when configured; source delivery still needs its own evidence. Updates use saved deployment settings and respect version pins. See the setup guide for capability selection, OAuth, prerequisites, source builds, manual native operation, and installer environment controls; see the deployment runbook for backup and recovery.
For guided agent assistance:
npx skills add dinglebear-ai/cortex --skill install-cortex
Start a fresh task and invoke $install-cortex.
The npm launcher remains available for local CLI and stdio MCP use with Node.js 18 or newer:
npx -y @dinglebear/cortex --help
npx -y @dinglebear/cortex mcp
npm install --global @dinglebear/cortex
Connect an MCP client
Query-only stdio mode reads the configured local database and starts no network listeners:
{
"mcpServers": {
"cortex": {
"command": "npx",
"args": ["-y", "cortex-rmcp", "mcp"],
"env": {
"CORTEX_DB_PATH": "/absolute/path/to/cortex.db"
}
}
}
}
Streamable HTTP mode connects to the persistent daemon:
{
"mcpServers": {
"cortex": {
"url": "http://127.0.0.1:3100/mcp",
"headers": {
"Authorization": "Bearer your-cortex-token"
}
}
}
}
A useful first call is:
{"action":"status"}
Then narrow the investigation with tail, errors, search, timeline, or context before using broader analysis operations.
How Cortex is built
Cortex is one Rust binary with multiple operating modes. The same application and service layer backs the CLI, REST handlers, and MCP handlers, so validation, limits, identity resolution, redaction, and business rules do not belong to one transport alone.
INGESTION
Syslog UDP/TCP OTLP signals Docker agent / pull
Managed file tails Heartbeats Claude / Codex / Gemini / Antigravity
Shell history Agent commands Fleet inventory
\ | /
\ | /
+---- bounded parsing and enrichment ----+
|
scrub, normalize, batch
|
SQLite WAL + FTS5
|
+----------------+----------------+
| |
authoritative records derived accelerators
logs, heartbeats, rollups, signatures,
inventory, sessions graph projections
| |
+----------------+----------------+
|
shared service layer
|
CLI REST MCP Web workspace
The daemon supervises its receivers and background services with cooperative cancellation. Shutdown drains HTTP requests, gives maintenance tasks 10 seconds to finish before abort-and-join, gives ingest 5 seconds to flush, and then attempts a WAL checkpoint. Already-running blocking SQLite calls cannot be cancelled by Tokio.
Background services include:
- Retention and storage-budget enforcement
- WAL and FTS maintenance
- Docker ingest supervision
- File-tail supervision
- Error-signature scanning
- Notification evaluation, dispatch, and digest scheduling
- Inventory refresh and backfill
- Graph projection refresh
- AI-session and timeline rollups
- Database optimization and maintenance jobs
Heavy analytical reads and maintenance jobs have separate concurrency controls so one expensive investigation cannot starve the ingest path.
Ingestion
All log-like sources are normalized into the same durable log model, enriched where safe, scrubbed where configured, and written through bounded batch paths.
Syslog over UDP and TCP
Cortex listens on the same configurable port for UDP and TCP syslog. It parses common RFC 3164 and RFC 5424 shapes, preserves the raw frame, records sender identity, normalizes severity and facility, and enriches known application formats.
Relevant defaults:
- Bind:
0.0.0.0:1514 - Maximum message: 8 KiB
- Maximum concurrent TCP connections: 512
- TCP idle timeout: 300 seconds
- Writer batch: 100 records or 500 ms
- Write queue capacity: 10,000 records
Syslog has no application-layer authentication. Restrict senders with network controls and CORTEX_ALLOWED_SOURCE_CIDRS when the listener is reachable beyond a trusted network.
Built-in enrichment recognizes useful signals from AdGuard, Authelia, Docker lifecycle events, fail2ban, Linux kernel and OOM events, SWAG, reverse-proxy logs, and host-local Cortex Docker agent metadata. Source gates can restrict enrichment that would otherwise trust a marker inside an unauthenticated syslog body.
OpenTelemetry ingestion
Cortex accepts protobuf OTLP/HTTP export requests on the shared HTTP listener. Logs use POST /v1/logs with a 4 MiB body limit and flow through the normal writer. Metrics use POST /v1/metrics and traces use POST /v1/traces, each with an 8 MiB body limit and dedicated storage. Metric requests admit at most 5,000 points and also enforce a bounded normalized payload budget.
Current OTLP scope is intentionally narrow:
- Logs, traces, and metrics over HTTP/protobuf are supported.
- OTLP/gRPC is not implemented.
All three OTLP endpoints authenticate with CORTEX_TOKEN — the same static MCP bearer token that guards POST /mcp, read from the managed ~/.cortex/.env on a deployed host. It is not CORTEX_API_TOKEN (REST /api/*) and not CORTEX_API_ADMIN_TOKEN. Loopback and trusted-gateway policies skip the check. An OAuth-only deployment with no static token denies OTLP outright, because machine exporters have no OAuth flow — so a non-loopback OAuth-only OTLP exposure is rejected at startup unless CORTEX_TOKEN is set.
Docker logs and events
Cortex supports two Docker collection paths:
- 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.
- 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/sessionsand~/.codex/worktrees - Gemini CLI chat data under
~/.gemini/tmp - Antigravity desktop's redacted transcript projections under
~/.gemini/antigravity/brain/<session>/.system_generated/logs/transcript.jsonl - Antigravity CLI's redacted transcript projections under
~/.gemini/antigravity-cli/brain/<session>/.system_generated/logs/transcript.jsonl
The Antigravity adapter reads only the narrow redacted JSONL projections above; it does not scan conversation databases or other brain artifacts. 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 where those lanes are represented by the provider schema, and reports unsupported lanes honestly.
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-commandsfor deduplicated agent command-spool recordsPOST /v1/shell-historyfor 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 snapshotcollection-state.json: collector health, timing, and warning stateraw/<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 provider subprocess.
CORTEX_LLM selects the provider and optional model for every LLM operation: skill, MCP, hook, and abuse assessments, including dry-run audit metadata. Set CORTEX_LLM=codex (the default, using Codex app-server) or CORTEX_LLM=gemini (Gemini CLI). To pin the model globally, use CORTEX_LLM=codex/gpt-5.5 or CORTEX_LLM=gemini/gemini-3.1-flash-lite-preview. An explicit model in CORTEX_LLM wins over --model; otherwise that existing flag can select a model for one invocation. Empty or unsupported selectors fail without provider fallback.
The selector also works in managed ~/.cortex/.env; process environment values take precedence. Settings are retained after config loading.
The old CORTEX_CODEX_MODEL and CORTEX_HEADLESS_GEMINI_MODEL variables are ignored. Command and authentication-home overrides remain installation settings, not provider selectors. --no-llm needs no provider configuration or credentials.
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.
| Group | Purpose |
|---|---|
search, filter, tail |
Log retrieval |
hosts, apps, entity, graph |
Discovery and topology |
analysis, correlate, state, stats, timeline |
Investigation and analytics |
sessions, assess |
AI-session queries and local guarded assessments |
alerts |
Error signatures, acknowledgements, and notification history |
ingest, heartbeat |
Collectors, agents, file tails, inventory, and heartbeats |
serve, mcp |
Full daemon and query-only stdio MCP modes |
doctor, status, db, compose |
Diagnostics and maintenance |
setup, update, config, completions |
Lifecycle and operator tooling |
Examples:
cortex search "oom killer" --host devhost --since 1h
cortex filter --severity err --since 6h
cortex timeline --since 24h
cortex sessions search "migration failure"
cortex graph explain --help
cortex alerts errors list
cortex ingest inventory refresh --json
cortex ingest filetail list
cortex status
cortex doctor
The CLI supports direct/local operation and HTTP operation. REST-backed mode is the normal remote path and uses CORTEX_URL plus CORTEX_API_TOKEN.
MCP
Cortex exposes one MCP tool named cortex. Its required action field selects an action from a single authoritative Rust registry. The mechanically generated current count is published in the live coverage inventory.
The current scope split is:
- 53 read actions requiring
cortex:read - 6 admin actions requiring
cortex:admin:artifact_evidence_record,ack_error,unack_error,file_tails,notifications_test, andllm_invocations - 1 informational action,
help, which requires an authenticated context when authentication is mounted but no read/admin scope
Cortex MCP 질문
Cortex MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --env 'CORTEX_API_TOKEN=<YOUR_CORTEX_API_TOKEN>' --env 'CORTEX_TOKEN=<YOUR_CORTEX_TOKEN>' cortex -- npx -y @dinglebear/cortex를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Cortex MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Cortex는 어떤 종류의 데이터를 수집할 수 있나요?
Cortex는 syslog (UDP/TCP), OTLP 로그, 메트릭 및 트레이스, Docker 로그 및 이벤트, 관리형 파일 테일, 호스트 하트비트, AI 트랜스크립트, 셸 히스토리, 플릿 인벤토리를 수집합니다.
Cortex는 대규모 엔터프라이즈 환경에 적합한가요?
아니요, Cortex는 클러스터형 로그 웨어하우스나 범용 SIEM보다는 신뢰할 수 있는 홈랩 또는 소규모 프라이빗 플릿을 위해 특별히 설계되었습니다.
MCP 클라이언트를 Cortex에 어떻게 연결하나요?
로컬 데이터베이스를 가리키는 쿼리 전용 stdio 모드를 사용하거나, bearer token을 사용하여 지속적인 데몬에 연결하는 streamable HTTP 모드를 사용할 수 있습니다.