Skip to main content

Self-Hosting Guide

ZenSearch self-host is delivered as an enterprise engagement. Every deployment is sized to your data, identity stack, compliance posture, and connector mix.

:::tip Talk to our team To scope a deployment, contact [email protected]. Existing enterprise customers can also reference the Authentication and OAuth Client Setup pages while configuring their environment. :::

What self-hosting gives you​

  • Full data sovereignty — your data never leaves your network
  • Air-gapped support — deploy without internet connectivity
  • Bring your own LLM — use OpenAI, Anthropic, Cohere, Groq, OpenRouter, Azure AI Foundry, Amazon Bedrock, Ollama, or any OpenAI-compatible endpoint
  • Infrastructure control — deploy on AWS, GCP, Azure, or bare metal
  • Custom networking — configure VPCs, firewalls, and service mesh as needed
  • Compliance review paths — SOC 2, HIPAA, and GDPR

Deployment options​

Docker Compose​

Single-machine deployment for smaller production footprints and departmental rollouts. All application services, infrastructure, and selected connectors start with a single command.

Best for: teams of up to ~50 users, evaluation environments, and staging.

Kubernetes​

Production deployment with horizontal scaling, health checks, rolling updates, and high availability. Helm charts are provided as part of the engagement.

Best for: large teams, production workloads, organizations with existing Kubernetes infrastructure.

Air-Gapped Deployment​

For environments with no internet access:

  1. All container images can be pre-loaded from an internet-connected staging machine.
  2. Use a self-hosted LLM (Ollama, vLLM, or any OpenAI-compatible server) instead of cloud providers.
  3. Pre-download ML models for local inference.
  4. No internet access required after initial setup.

Hardware Requirements​

Small team (< 10,000 documents):

  • 8 CPU cores
  • 16 GB RAM
  • 100 GB SSD storage
  • No GPU required (uses cloud LLM APIs)

Medium team (10,000–100,000 documents):

  • 16 CPU cores
  • 32 GB RAM
  • 500 GB SSD storage
  • Optional: NVIDIA GPU for local document parsing

Large scale (100,000+ documents):

  • 32+ CPU cores
  • 64+ GB RAM
  • 1 TB+ SSD storage
  • NVIDIA GPU recommended for local parsing
  • Consider running infrastructure on dedicated nodes

Configuration overview​

Concrete configuration values, image registry access, license keys, and migration support are all part of the enterprise engagement. The high-level shape:

AI Models​

ZenSearch supports multiple AI providers. You can configure which provider and models to use for chat, agents, and embeddings:

  • Cloud providers — OpenAI, Anthropic, Cohere, Groq
  • Self-hosted models — Ollama, vLLM, or any OpenAI-compatible API endpoint
  • Mix and match — use cloud models for some tasks and local models for others

Embedding models can be configured separately from chat models to optimize cost and performance.

Authentication​

ZenSearch integrates with your existing identity provider — OIDC (Keycloak, Auth0, Okta, Azure AD, …), SAML enterprise SSO, or the managed Clerk service. See Authentication for the full configuration reference.

Connectors​

Deploy only the connectors your organization needs. Each connector is configured with credentials for the target data source and can be enabled, paused, or removed at any time through the dashboard. See OAuth Client Setup for the upstream client-app registration steps.

Guardrails​

Guardrails are configured per-team through the dashboard. Features include prompt injection detection, PII detection and filtering, hallucination detection (lexical, semantic, hybrid), toxicity filtering, and content moderation.

See Guardrails for configuration details.

Observability — Distributed Tracing​

ZenSearch services are instrumented with OpenTelemetry and can export traces to any OTLP-compatible backend (Grafana Tempo, Jaeger, Honeycomb, Datadog, etc.). Enabling tracing gives you end-to-end visibility into a request as it flows through core-api, the Model Gateway, agents, and downstream providers.

Enable on the Core API and Model Gateway:

OTEL_ENABLED=true
OTEL_EXPORTER_ENDPOINT=tempo:4318   # or your OTLP HTTP collector
OTEL_EXPORTER_TYPE=otlp             # use "stdout" for local development

Both services auto-set their service.name attribute, so traces are pre-grouped in your backend.

Security​

Encryption​

  • All stored credentials (API keys, OAuth tokens) are encrypted at rest
  • TLS is supported for all inter-service communication in production
  • Database connections support SSL/TLS

Network Security​

  • AI model routing is internal-only and never exposed externally
  • Use a reverse proxy (Nginx, Traefik, Caddy) to terminate TLS for the web UI and API
  • Configure CORS to only allow your production domain
  • Internal services communicate on an isolated network

Access Control​

  • Role-based access control (Owner, Admin, Editor, Viewer)
  • Document-level permissions synced from source platforms
  • Search-time permission enforcement — users only see content they're authorized to access

Upgrading​

ZenSearch releases are delivered as updated container images. The upgrade process:

  1. Pull the latest images
  2. Database migrations run automatically on startup
  3. Restart services
  4. Verify health via the dashboard

Zero-downtime upgrades are supported on Kubernetes deployments.

Enterprise Getting Started​

Enterprise customers receive:

  • License key for on-premise deployment
  • Private deployment guide with step-by-step instructions
  • Container registry access for all platform images
  • Dedicated support from our engineering team

Contact [email protected] to discuss your on-premise deployment requirements.