# HelixML

> AI agent orchestration platform. Build AI agents with skills, knowledge, sandboxes, and integrations.

## Docs

- [Getting Started](https://helix.ml/docs): Documentation for HelixML.
- [Projects & Spec Tasks](https://helix.ml/docs/projects): Projects and spec tasks are the core of HelixML. This is how work is planned and executed.
- [Agents](https://helix.ml/docs/agents): Build AI agents with skills, knowledge, and integrations.
- [Sandboxes](https://helix.ml/docs/sandboxes): Isolated desktop environments for AI coding agents.
- [Code Intelligence](https://helix.ml/docs/code-intelligence): Deep code understanding powered by Kodit. Semantic search, codebase navigation, and context-aware agent workflows.
- [Mac App](https://helix.ml/docs/macos): Run dozens of AI agent desktops on your own Mac — GPU-accelerated, credentials and dev data stay local, your choice of AI provider.
- [Helix Cloud](https://helix.ml/docs/helix-cloud): Managed Helix service with sandboxes, authentication, and infrastructure handled for you.
- [Linux & Kubernetes](https://helix.ml/docs/linux-kubernetes): Install Helix on a Linux server or Kubernetes cluster.
- [Sovereign Server](https://helix.ml/docs/sovereign-server): A 4U rack server with 8× NVIDIA RTX 6000 Pro GPUs and 768 GB VRAM, Helix preloaded. Ship it to your data centre, power it on, run hundreds of concurrent AI agents with zero cloud dependency.
- [Kodit (Open-Source)](https://helix.ml/docs/kodit): Code and Document Indexing Server

---

## What is HelixML?

Helix is a batteries-included platform for building, running and managing AI agents. It can do everything
from working as a simple self-hosted ChatGPT alternative to working as a controlplane for your fleet of agents.

![Helix Code](/images/helix-code.svg)

## Features

- Kanban style board to manage your project backlog, automatically picking up new work 
- Agent sandboxes with full desktop
- Integration with all major LLM providers (Anthropic, OpenAI, Google, etc.)
- Integration with all majors source control providers (GitHub, GitLab, Bitbucket)
- Full planning -> implementation -> review -> pull request -> merge workflow

## Use cases

- Accelerate development of any project
- Internal knowledge base for your team
- Automated customer support
- Closed self-improvement loop through support -> tickets -> spec tasks -> fixes

---

## Projects

Projects are spec-driven project management boards that organize how work gets planned and executed by AI agents. Each project acts as a workspace where you define what needs to be built, track progress across tasks, and review the results — all through a structured, approval-based workflow.

![Projects board showing spec tasks organized by status](/images/projects.png)

Project provide:
- Ability to collaborate with your team
- Manage spec tasks
- Setup Optimus, a Helix agent to help you plan and manage your project
- Setup recurring tasks such as reviewing your GitHub issues and preparing new spec tasks to work on

## Spec Tasks

A spec task is a discrete unit of work within a project. You describe what needs to happen — a feature to build, a bug to fix, a change to make — and an agent prepares an execution plan. Once you approve the plan, the agent carries out the work inside an isolated sandbox environment, producing a pull request for human review.

Spec tasks move through a clear lifecycle:

- **Define**: Write a spec describing the desired outcome
- **Plan**: An agent analyzes the codebase and proposes an execution plan
- **Approve** Review the plan and approve it before any work begins
- **Implementation**: The agent works inside a sandbox desktop with full access to browser, terminal, and file system
- **Review**: A pull request is created for human review and merge

![Spec task detail view showing the execution plan and status](/images/spec_tasks.png)

This human-in-the-loop approach keeps you in control. Agents never push code or merge changes without your explicit approval. You set the direction, agents handle the execution, and you review the output.


## Jump in at any step

You can always participate in the process at any step. You can review the plan, approve it, or even edit the spec to make changes. You can also review the implementation and make changes to the spec based on the implementation.

![Collaborate on the spec task](/images/spec_task_detail.png)

Interact with this desktop view directly, use the browser, IDE and terminals inside the sandbox.

---

Helix agents combine language models with skills, knowledge bases, and external integrations. An agent receives a user message, decides which tools to use, executes them, and synthesizes a response.

## How Agents Work

When a user sends a message, the agent:

1. Loads the assistant configuration (model, system prompt, skills)
2. Queries relevant knowledge bases for context
3. Calls the LLM with available tools exposed as OpenAI function calls
4. Executes any tools the LLM decides to use (in parallel if multiple)
5. Adds results to the conversation and repeats until done

Agents iterate up to a configurable maximum (default 10) before stopping to prevent runaway loops.

## Skills

Skills are capabilities you attach to an agent. Each skill exposes one or more tools the LLM can invoke.

### Built-in Skills

| Skill | Description |
|-------|-------------|
| **Web Search** | Search the internet and browse results |
| **Browser** | Open URLs and extract content as markdown |
| **Knowledge** | Query RAG sources for document retrieval |
| **API Calling** | Execute REST APIs defined with OpenAPI schemas |
| **Calculator** | Perform mathematical operations |
| **Memory** | Persist information across sessions |
| **MCP** | Connect to Model Context Protocol servers |

### Enabling Skills

Skills are enabled in the assistant configuration:

```yaml
assistants:
- name: Research Assistant
  model: qwen3:8b
  system_prompt: You help users research topics.

  web_search:
    enabled: true
    max_results: 10

  browser:
    enabled: true
    markdown_post_processing: true

  calculator:
    enabled: true
```

## Knowledge

Knowledge bases provide RAG (retrieval augmented generation) for your agents. When attached to an assistant, knowledge becomes a tool the agent can query.

```yaml
assistants:
- model: qwen3:8b
  knowledge:
  - name: product-docs
    description: Product documentation and API reference
    source:
      web:
        urls:
        - https://docs.example.com/
        crawler:
          enabled: true
    rag_settings:
      results_count: 8
      chunk_size: 2048
```

Knowledge sources can be:

- **Web URLs** with optional crawling
- **Uploaded files** (PDF, DOCX, PPTX)
- **Inline content** (text directly in config)
- **S3 buckets**
- **Google Drive**

Knowledge can refresh on a schedule:

```yaml
knowledge:
- name: news-feed
  refresh_enabled: true
  refresh_schedule: "0 */6 * * *"  # Every 6 hours
  source:
    web:
      urls:
      - https://news.example.com/feed
```

## API Integrations

Connect agents to REST APIs using OpenAPI schemas. The agent can call endpoints based on user requests.

```yaml
assistants:
- model: qwen3:8b
  apis:
  - name: Weather API
    description: Get current weather and forecasts
    url: https://api.weather.example.com
    schema: |
      openapi: 3.0.0
      info:
        title: Weather API
        version: 1.0.0
      paths:
        /current:
          get:
            summary: Get current weather
            parameters:
            - name: city
              in: query
              required: true
              schema:
                type: string
```

For APIs requiring authentication, use OAuth providers:

```yaml
apis:
- name: GitHub
  url: https://api.github.com
  schema: ./github-openapi.yaml
  oauth_provider: github
  oauth_scopes:
  - repo
  - read:user
```

## MCP Servers

Model Context Protocol (MCP) lets agents connect to external tool servers. Any MCP-compatible server exposes its tools to your agent.

```yaml
assistants:
- model: qwen3:8b
  mcps:
  - name: Database Tools
    description: Query and manage database records
    url: https://mcp.example.com/tools
    headers:
      Authorization: Bearer ${MCP_API_KEY}
```

MCP servers can also use OAuth for authentication:

```yaml
mcps:
- name: Salesforce
  url: https://mcp.salesforce.example.com
  oauth_provider: salesforce
  oauth_scopes:
  - api
  - refresh_token
```

## Triggers

Agents can be triggered from various sources beyond the chat UI:

### Discord

```yaml
triggers:
- discord:
    server_name: My Server
    channel_names:
    - support
    - general
```

### Slack

```yaml
triggers:
- slack:
    bot_token: ${SLACK_BOT_TOKEN}
    channels:
    - C01234567
```

### Scheduled (Cron)

```yaml
triggers:
- cron:
    schedule: "0 9 * * 1-5"  # 9am weekdays
    input: Generate the daily report
```

### Webhooks

Agents expose webhook endpoints that can be called by external systems to trigger conversations.

## Secrets

Store sensitive values as secrets rather than hardcoding them:

```yaml
assistants:
- model: qwen3:8b
  apis:
  - name: Internal API
    url: https://api.internal.example.com
    headers:
      X-API-Key: ${INTERNAL_API_KEY}
```

Secrets are configured in the Helix UI under the app settings, or via the `secrets` field in the app configuration.

## Agent Types

Helix supports different agent execution modes:

| Type | Description |
|------|-------------|
| **helix_basic** | Simple chat assistant without tool calling |
| **helix_agent** | Standard agent with skills and tool calling |
| **zed_external** | Runs in isolated desktop environment with Zed IDE (Helix Code) |

Set the agent type in the assistant configuration:

```yaml
assistants:
- model: qwen3:8b
  agent_type: helix_agent
  max_iterations: 20
```

For Helix Code sandboxes, use `zed_external`:

```yaml
assistants:
- model: claude-sonnet-4-20250514
  agent_type: zed_external
  generation_model_provider: anthropic
```

## Example: Full Agent Configuration

```yaml
name: Customer Support Agent
description: Handles customer inquiries with access to docs and CRM

assistants:
- name: Support
  model: qwen3:8b
  system_prompt: |
    You are a helpful customer support agent. Use the knowledge base
    to answer product questions and the CRM API to look up customer
    information when needed.

  temperature: 0.3
  max_iterations: 15

  knowledge:
  - name: help-docs
    description: Product documentation and FAQs
    source:
      web:
        urls:
        - https://help.example.com/
        crawler:
          enabled: true
          max_depth: 3

  apis:
  - name: CRM
    description: Look up customer records and order history
    url: https://crm.example.com/api
    schema: ./crm-openapi.yaml
    oauth_provider: internal-sso

  web_search:
    enabled: true

triggers:
- slack:
    bot_token: ${SLACK_BOT_TOKEN}
    channels:
    - support-requests
- cron:
    schedule: "0 8 * * 1"
    input: Generate weekly support summary
```

---

Helix Code provides isolated desktop environments where AI coding agents work autonomously. Each agent runs in its own containerized Linux desktop with a full IDE, and you watch their progress via real-time video streaming in your browser.

See also the [Coding Agents overview](/docs/agents) for how sandboxes fit into the broader agent workflow.

## How It Works

Each agent session receives its own containerized environment with:

- **Isolated Linux desktop** running on Wayland (Sway) or X11 (GNOME)
- **Zed IDE** - a Rust-based editor with native GPU rendering
- **AI agent** - powered by Claude, Qwen, or other LLMs via the Helix proxy
- **WebSocket streaming** - H.264 video streamed to your browser over standard HTTPS

The Helix control plane manages orchestration, knowledge sources, and conversation history through the UI.

## Architecture

Helix Code uses a three-tier isolation model for security and multi-tenancy:

```
+--------------------------------------------+
|                HOST MACHINE                |
|  +--------------------------------------+  |
|  |         Helix Control Plane          |  |
|  |   (API Server, Frontend, Postgres)   |  |
|  +-----------------+--------------------+  |
|                     |                      |
|  +-----------------v--------------------+  |
|  |       HELIX-SANDBOX CONTAINER        |  |
|  |          (Docker-in-Docker)          |  |
|  |  +--------------------------------+  |  |
|  |  |             HYDRA              |  |  |
|  |  |    (Multi-Tenant Isolation)    |  |  |
|  |  |   Isolated dockerd + network   |  |  |
|  |  +-------+----------------+-------+  |  |
|  |          |                |          |  |
|  |    +-----v----+     +-----v----+     |  |
|  |    | Ubuntu   |     | Ubuntu   |     |  |
|  |    | Session  |     | Session  | ... |  |
|  |    | with AI  |     | with AI  |     |  |
|  |    +----------+     +----------+     |  |
|  +--------------------------------------+  |
|                     |                      |
|           WebSocket Video Stream           |
|            (H.264 over HTTPS)              |
|                     v                      |
|                  Browser                   |
+--------------------------------------------+
```

**Hydra** manages multi-tenant isolation within the sandbox. Each concurrent session gets its own Docker daemon with isolated networking (separate bridge networks with non-overlapping subnets). Sessions cannot see each other's containers or network traffic.

## Features

### AI Agent Integration

Agents connect to Zed IDE via WebSocket and can use any LLM provider configured in Helix:

- Anthropic Claude (Sonnet, Opus)
- OpenAI GPT-4
- Local models via Helix runners (Qwen, Llama)
- Any OpenAI-compatible API

### Contextual Awareness

Integrate external knowledge sources into agent environments:

- PDFs and documents
- Jira and Confluence
- MCP (Model Context Protocol) servers
- Custom knowledge bases

### Knowledge Aggregation

Conversation histories across all coding sessions are searchable via RAG, enabling knowledge sharing across your team.

### Spec-Driven Workflows

Use Kanban boards to manage agent task specifications before implementation, ensuring agents work on well-defined tasks.

## Installation

### Requirements

- Linux x86_64 (Ubuntu 22.04+ recommended)
- Docker
- (Optional) NVIDIA GPU for hardware video encoding


macOS and Windows are not supported for running sandboxes. The sandbox requires Linux with Docker.


### Quick Start

Run the Helix installer:

```bash
curl -sL -O https://get.helixml.tech/install.sh
chmod +x install.sh
sudo ./install.sh
```

The installer will detect your hardware and configure the sandbox automatically. On systems with NVIDIA GPUs, hardware H.264 encoding provides 60 FPS streaming with minimal CPU overhead.

### Configure Inference Providers

After installation, configure AI providers through **Account** → **AI Providers**:

- Anthropic (Claude)
- OpenAI
- Together AI
- Any OpenAI-compatible API

Or connect a Helix runner with local models for complete data privacy.

## Desktop Environments

Three desktop options are available:

| Environment | Display Server | Best For |
|-------------|----------------|----------|
| **Sway** | Native Wayland | Lightweight, fast startup, lowest resource usage |
| **Ubuntu** | GNOME (Xwayland) | Full desktop experience, broader app compatibility |
| **Zorin** | GNOME (Xwayland) | User-friendly interface |

Each desktop includes:
- Zed IDE with AI agent integration
- Firefox browser
- Docker CLI
- Git

## Use Cases

### Autonomous Development

Agents work asynchronously on tasks while you focus on other work. Review results when ready rather than waiting for completions.

### Fleet Management

Manage multiple concurrent agent tasks across your team. Track progress, review outputs, and coordinate work through the Kanban board.

### Cloud Development Environments

Persistent development environments that survive disconnections. Pick up where you left off from any device with a browser.

### Security

Each agent runs in its own isolated container with:
- Separate filesystem (no access to host)
- Isolated network (no cross-session traffic)
- Dedicated Docker daemon (via Hydra)

Code execution is contained within the session. Even if an agent runs malicious commands, the blast radius is limited to that session's container.

## Getting Started

1. Install Helix with the installer script
2. Access the Helix UI at your deployment URL
3. Go to **Helix Code** and create a new session
4. Send a message to start the agent working
5. Watch the agent's desktop in real-time via the video stream

---

Helix Code Intelligence, powered by our open source library Kodit, is a global code index. It gives both users and coding assistants an appreciation of external codebases.  Agents can navigate enterprise architectures like experienced developers.

## Why It Matters

Agents working without code intelligence waste tokens re-reading files, miss relevant context, and make changes that break downstream consumers. Kodit eliminates this by giving every agent the structural understanding it needs upfront.

Coding assistants repeatedly rewrite functionality that already exists in organizational libraries and even the same codebase. Code intelligence reduces duplication by surfacing reusable code.

In our experiments, code intelligence improves agentic coding performance on the SWE-bench benchmark by 20%.

## How It Works

Helix Code Intelligence uses Kodit to build a structured representation of internal and external repositories. When an agent needs to write code, instead of guessing, it can search for relevant snippets, read API documentation and understand architecture. Kodit provides precise, context-aware responses to adopt and unify organisational patterns and prevent duplication. It prevents coding assistants reimplementing functionality that exists elsewhere in the codebase or the organisation.

Kodit is also useful for humans. Helix Code Intelligence provides a dynamic wiki, built from the underlying code, to give you greater understanding of a repository if you need to learn more.

Helix Code Intelligence has full integration with Helix and indexes your Projects and Repositories out-of-the-box.

## Key Capabilities

- **Semantic and keyword code search** - find code by intent and keywords
- **Global bash-like tools** - org-wide ls and grep functionality
- **Cross-language support** - indexing pipelines that work with your code and your documentation
- **External MCP access** - give local IDEs the power of code intelligence
- **Automated wiki generation** - unify repository documentation _and_ keep it up to date
- **Internal & external** - works with private or public repositories

---

Don't have Apple Silicon? Try [Helix Cloud](https://app.helix.ml) or see [Linux & Kubernetes docs](/docs/linux-kubernetes).

## Overview

Run the entire Helix platform locally on your Mac. The Mac app gives you a private, offline-capable AI agent stack powered by Apple Silicon — no cloud dependency required.

## Download



## Supported Hardware

Helix runs on **any Apple Silicon Mac** (M1 and later) with **16 GB+ unified memory** — MacBook Air, MacBook Pro, Mac Mini, Mac Studio, Mac Pro.

More unified memory = more agent desktops running simultaneously. 32 GB+ recommended for heavier workloads.

## What You Get

- Up to 15 isolated agent desktop environments running simultaneously
- GPU-accelerated 4K streaming via Apple Silicon
- LAN sharing — give your team access without exposing anything to the internet
- Full Helix controlplane running locally
- Credentials and development data stay on your machine — SSH keys, `.env` files, tokens, database credentials never leave your hardware
- Use your API key or Claude subscription for best-in-class inference, or run fully local with Ollama on 64 GB+ unified memory — toggle wifi off and everything still works
- For stronger local models that rival Claude and GPT, graduate to a [Sovereign Server](/docs/sovereign-server) or your own GPUs

## Requirements

- macOS 14 (Sonoma) or later
- Apple Silicon (M1 or newer)
- Minimum 16 GB unified memory (32 GB+ recommended)

## Licensing

The Mac App requires a license at **$299/year**. You can purchase one from your [Account page](/account/licenses).

A license includes:
- Unlimited agent desktops (hardware permitting)
- All updates for the license period
- Email support

---

## Overview

Helix Cloud is the fastest way to get started. We manage the infrastructure, sandboxes, authentication, and scaling — you focus on building with AI agents.

## Getting Started

1. Sign up at [app.helix.ml](https://app.helix.ml)
2. Create your first project
3. Define spec tasks and let agents do the work

No installation, no infrastructure, no maintenance.

## What's Included

- **Managed Sandboxes** — isolated desktop environments provisioned on demand
- **Authentication** — built-in user management and team access controls
- **Automatic Scaling** — infrastructure scales with your workload
- **All LLM Providers** — access to Anthropic, OpenAI, Google, and more out of the box
- **Source Control Integration** — connect GitHub, GitLab, or Bitbucket in one click

## Plans

Helix Cloud is available on **Pro** and **Business** plans. Both include a 14-day free trial. See [Pricing](/pricing) for details.

---

## Licensing

A license is required to run Helix on Linux or Kubernetes.

- **Developer license**: For individuals, testing, and businesses with less than $10M annual revenue or fewer than 250 employees. [Buy a developer license →](/account/licenses)
- **Enterprise license**: For larger organizations with full RBAC, SSO, SOC 2 Type II, and dedicated onboarding. [Enterprise licensing →](/account/enterprise)

Helix runs on any Kubernetes cluster - whether that's on your own bare metal, a European cloud provider like [Hetzner](https://www.hetzner.com/) or [OVH](https://www.ovhcloud.com/), or a major cloud platform like AWS (EKS), Google Cloud (GKE), or Azure (AKS). If you can run containers, you can run Helix.

For organisations focused on [digital sovereignty](/use-cases/digital-sovereignty), we also offer a [turnkey Sovereign Server](/docs/sovereign-server) - a 4U rack server with Helix pre-installed, shipped to your data centre.

## Local Setup

To install Helix on your own Linux server with Nvidia/AMD GPU support, run the following command:

```bash
curl -sL -O https://get.helixml.tech/install.sh && bash install.sh
```

## Kubernetes Setup

### Helm charts

Helix ships as **two separate Helm charts**, both published to `https://charts.helixml.tech`:

| Chart | Purpose | Required? |
|---|---|---|
| `helix-controlplane` | Main Helix API, UI, RAG, and orchestration. This is what users log in to. | **Yes** |
| `helix-sandbox` | Docker-in-Docker host for desktop agents, Zed sessions, and spec tasks (cloud desktops with GPU video streaming). | **Recommended.** Required if you use desktop or agent features. |

Inference is delivered by external providers (OpenAI, Anthropic, Together, or any OpenAI-compatible endpoint such as a self-hosted vLLM). There is no separate runner chart: configure providers under `controlplane.providers.*` as shown below.

The sections below cover the install for both charts.

### Prerequisites

- A Kubernetes cluster (1.28+). Managed control planes (AKS/EKS/GKE) are fine; the sandbox chart requires privileged pods, so AKS/EKS/GKE **Autopilot** is not supported.
- `kubectl` and `helm` 3.x on your workstation.
- A Helix license key from [your account](/account/licenses).
- A `StorageClass` that supports `ReadWriteOnce` persistent volumes. The control plane chart provisions several PVCs (main Postgres, pgvector, kodit-vectorchord, controlplane data).
- For a minimal control-plane-only install, budget **~8 vCPU / 24 GiB RAM** of worker capacity. The control plane pod ships with a Haystack sidecar that loads a ~4 GB embedding model on first start.
- An LLM provider (OpenAI, Anthropic, Together, or any OpenAI-compatible endpoint such as a self-hosted vLLM). Without one, there will be no models available after first login.

### Cloud quotas

On a fresh Azure/AWS/GCP subscription, most GPU SKU families have quota 0 by default. Before starting:

- **AWS**: `g5`/`p4d` EC2 quotas per region.
- **Azure**: `NVadsV710v5` (AMD V710) or `NC*`/`ND*` (NVIDIA) families, plus "Total Regional vCPUs".
- **GCP**: `nvidia-*` GPU quotas per region.

### Create secrets

Replace `<paste-your-license-key>` with the key from [your account](/account/licenses). Generate real random values for the postgres password, runner token, and encryption key; the example commands below produce them inline.

```bash
# Create namespace and secrets
kubectl create namespace helix
kubectl config set-context --current --namespace=helix

# Postgres credentials for the bundled Postgres pod (or an external instance).
kubectl create secret generic postgresql-auth-secret \
  --from-literal=username="helix" \
  --from-literal=password="$(openssl rand -hex 16)" \
  --from-literal=database="helix"

kubectl create secret generic pgvector-auth-secret \
  --from-literal=username="postgres" \
  --from-literal=password="" \
  --from-literal=database="postgres"

kubectl create secret generic helix-pgvector-creds \
  --from-literal=dsn="postgresql://postgres:@my-helix-controlplane-pgvector:5432/postgres"

kubectl create secret generic helix-license \
  --from-literal=license-key="<paste-your-license-key>"

# Encryption key for secrets at rest (PATs, SSH keys, OAuth tokens).
# Must be a 64-character hex string (32 bytes for AES-256-GCM). DO NOT
# rotate this once data has been written - rotating invalidates every
# stored secret.
kubectl create secret generic helix-encryption-key \
  --from-literal=encryption-key="$(openssl rand -hex 32)"

# Random token, used by the sandbox chart to auth back to the control plane.
kubectl create secret generic helix-runner-secrets \
  --from-literal=api-token="$(openssl rand -hex 32)"
```

### Configure values.yaml

Save this as `values.yaml` for the chart:

```yaml
# Production-ready configuration for helix-controlplane
# For more options: https://github.com/helixml/helix/blob/main/charts/helix-controlplane/values-example.yaml

global:
  # Public URL of your Helix deployment. Also injected into the desktop
  # sandbox containers as the URL their inner agent (Zed / Qwen Code)
  # uses to reach the control plane API. The default of
  # http://localhost:8080 is ONLY correct for a single-binary local
  # install - inside a Kubernetes cluster localhost resolves to the
  # sandbox pod itself and inference will fail with
  # "error sending request for url (http://localhost:8080/...)".
  #
  # In Kubernetes set this to either:
  #   - the cluster-internal service URL of the control plane, e.g.
  #     http://my-helix-controlplane.helix.svc.cluster.local
  #     (works for port-forward / private access)
  #   - or your public ingress hostname, e.g. https://helix.example.com
  serverUrl: http://my-helix-controlplane.helix.svc.cluster.local

# Leave image.tag unset so the chart uses its pinned appVersion.
# Do NOT set it to "latest" - no :latest tag is published to GHCR.
# To pin a specific release, use e.g. tag: "2.9.31".

searxng:
  enabled: true

chrome:
  enabled: true

pgvector:
  enabled: true
  auth:
    existingSecret: "pgvector-auth-secret"
    usernameKey: "username"
    passwordKey: "password"
    databaseKey: "database"
  persistence:
    enabled: true
    size: 50Gi
    storageClass: ""
    annotations: {}
    accessModes:
      - ReadWriteOnce

controlplane:
  licenseKeyExistingSecret: "helix-license"
  licenseKeyExistingSecretKey: "license-key"

  runnerTokenExistingSecret: "helix-runner-secrets"
  runnerTokenExistingSecretKey: "api-token"

  # Encryption key for secrets at rest (PATs, SSH keys, OAuth tokens).
  # Required - the API will refuse to start without it. Generated above
  # via `openssl rand -hex 32`. Do not rotate after data is written.
  encryptionKeyExistingSecret: "helix-encryption-key"
  encryptionKeyExistingSecretKey: "encryption-key"

  admin:
    userSource: "env"
    userIds: "all"

  haystack:
    enabled: true
    existingSecret: "helix-pgvector-creds"
    existingSecretDsnKey: "dsn"
    embeddingsModel: "MrLight/dse-qwen2-2b-mrl-v1"
    embeddingsDim: "1536"
    chunkSize: "1000"
    chunkOverlap: "50"
    chunkUnit: "word"

  rag:
    defaultProvider: "haystack"
    embeddingsProvider: "helix"

  inference:
    defaultProvider: "helix"

  fineTuning:
    defaultProvider: "helix"

  # Configure at least one LLM provider. Without this, there will be
  # no models available after first login. Provide an API key inline,
  # or reference a Kubernetes secret via controlplane.providers.<name>.apiKeyExistingSecret.
  # providers:
  #   anthropic:
  #     apiKey: "sk-ant-..."
  #   openai:
  #     apiKey: "sk-..."

  # Extra environment variables injected into the control plane pod.
  # The control plane process is where settings like HELIX_ENCODER
  # are read and forwarded to inner desktop containers spawned for
  # spec task / Zed agent sessions.
  #
  # Example: opt into hardware H.264 video encoding on AMD GPUs
  # (requires Helix 2.10.0+; no-op on 2.9.x). Default auto-detect uses
  # software OpenH264 on AMD because of a historical gst-va crash on
  # older Mesa; this flag bypasses that skip.
  # extraEnv:
  #   - name: HELIX_ENCODER
  #     value: "vaapi"

persistence:
  enabled: true
  size: 100Gi
  storageClass: ""
  accessModes:
    - ReadWriteOnce

volumes:
  - name: data

postgresql:
  enabled: true
  auth:
    existingSecret: "postgresql-auth-secret"
    usernameKey: "username"
    passwordKey: "password"
    databaseKey: "database"
  persistence:
    enabled: true
    size: 10Gi
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      memory: "1Gi"

tika:
  enabled: false

typesense:
  enabled: false
```

#### External Postgres

The chart can use an existing managed Postgres instead of the bundled one, but the bundled **pgvector** sidecar requires the `vectorchord` and `vectorchord-bm25` extensions. Managed services that ship stock Postgres (Azure Flexible Server, AWS RDS, Cloud SQL) do **not** include these extensions out of the box, so keep `pgvector.enabled: true`. That pod will host the RAG vector index independently of wherever your main Postgres lives.

### Install the control plane

```bash
# Add Helix Helm repository
helm repo add helix https://charts.helixml.tech
helm repo update

# Install the control plane with your generated values.yaml and secrets.
# By default the chart uses its pinned appVersion. Do NOT set image.tag
# to "latest" - no :latest tag is published. To pin a specific release,
# add --set image.tag="<version>" (e.g. "2.9.31") or --version "<chart-version>".
helm upgrade --install my-helix-controlplane helix/helix-controlplane \
  -f values.yaml
```

First boot pulls the embedding model (~4 GB) into the Haystack sidecar; budget 5 to 10 minutes before the main pod becomes Ready.

### External inference providers

Helix can route inference to external providers (OpenAI, Anthropic, Together, or any self-hosted OpenAI-compatible endpoint like vLLM) instead of running a local runner. Each provider is configured under `controlplane.providers.*` in the control-plane values. Use `existingSecret` for API keys so they stay out of your values file and git history.

First, create a Kubernetes Secret for each provider you want to use:

```bash
kubectl create secret generic openai-api-key \
  --from-literal=api-key="sk-..."

kubectl create secret generic anthropic-api-key \
  --from-literal=api-key="sk-ant-..."

kubectl create secret generic togetherai-api-key \
  --from-literal=api-key="..."
```

Then add a `providers:` block inside the `controlplane:` section of your `values.yaml`. Only include the providers you actually use:

```yaml
controlplane:
  # ... your existing controlplane config ...
  providers:
    openai:
      existingSecret: "openai-api-key"
      existingSecretApiKeyKey: "api-key"
      # baseUrl: "https://api.openai.com/v1"   # override for Azure OpenAI or proxies

    anthropic:
      existingSecret: "anthropic-api-key"
      existingSecretApiKeyKey: "api-key"

    togetherai:
      existingSecret: "togetherai-api-key"
      existingSecretApiKeyKey: "api-key"

    vllm:
      # Self-hosted vLLM speaks the OpenAI API. Point at its cluster-internal service.
      # Most vLLM deployments need no API key; pass one via existingSecret if yours does.
      baseUrl: "http://my-vllm.vllm.svc.cluster.local:8000/v1"
```

Anthropic can also be used via GCP Vertex AI - set `vertexProjectID`, `vertexRegion`, and either `vertexCredentialsJSON` or `vertexCredentialsSecret` under `providers.anthropic`. See `values.yaml` in the chart for the full shape.

Re-run `helm upgrade` on the control plane to apply the change.

### Install the sandbox chart (cloud desktops / Zed agent)

The `helix-sandbox` chart powers Helix's cloud desktop and in-browser Zed IDE features. It is optional; install it only if you want to run spec tasks or open the IDE in the browser.

The sandbox runs a Docker-in-Docker daemon which needs privileged pods, a GPU node pool (for desktop rendering), and large persistent volumes.

```bash
helm upgrade --install my-helix-sandbox helix/helix-sandbox \
  --namespace helix \
  --set sandbox.apiUrl="http://my-helix-controlplane.helix.svc.cluster.local" \
  --set sandbox.runnerTokenExistingSecret=helix-runner-secrets \
  --set sandbox.runnerTokenExistingSecretKey=api-token
```

Per-cloud override values are shipped with the chart: [values-aks.yaml](https://github.com/helixml/helix/blob/main/charts/helix-sandbox/values-aks.yaml), [values-eks.yaml](https://github.com/helixml/helix/blob/main/charts/helix-sandbox/values-eks.yaml), [values-gke.yaml](https://github.com/helixml/helix/blob/main/charts/helix-sandbox/values-gke.yaml), [values-bare-metal.yaml](https://github.com/helixml/helix/blob/main/charts/helix-sandbox/values-bare-metal.yaml).

### Access the control plane

```bash
kubectl port-forward -n helix svc/my-helix-controlplane 8080:80
```

Then open [http://localhost:8080](http://localhost:8080). The first registered user becomes an admin (because of `controlplane.admin.userIds: "all"`).

For a production deployment you should configure an ingress with TLS termination and set `global.serverUrl` to the public URL. See the [values-example.yaml](https://github.com/helixml/helix/blob/main/charts/helix-controlplane/values-example.yaml) for nginx + cert-manager, GKE managed-certificate, and cert-manager + DNS-01 examples.

### Environment variables

Most options have first-class chart values - reach for those before resorting to env vars. The variables in this section are operator-tunable runtime knobs that don't have a structured chart key. They're passed through one of three `extraEnv` lists, depending on which component reads them:

| Scope | Where it's set | Applies to |
|---|---|---|
| `global.extraEnv` | helix-controlplane chart | controlplane + chrome + searxng pods. Use this for cluster-wide settings like `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` that every outbound HTTP client needs. |
| `controlplane.extraEnv` | helix-controlplane chart | controlplane pod only. Use this for desktop-bridge tunables (forwarded into dev containers) and control-plane process flags. |
| `sandbox.extraEnv` | helix-sandbox chart | sandbox pod only. Use this for hydra-side flags read inside the sandbox before the dev container starts. |

```yaml
# helix-controlplane values.yaml
global:
  extraEnv:
    - name: HTTPS_PROXY
      value: "http://proxy.internal:8080"
    - name: NO_PROXY
      value: "localhost,127.0.0.1,.svc,.cluster.local"

controlplane:
  extraEnv:
    - name: HELIX_VIDEO_MODE
      value: shm
```

Re-run `helm upgrade` after changing any of these. The desktop-bridge env vars (video mode, encoder, GOP, render node) are read when a new dev container is created, so existing spec-task sessions keep their old values - start a new session to pick up the change.

#### Desktop streaming (`controlplane.extraEnv`)

These are read inside each spec-task / dev container by `desktop-bridge`. Helix 2.11.3+ forwards them from the controlplane env into dev containers automatically.

| Variable | Default | Notes |
|---|---|---|
| `HELIX_VIDEO_MODE` | `zerocopy` | PipeWire capture path: `zerocopy` (DMA-BUF -> CUDA, fastest), `native` (DMA-BUF via GStreamer 1.24+), or `shm` (shared memory, slower but most compatible). Set to `shm` if the browser shows endless reconnects and `desktop-bridge` logs `failed to set pipeline to playing` after `Received CUDA context via set_context` - typically seen on managed-GPU clusters where the DMA-BUF -> CUDA import fails (e.g. GKE T4). NVENC is still used for the encode, so quality is unchanged. |
| `HELIX_ENCODER` | auto-detect | H.264 encoder selection: `nvenc` (NVIDIA), `vaapi` / `vaapi-legacy` (Intel/AMD), `openh264` / `x264` (software fallback). Useful when auto-detect picks the wrong encoder for your hardware. |
| `HELIX_GOP_SIZE` | `120` | GOP (Group of Pictures) size in frames. Default is 2 seconds at 60fps. Lower values make mid-stream joins faster (less catchup data) at the cost of slightly larger bitrate. |
| `HELIX_RENDER_NODE` | unset | VA-API render device path (e.g. `/dev/dri/renderD129`). Set explicitly on multi-GPU hosts where auto-detection picks the wrong one. Set to `SOFTWARE` to disable VA-API. |

#### Control plane behaviour (`controlplane.extraEnv`)

| Variable | Default | Notes |
|---|---|---|
| `HELIX_DISABLE_VERSION_CHECK` | unset | Set to any non-empty value to disable the upstream version-check ping on startup. Useful in air-gapped deployments. |
| `HELIX_SKIP_AUTOMIGRATE` | unset | Set to `1` to skip GORM AutoMigrate on the public schema at boot. Only set this if you migrate the schema out-of-band - otherwise the control plane may crash on schema-mismatch errors. |

#### Sandbox host (`sandbox.extraEnv`)

These are read by hydra inside the sandbox pod, before the dev container starts. Requires Helix 2.11.3+ for the `sandbox.extraEnv` plumbing.

| Variable | Default | Notes |
|---|---|---|
| `HELIX_SANDBOX_APT_MIRROR` | unset | Override the Debian/Ubuntu APT mirror used when bootstrapping dev container images. Useful in air-gapped or geo-restricted environments. |

---

## Overview

We ship a fully configured 4U rack server to your data centre with Helix pre-installed and ready to run. Plug it in, power it on, and your team has a private AI agent fleet — hundreds of concurrent agents, each with their own GPU-accelerated desktop — with zero cloud dependency. No API keys, no token metering, no data leaving your building.

It's the fastest path to owning your AI stack. No Kubernetes expertise required. No cloud accounts. No configuration. Just hardware, software, and onboarding — in one package.

[Learn why digital sovereignty matters →](/use-cases/digital-sovereignty)

![Sovereign Server — 4U rack server with 8× NVIDIA RTX 6000 Pro GPUs](/images/sovereign-server.png)

**Ready to buy?** [Purchase a Sovereign Server →](/account/sovereign) · [Talk to sales →](/contact)

---

## The hardware

The Sovereign Server is built on the [Gigabyte G494-SB4](https://www.gigabyte.com/Enterprise/GPU-Server/G494-SB4-rev-AAP2) — a 4U GPU-optimised server platform designed for AI workloads.

**Base configuration:**

| Component | Specification |
|---|---|
| **GPUs** | 8× NVIDIA RTX 6000 Pro (Blackwell generation, 96 GB GDDR7 each — 768 GB total VRAM) |
| **CPU** | Dual Intel Xeon 6 Series processors |
| **Memory** | 256 GB+ DDR5 ECC Registered |
| **Storage** | NVMe SSD (configured to workload) |
| **Network** | Dual 10GbE onboard |
| **Power** | Quad 3000W redundant (80+ Titanium) |
| **Form factor** | 4U rackmount, standard 19″ |

Configurations are customisable. We work with you during onboarding to spec the server to your workload — more memory, more storage, different networking — whatever your environment needs.

---

## What's included

**Hardware** — The server itself, fully assembled, tested, and burned in before shipping.

**Software** — Helix pre-installed and configured. The entire stack — inference, RAG, agents, agent desktops, fleet orchestration, observability — ready to go on first boot.

**Onboarding** — A discounted 8-week structured onboarding programme with the Helix team. We help you integrate with your existing git workflows, CI/CD pipelines, SSO provider, and communication tools (Slack/Teams). Weekly check-ins and a final readout.

**First-year license** — Your first year of the Helix enterprise license is included in the price. After year one, you renew annually.

**Warranty** — 3-year return-to-base hardware warranty included. On-site support upgrades available.

---

## The economics

Cloud AI is expensive and getting more expensive. We're hearing from teams spending $3,000 per developer per month on tools like Claude Code and Cursor — and that number keeps climbing. Per-seat and per-token pricing means your costs scale linearly with adoption — exactly when you want your team leaning into AI the hardest.

The Sovereign Server flips that.

**One-time hardware cost, predictable annual licence.** No token metering. No per-API-call billing. No surprise invoices. No vendor deciding to double their prices overnight.

A single Sovereign Server comfortably supports 20–30+ developers and can run hundreds of concurrent AI agents, each with their own GPU-accelerated desktop. 768 GB of VRAM and hardware video encoding — this box has real density.

At typical enterprise AI spend:

| Scenario | Cloud AI (per year) | Sovereign Server (per year) |
|---|---|---|
| **10 developers, $3,000/month each** | $360,000 | Electricity + licence |
| **20 developers, $3,000/month each** | $720,000 | Electricity + licence |
| **30 developers, $3,000/month each** | $1,080,000 | Electricity + licence |

At $3,000/developer/month, **a team of 20 is spending $720,000 per year on cloud AI.** The Sovereign Server pays for itself in under three months — and then keeps running for a decade. Even at more modest usage of $1,000/developer/month, a 20-person team recoups the hardware cost within the first year.

After the hardware cost is recovered, your ongoing costs are predictable: an annual Helix licence with per-seat pricing you negotiate up front — not per-token billing that spikes every time your team leans harder into AI. Want to go all-in? Talk to us about an org-wide unlimited licence. Either way, the compute is already paid for, and you know what you're paying before the year starts.

That's without factoring in the cost of a data breach, a compliance failure, or a vendor pulling the rug on your API access.

---

## Sovereignty by default

The Sovereign Server isn't just cheaper. It's a different architecture.

**Your infrastructure, your jurisdiction.** The server sits in your data centre, in your country, under your legal framework. Not "your region" of someone else's cloud.

**No external API calls.** Every prompt, every response, every document stays on your network. Nothing leaves.

**Open-weight models that rival the best.** Llama, Qwen, Mistral, DeepSeek, Kimi — the latest open-weight models now match or exceed Claude and OpenAI on most benchmarks. You choose which to run. Swap models without asking permission, and verify you're running exactly what you think you're running. No proprietary black boxes — and no reason to settle for less capable models just because you're running locally.

**Works offline, air-gap ready.** Helix is designed to run fully disconnected. There's an optional version-update check, but no mandatory telemetry, no usage data collection, no licence heartbeat. Disconnect the network cable and it keeps running.

**No vendor kill switch.** We can't revoke your access, force a model update, or shut you down because your use case violates an acceptable use policy. The server is yours.

**Full auditability.** Every interaction logged locally. Prompts, responses, user identity, timestamps, model version. Your compliance team gets full visibility.

Cloud AI providers can't offer any of this. Their business model depends on you not having it.

[Read the full digital sovereignty case →](/use-cases/digital-sovereignty)

---

## What you can run

The Sovereign Server runs the full Helix stack. Everything you'd get on Helix Cloud or a self-managed Kubernetes deployment — but on dedicated hardware with no shared tenancy.

- **Private inference** — Run state-of-the-art open-weight LLMs locally with vLLM and Ollama backends. The latest models from Meta, Alibaba, Mistral, and DeepSeek are competitive with Claude and OpenAI on coding, reasoning, and language tasks — and you can run them on your own hardware. OpenAI-compatible API, so your existing integrations work without changes.
- **RAG pipelines** — Text and vision RAG over your internal documents, PDFs, wikis.
- **AI agents** — Autonomous agents with web search, browser, API calling, MCP integration.
- **Agent desktops** — Full GPU-accelerated streaming desktops for every agent. Watch them work, pair-program when they need help.
- **Fleet orchestration** — Spec coding, kanban pipeline, human-in-the-loop review gates. Manage dozens of agents from a single dashboard.
- **Observability & evals** — Full visibility into what your agents are doing and how well they're doing it.

With 8× RTX 6000 Pro GPUs and 768 GB of total VRAM, you can run large models (70B+ parameter) at production throughput while simultaneously running hundreds of concurrent agent desktops. Hardware video encoding means each desktop streams at 60fps with minimal CPU overhead.

**Continuous updates, latest models.** Helix is actively developed — you can upgrade the software at any time to pick up support for new models as they're released. New open-weight models are landing every few weeks, and your server keeps pace. No waiting for a vendor to decide to "support" something. If it runs on your hardware, you can run it.

---

## Easily expandable

The Sovereign Server is a single machine, but it's not a dead end. Helix is designed to scale horizontally.

Need more compute? Just add more servers. Helix's architecture separates the control plane from GPU runners and agent sandboxes — so you can connect additional GPU servers to a single Helix control plane without replacing anything. Your second server doubles your capacity. Your third triples it. Each one slots in alongside the first.

For larger deployments, we recommend moving the Helix control plane onto Kubernetes, which lets you manage a cluster of GPU servers as a single fleet. We can help you configure this — whether that's a handful of rack servers in your data centre or a larger distributed deployment across multiple sites.

Start with one box. Scale when you need to. No rip-and-replace.

---

## Who it's for

**Regulated industries** — Finance, healthcare, legal, defence, government. If you're subject to GDPR, NIS2, DORA, or the EU AI Act, the Sovereign Server gives you compliance by architecture rather than by contract.

**Organisations leaving the cloud** — If you've done the maths on cloud AI spend and decided to bring it in-house, the Sovereign Server is the fastest path. No Kubernetes expertise required.

**Air-gapped environments** — Classified and high-security environments where no outbound network access is permitted. The Sovereign Server runs fully disconnected after initial setup.

**Teams scaling AI adoption** — If your developers are already running AI agents on personal machines and you need to bring that inside your security perimeter with proper controls, this is the enterprise answer.

---

## Pricing

**~$175,000** — broken out: ~$100,000 for the hardware (CyberServe appliance, yours to keep) + $75,000 for the 8-week onboarding pilot and first-year enterprise licence. Helix pre-installed and configured.

Annual licence renewal after year one with per-seat pricing. For larger organisations, ask us about org-wide unlimited licences. [Contact us](/contact) for licence pricing.

Custom configurations available. If you need different GPU specs, more memory, or a multi-server deployment, we'll work with you to spec the right setup.

---

## Get started

Ready to take control of your AI infrastructure?

[Purchase a Sovereign Server →](/account/sovereign)

[Talk to us about a Sovereign Server →](/contact)

Already have your own hardware? You can also deploy Helix on any Linux server or Kubernetes cluster. [See Linux & Kubernetes docs →](/docs/linux-kubernetes)

---

> This page is sourced from the [Kodit GitHub repository](https://github.com/helixml/kodit).





AI coding assistants work better when they have access to real examples from your codebase. Kodit indexes your repositories, splits source files into searchable snippets, and serves them to any MCP-compatible assistant. When your assistant needs to write new code, it queries Kodit first and gets back relevant, up-to-date examples drawn from your own projects.

Kodit also handles documents. PDFs, Word files, PowerPoint decks, and spreadsheets are rasterized and indexed so you can search across both code and documentation in one place.

**What you get:**

- **Multiple search strategies** including BM25 keyword search, semantic vector search, regex grep, and visual document search, each exposed as a separate MCP tool so your assistant picks the right approach for each query
- **MCP server** that works with Claude Code, Cursor, Cline, Kilo Code, and any other MCP-compatible assistant
- **REST API** for programmatic access to search, repositories, enrichments, and indexing status
- **AI enrichments** (optional) including architecture docs, API docs, database schema detection, cookbook examples, and commit summaries, all generated by an LLM
- **Document intelligence** with visual search across PDF pages, Office documents, and images using multimodal embeddings
- **No external dependencies required** for basic operation, with a built-in embedding model and SQLite storage

## Quickstart

### Docker (recommended)

```sh
docker run -p 8080:8080 registry.helix.ml/helix/kodit:latest
```

This starts Kodit with SQLite storage and a built-in embedding model. No API keys needed.

### Pre-built binaries

Download a binary from the [releases page](https://github.com/helixml/kodit/releases), then:

```sh
chmod +x kodit
./kodit serve
```

### Verify it works

Open the interactive API docs at [http://localhost:8080/docs](http://localhost:8080/docs).

Or index a small repository and run a search:

```sh
# Index a repository
curl http://localhost:8080/api/v1/repositories \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "repository",
      "attributes": {
        "remote_uri": "https://gist.github.com/philwinder/7aa38185e20433c04c533f2b28f4e217.git"
      }
    }
  }'

# Check indexing progress
curl http://localhost:8080/api/v1/repositories/1/status

# Search (once indexing is complete)
curl http://localhost:8080/api/v1/search \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "search",
      "attributes": {
        "keywords": ["orders"],
        "text": "code to get all orders"
      }
    }
  }'
```

## Connecting to AI Assistants

Kodit exposes an MCP endpoint at `/mcp`. Connect your assistant to start using Kodit as a code search tool.

### Claude Code

```sh
claude mcp add --transport http kodit http://localhost:8080/mcp
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "kodit": {
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

### Cline

Add to the MCP Servers configuration (Remote Servers tab):

```json
{
  "mcpServers": {
    "kodit": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

### Kilo Code

Add to the MCP configuration (Edit Project/Global MCP):

```json
{
  "mcpServers": {
    "kodit": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp",
      "alwaysAllow": [],
      "disabled": false
    }
  }
}
```

Replace `http://localhost:8080` with your server URL if running remotely.

### Encouraging assistants to use Kodit

Some assistants may not call Kodit tools automatically. Add this to your project rules or system prompt to enforce usage:

```
For every request that involves writing or modifying code, the assistant's first
action must be to call the kodit search MCP tools. Only produce or edit code after
the tool call returns results.
```

In Cursor, save this as `.cursor/rules/kodit.mdc` with `alwaysApply: true` frontmatter.

## MCP Tools

Kodit exposes these tools to connected AI assistants:

| Tool | Description |
|------|-------------|
| `kodit_repositories` | List all indexed repositories |
| `kodit_semantic_search` | Semantic similarity search across code |
| `kodit_keyword_search` | BM25 keyword search |
| `kodit_visual_search` | Search document page images |
| `kodit_grep` | Regex pattern matching |
| `kodit_ls` | List files by glob pattern |
| `kodit_read_resource` | Read file content by URI |
| `kodit_architecture_docs` | Architecture documentation for a repo |
| `kodit_api_docs` | Public API documentation |
| `kodit_database_schema` | Database schema documentation |
| `kodit_cookbook` | Usage examples and patterns |
| `kodit_commit_description` | Commit description |
| `kodit_wiki` | Wiki table of contents |
| `kodit_wiki_page` | Read a specific wiki page |
| `kodit_version` | Server version |

The enrichment tools (`architecture_docs`, `api_docs`, `database_schema`, `cookbook`, `wiki`, `commit_description`) require an LLM provider to be configured. See Enrichment Providers under Configuration Reference.

## Go Library

Kodit can be embedded directly as a Go library. This is how [Helix](https://helix.ml) integrates Kodit into its platform.

```go
import "github.com/helixml/kodit"

client, err := kodit.New(
    kodit.WithSQLite(".kodit/data.db"),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Index a repository
_, _, err = client.Repositories.Add(ctx, &service.RepositoryAddParams{
    URL: "https://github.com/kubernetes/kubernetes",
})

// Search
results, err := client.Search.Query(ctx, "create a deployment",
    service.WithLimit(10),
)

for _, result := range results.Enrichments() {
    fmt.Println(result.Subtype(), result.Content())
}
```

### Library options

| Option | Description |
|--------|-------------|
| `WithSQLite(path)` | Use SQLite for storage |
| `WithPostgresVectorchord(dsn)` | Use PostgreSQL with VectorChord |
| `WithOpenAI(apiKey)` | OpenAI for embeddings and text |
| `WithAnthropic(apiKey)` | Anthropic Claude for text (needs separate embedding provider) |
| `WithTextProvider(p)` | Custom text generation provider |
| `WithEmbeddingProvider(p)` | Custom embedding provider |
| `WithRAGPipeline()` | Skip LLM enrichments, index and search only |
| `WithFullPipeline()` | Require all enrichments (errors without a text provider) |
| `WithDataDir(dir)` | Data directory (default: `~/.kodit`) |
| `WithCloneDir(dir)` | Repository clone directory |
| `WithAPIKeys(keys...)` | API keys for HTTP authentication |
| `WithWorkerCount(n)` | Number of background workers (default: 1) |
| `WithPeriodicSyncConfig(cfg)` | Automatic repository sync settings |

### Search options

| Option | Description |
|--------|-------------|
| `WithSemanticWeight(w)` | Weight for semantic vs keyword search (0.0 to 1.0) |
| `WithLimit(n)` | Maximum number of results |
| `WithOffset(n)` | Offset for pagination |
| `WithLanguages(langs...)` | Filter by programming languages |
| `WithRepositories(ids...)` | Filter by repository IDs |
| `WithMinScore(score)` | Minimum score threshold |
| `WithEnrichmentTypes(types...)` | Filter results to specific enrichment types |
| `WithSnippets(include)` | Include code snippets in results |
| `WithDocuments(include)` | Include enrichment documents in results |

### Go HTTP client

A generated HTTP client is available for calling a remote Kodit server from Go:

```sh
go get github.com/helixml/kodit/clients/go
```

```go
import koditclient "github.com/helixml/kodit/clients/go"

client, err := koditclient.NewClient("https://kodit.example.com")

// List repositories
resp, err := client.GetRepositories(ctx, nil)

// Search
text := "create a deployment"
resp, err := client.PostSearch(ctx, koditclient.PostSearchJSONRequestBody{
    Data: &koditclient.DtoSearchData{
        Attributes: &koditclient.DtoSearchAttributes{
            Text: &text,
        },
    },
})
```

Types are auto-generated from the OpenAPI spec. See the interactive API docs at `/docs` for the full endpoint list.

## Production Deployment

For production use, deploy with PostgreSQL (VectorChord) for scalable vector search and a dedicated LLM provider for enrichments.

### Docker Compose

Save this as `docker-compose.yaml`:

```yaml
services:
  kodit:
    image: registry.helix.ml/helix/kodit:latest
    ports:
      - "8080:8080"
    command: ["serve"]
    restart: unless-stopped
    depends_on:
      - vectorchord
    environment:
      DATA_DIR: /data
      DB_URL: postgresql://postgres:mysecretpassword@vectorchord:5432/kodit

      # Enrichment LLM (optional, enables AI-generated docs)
      ENRICHMENT_ENDPOINT_BASE_URL: http://ollama:11434
      ENRICHMENT_ENDPOINT_MODEL: ollama/qwen3:1.7b

      # External embedding provider (optional, replaces built-in model)
      # EMBEDDING_ENDPOINT_API_KEY: sk-proj-xxxx
      # EMBEDDING_ENDPOINT_MODEL: openai/text-embedding-3-small

      LOG_LEVEL: INFO
      API_KEYS: ${KODIT_API_KEYS:-}
    volumes:
      - kodit-data:/data

  vectorchord:
    image: tensorchord/vchord-suite:pg17-20250601
    environment:
      POSTGRES_DB: kodit
      POSTGRES_PASSWORD: mysecretpassword
    volumes:
      - vectorchord-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  kodit-data:
  vectorchord-data:
```

### Kubernetes

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vectorchord
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vectorchord
  template:
    metadata:
      labels:
        app: vectorchord
    spec:
      containers:
        - name: vectorchord
          image: tensorchord/vchord-suite:pg17-20250601
          env:
            - name: POSTGRES_DB
              value: kodit
            - name: POSTGRES_PASSWORD
              value: mysecretpassword
          ports:
            - containerPort: 5432
---
apiVersion: v1
kind: Service
metadata:
  name: vectorchord
spec:
  selector:
    app: vectorchord
  ports:
    - port: 5432
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kodit
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kodit
  template:
    metadata:
      labels:
        app: kodit
    spec:
      containers:
        - name: kodit
          image: registry.helix.ml/helix/kodit:latest # pin to a specific version
          args: ["serve"]
          env: [] # see Configuration Reference for environment variables
          ports:
            - containerPort: 8080
          readinessProbe:
            httpGet:
              path: /
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: kodit
spec:
  type: LoadBalancer
  selector:
    app: kodit
  ports:
    - port: 8080
```

### Authentication