模块化AI助手

🐳 Docker

docker pull ghcr.io/northlandpositronics/cogtrix:latest
docker run -it --network host ghcr.io/northlandpositronics/cogtrix:latest

The image bundles every optional package (Anthropic, Google, MCP, all search providers, NumPy/SciPy). --network host lets it reach a local Ollama. Mount your config (-v "$HOME/.cogtrix.yaml:/app/.cogtrix.yaml:ro") and persist sessions (-v cogtrix-data:/data). Append api to the docker command to launch the REST/WS server instead of the interactive CLI.

---

⚙️ Configuration in one screenful

Cogtrix runs with zero config when Ollama is on localhost. For anything more, drop a YAML file in .cogtrix.yaml (project) or ~/.cogtrix.yaml (global):

providers:
  my-server:
    type: ollama
    base_url: "http://192.168.1.100:11434"
  openai:
    type: openai

models:
  default: local
  local:                          # everyday work — local qwen3 on a home GPU
    provider: my-server
    model: qwen3:8b
  fast: my-server/qwen3:8b        # same model, shorthand alias form
  smart: openai/gpt-4.1           # heavy reasoning, e.g. /think and /delegate

services:
  tavily:
    api_key: "tvly-..."           # cleaner results than DuckDuckGo at low volume

JSON works too (.cogtrix.json). Settings are resolved highest priority first: CLI flags → environment variables → config file → built-in defaults.

Full reference: Configuration Guide.

---

🛠️ Optional extras

uv pip install "cogtrix[anthropic]"   # Anthropic Claude
uv pip install "cogtrix[google]"      # Google Gemini
uv pip install "cogtrix[api]"         # REST API server + Stripe billing
uv pip install "cogtrix[mcp]"         # MCP server support
uv pip install "cogtrix[search]"      # Tavily, Exa, Brave, SerpAPI
uv pip install "cogtrix[rag]"         # RAG (needs C++ build tools)
uv pip install "cogtrix[saml]"        # SAML 2.0 SSO (needs libxmlsec1-dev on Linux)
uv pip install "cogtrix[ldap]"        # LDAP / Active Directory sync

---

🔌 REST + WebSocket API

Cogtrix ships a FastAPI server that exposes 159 REST endpoints across 27 route groups plus 2 WebSocket streams. It's the same API the React web frontend uses.

```bash export COGTRIX_JWT_SECRET="$(python -c 'import secrets; print(secrets.token_hex(32))')" python -m src.api

or: python -m src.api --debug --reload

```

Interactive docs at http://localhost:8000/api/v1/docs (Swagger) and /api/v1/redoc.

Auth: JWT bearer tokens (Authorization: Bearer <token>). First registered user gets the admin role automatically. API keys (prefix cgx_live_) can be created and managed via /api/v1/auth/api-keys and are accepted in the same Authorization: Bearer header — the request-auth dependency dispatches on prefix.

WebSockets: The session stream (/ws/v1/sessions/{id}) requires the JWT in the Authorization header; the ?token=<jwt> query-parameter fallback was removed for security (#1128). The admin log stream (/ws/v1/logs) still accepts ?token=<jwt> for clients that can't set custom WS headers.

Route map by group:

Full reference: API Reference · Client Contract · WebSocket Protocol.

---

🚦 Troubleshooting

Detailed debugging: run with --debug (logs every LLM call, tool input/output, and context info to cogtrix.log).

---