cortex

{
  "name": "cortex",
  "description": "Self-hosted log aggregation and investigation for homelabs: syslog, Docker, OTLP, and AI transcripts in SQLite/FTS, exposed over MCP, CLI, and REST.",
  "author": {
    "name": "jmagar"
  },
  "repository": "https://github.com/dinglebear-ai/cortex",
  "license": "MIT",
  "keywords": [
    "cortex",
    "mcp",
    "logging",
    "homelab"
  ],
  "mcpServers": "./plugins/cortex/mcp.json",
  "skills": "./plugins/cortex/skills",
  "userConfig": {
    "is_server": {
      "type": "boolean",
      "title": "Run as server",
      "description": "True on the ONE machine in your fleet that should ingest and store logs — it runs the syslog receiver (UDP+TCP), the SQLite store, and the MCP HTTP server. False on every other machine that just needs to query logs from Claude Code; those instances skip all local server setup and act as MCP clients only.",
      "required": true,
      "default": true
    },
    "server_url": {
      "type": "string",
      "title": "Server URL",
      "description": "Base URL the MCP client in this Claude Code session connects to (always used — both modes). Server mode: keep the default http://localhost:3100 so the local MCP client talks to the local server. Client mode: set to the remote server, e.g. http://devhost:3100, http://syslog.lan:3100, or https://syslog.example.com if fronted by a reverse proxy. Must include the scheme and (if non-default) port; do NOT include a trailing /mcp path — the plugin appends it.",
      "required": true,
      "default": "http://localhost:3100"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Bearer token for MCP HTTP authentication, sent on every request as `Authorization: Bearer <token>`. Server mode: pick any value — that becomes the secret the server enforces (generate one with `openssl rand -hex 32`, or use `just gen-token`). Client mode: paste the token your server admin configured. The same token must match on both sides; mismatched tokens return 401.",
      "sensitive": true,
      "required": false
    },
    "no_auth": {
      "type": "boolean",
      "title": "Disable service auth",
      "description": "Run cortex without service-local MCP auth. Use this only when an upstream gateway or reverse proxy enforces auth before traffic reaches cortex. Server mode only.",
      "required": true,
      "default": false
    },
    "auth_mode": {
      "type": "string",
      "title": "Auth mode",
      "description": "Server auth mode. bearer keeps the static API token only. oauth enables Google OAuth/JWT for clients like Codex while the generated API token remains accepted for this Claude Code plugin connection. OAuth mode requires public_url, google_client_id, google_client_secret, and auth_admin_email.",
      "required": true,
      "default": "bearer"
    },
    "public_url": {
      "type": "string",
      "title": "Public URL",
      "description": "Public base URL for OAuth issuer/resource metadata, e.g. https://syslog.example.com. If auth_mode=oauth and this is empty, setup derives it from an https server_url by stripping a trailing /mcp if present. Server mode only.",
      "default": ""
    },
    "google_client_id": {
      "type": "string",
      "title": "Google OAuth client ID",
      "description": "Google OAuth client ID used when auth_mode=oauth. Create a Web application OAuth client in Google Cloud Console. Server mode only.",
      "default": ""
    },
    "google_client_secret": {
      "type": "string",
      "title": "Google OAuth client secret",
      "description": "Google OAuth client secret used when auth_mode=oauth. Stored in the generated plugin env file with mode 600. Server mode only.",
      "sensitive": true,
      "default": ""
    },
    "auth_admin_email": {
      "type": "string",
      "title": "OAuth admin email",
      "description": "Bootstrap allowed Google account for OAuth mode. The server refuses to start OAuth without an allowlisted account. Server mode only.",
      "default": ""
    },
    "auth_allowed_redirect_uris": {
      "type": "string",
      "title": "OAuth redirect URIs",
      "description": "Optional extra non-loopback OAuth client redirect URIs. Setup automatically adds Claude's MCP callback URLs and, when present, the current Codex mcp_oauth_callback_url from ~/.codex/config.toml. Server mode only.",
      "default": ""
    },
    "cortex_receiver_host": {
      "type": "string",
      "title": "Syslog bind host",
      "description": "Interface address the syslog receiver binds to. 0.0.0.0 listens on every interface so other hosts on the LAN/VPN can forward to you (the normal homelab choice). 127.0.0.1 restricts to local-only ingestion (useful when only this host's rsyslog forwards in). Server mode only.",
      "default": "0.0.0.0"
    },
    "cortex_receiver_port": {
      "type": "number",
      "title": "Syslog port",
      "description": "UDP and TCP port the syslog receiver binds to inside the server process or Docker container (the same port serves both protocols). Keep this at 1514 unless you intentionally grant CAP_NET_BIND_SERVICE or run as root. Server mode only.",
      "default": 1514
    },
    "cortex_receiver_host_port": {
      "type": "number",
      "title": "Docker syslog host port",
      "description": "Host port published by Docker Compose to the container's syslog bind port. Set this to 514 when devices can only forward to the privileged syslog port, while leaving cortex_receiver_port at 1514 inside the container. Docker server mode only.",
      "default": 1514
    },
    "mcp_host": {
      "type": "string",
      "title": "MCP bind host",
      "description": "Interface address the MCP HTTP server binds to. 0.0.0.0 makes the MCP endpoint reachable from other hosts (required if any client-mode peer needs to connect). 127.0.0.1 keeps it local-only (use this if you front the server with a reverse proxy on the same host, or only query from this machine). Server mode only.",
      "default": "0.0.0.0"
    },
    "mcp_port": {
      "type": "number",
      "title": "MCP HTTP port",
      "description": "TCP port the MCP HTTP server listens on (serves POST /mcp and GET /health). Default 3100. Must match the port in server_url for clients to reach you. Avoid 3000 to dodge the common Node.js dev server collision. Server mode only.",
      "default": 3100
    },
    "max_db_size_mb": {
      "type": "number",
      "title": "Max database size (MB)",
      "description": "Soft cap on logical SQLite DB size. When exceeded, oldest logs (ordered by received_at) are deleted in batches until the recovery target is met; if cleanup can't free enough space, NEW WRITES are blocked until storage recovers. 0 disables this guard entirely (logs grow until disk fills or retention purges them). Default 8192 MB (8 GB) is sized for a homelab ingesting from a handful of hosts plus Docker stdout — bump much higher (50000+) if you have lots of free disk and want long retention, lower if storage is tight. Server mode only.",
      "default": 8192,
      "min": 0
    },
    "data_dir": {
      "type": "directory",
      "title": "Data directory",
      "description": "Directory holding the SQLite database file (cortex.db plus its WAL/SHM sidecars in WAL mode). Defaults to the plugin's persistent data directory ($CLAUDE_PLUGIN_DATA), which survives plugin upgrades. Override only if you need the DB on a different volume — e.g. a larger or faster disk. The directory must exist and be writable by the user running the service. Server mode only.",
      "default": "${CLAUDE_PLUGIN_DATA}"
    },
    "retention_days": {
      "type": "number",
      "title": "Log retention (days)",
      "description": "Age-based purge: log entries older than this are PERMANENTLY DELETED hourly with no recovery path — back up first with `scripts/backup.sh` if you need archival. 0 disables age-based purging entirely (storage guards from max_db_size_mb still apply). Default 90 days balances forensic value against DB size for a typical homelab. Server mode only.",
      "default": 90,
      "min": 0
    },
    "batch_size": {
      "type": "number",
      "title": "Ingest batch size",
      "description": "Number of parsed syslog messages written per SQLite batch. Higher values reduce transaction overhead during bursts but can add write latency. Server mode only.",
      "default": 100,
      "min": 1
    },
    "write_channel_capacity": {
      "type": "number",
      "title": "Ingest queue capacity",
      "description": "In-memory parsed-message queue capacity before listener backpressure. Increase this for bursty senders like journald backfill or high-volume network devices. Server mode only.",
      "default": 10000,
      "min": 1
    },
    "docker_ingest_enabled": {
      "type": "boolean",
      "title": "Enable Docker log ingestion",
      "description": "Pull container stdout/stderr from remote Docker socket proxies in addition to syslog. When true, each fleet_host is treated as a docker-socket-proxy endpoint at http://<host>:2375 and continuously polled for container logs. Logs land in the DB tagged hostname=<host>, app_name=<container>, source_ip=docker://<host>/<container>/<stream>. Each fleet host MUST be running docker-socket-proxy (or equivalent) on port 2375 with at least containers/logs read access — exposing the raw Docker socket is unsafe. Server mode only.",
      "required": true,
      "default": false
    },
    "fleet_hosts": {
      "type": "string",
      "title": "Fleet hosts",
      "description": "Hostnames for hosts in your fleet. Used for Docker ingest: when docker_ingest_enabled is true, each entry becomes the docker-socket-proxy URL http://<host>:2375. Entries must be reachable by name — resolvable DNS or an /etc/hosts entry, not just an SSH config alias. Add one entry per host, e.g. devhost, edgehost, nashost. Leave empty if you don't use Docker ingest.",
      "required": true,
      "multiple": true
    }
  }
}