Skip to content

Privacy and Self-Hosting

Numi Chat is designed to be self-hosted on your own hardware or server, giving individuals and organizations direct control over where conversations, files, and memories are stored and which external APIs are contacted.

Keep chat storage on your instance and choose connections to local models or external services.


1. Local-First Privacy Architecture

  • No telemetry or analytics: Numi Chat contains no usage beacons, tracking pixels, crash reporters, or third-party analytics scripts.
  • Self-hosted frontend assets: All JavaScript, CSS, icons, fonts, and vendor libraries (src/numi_chat/web/static/vendor/) are served directly by your Numi instance rather than fetched from third-party CDNs.
  • Server-side favicon proxy: Citation favicons are fetched and cached through the Numi server (/api/v1/favicon), so external sites see the server's IP rather than direct browser requests from users. (FAVICON_DIRECT_FALLBACK=false by default.)
  • First-party HttpOnly cookies: Session cookies (access_token and refresh_token) use HttpOnly, SameSite=Lax, and Secure (whenever ENVIRONMENT!=development).
  • Keyed-HMAC login throttling: Login rate-limit buckets (auththrottlebucket) store keyed HMAC-SHA256 digests rather than plaintext IP addresses or usernames.
  • Minimal session metadata: Active session rows (refreshtoken) store the browser's User-Agent string so users can review and revoke signed-in devices in Settings; client IP addresses are not stored on session rows.
  • SSRF-hardened outbound fetches: Direct PDF and opt-in page/favicon fetches validate DNS resolutions against private/loopback ranges and pin each connection and redirect hop to the validated public IP.
  • Scoped offline PWA cache: When installed as an app, the browser caches viewed chats for offline reading, excludes Cache-Control: no-store and admin responses, removes deleted chats, and wipes the offline cache on sign-out. See Install Numi as an App.
  • Cascading deletes: Deleting a chat or user account removes its database rows (ON DELETE CASCADE) and deletes its upload, generated-file, and avatar directories on disk.
  • Production-safe logging: Loguru variable inspection (LOG_DIAGNOSE) defaults to false and is forced off outside development so exception tracebacks do not dump local variable values into log files.

2. User Data Controls & Portability

Numi Chat includes built-in endpoints and UI controls for managing personal data:

  • Full data export (GET /api/v1/me/export): Downloads a structured JSON archive containing the user's account metadata, preferences, chats, complete message records, memory entries/items/history, and extracted document metadata.
  • Memory export & one-click clear: Users can export their memory profile as Markdown or wipe all derived and manual memories (DELETE /api/v1/me/memory), which also advances memory_cleared_at so older chats are never re-extracted.
  • Account self-deletion (DELETE /api/v1/me/): Verifies the user's current password, revokes all sessions, deletes all database records owned by the account, and removes associated files from state/.
  • Profile & credential management: Users can update their username (PATCH /api/v1/me/username), password (POST /api/v1/me/password), personal instructions (POST /api/v1/me/settings), and memory toggle at any time.

3. Outbound Requests & Model Routing

A self-hosted instance only sends data over the network to endpoints you configure:

  • Chat model endpoint: Receives the system prompt, opening <user_context>, bounded conversation history, turn attachments, and active tool schemas for the model selected in the chat. To keep inference 100% on your own hardware, use a local catalog model pointed at LOCAL_AI_BASE_URL (such as Ollama, vLLM, or llama.cpp).
  • Background memory & title models: Memory extraction (MEMORY_SUMMARY_MODEL) and automatic chat titles (CHAT_TITLE_MODEL) default to deepseek/deepseek-v4.1-flash-1017 via OpenRouter. If you run a local-only instance, either point those settings (or their admin UI overrides) at your local model, set MEMORY_SUMMARY_MODEL=inherit and CHAT_TITLE_MODEL=inherit, or disable background memory with MEMORY_ENABLED=false.
  • Pre-turn optional tool router: When DECISIONS_ENABLED=true (default), Numi classifies the user's raw message text (without history, memory, or files) via the OpenRouter Decisions API (DECISIONS_TOOL_GROUP_ROUTER=jev) or the local ONNX router (numi_route_alpha) when OpenRouter is configured. Set DECISIONS_ENABLED=false to disable pre-turn routing completely.
  • Enabled tools: Search (web_search), page extraction (fetch_web_page), image generation (generate_image), and optional integrations (weather, Wikipedia/academic search, grocery, shopping, deals) contact their respective upstream APIs only when invoked. See Secure Tool Access.

4. Operator Privacy Notice Configuration

Operators can publish their controller identity and privacy policy link on the sign-in screen and in the About dialog by setting these variables in .env:

INSTANCE_NAME="My Organization Chat"
OPERATOR_NAME="Example Organization"
OPERATOR_ADDRESS="123 Example St, City, Country"
PRIVACY_CONTACT_EMAIL="privacy@example.com"
PRIVACY_POLICY_URL="https://example.com/privacy"

These fields are served via the public GET /api/v1/instance endpoint when configured and omitted cleanly when left blank.


5. Operator Checklist for Regulated Deployments

When operating an instance for an organization or multiple users (for example, under GDPR):

  1. Controller notice: Configure the OPERATOR_* and PRIVACY_* settings above so users can see who operates the instance and where to read your privacy policy.
  2. Provider agreements: Choose model and search providers whose data-retention terms, regional hosting, and Data Processing Agreements (DPAs) match your compliance requirements, or route all chat and background models to self-hosted local inference.
  3. HTTPS & reverse proxy: Terminate TLS at a reverse proxy (ENVIRONMENT=production, CORS_ALLOW_ORIGINS, FORWARDED_ALLOW_IPS) as shown in Run with Docker.
  4. Backup & log retention: Apply your retention schedule to chats.db backups and rotated logs/ files on the host.