# HelixML

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

## Docs

- [Overview](https://helix.ml/docs): What Helix is, how it runs, and where to start.
- [Quickstart](https://helix.ml/docs/quickstart): Create an account, connect a repository, run your first spec task, and watch an agent open a pull request. Fifteen minutes, one engine.
- [Helix Cloud](https://helix.ml/docs/install-cloud): Managed Helix. Sign up, connect a repo, and run agents. No installation, no infrastructure to manage.
- [Mac App](https://helix.ml/docs/install-mac): Run the full Helix stack locally on Apple Silicon. Credentials and code stay on your machine.
- [Self-hosting](https://helix.ml/docs/install-self-hosting): Run Helix on your own Linux servers or Kubernetes cluster.
- [Manage your organisation](https://helix.ml/docs/guide-organizations): Create an organisation, invite members, assign teams, manage API keys and secrets, and configure org-level AI providers.
- [Manage your backlog on the Kanban board](https://helix.ml/docs/guide-manage-backlog): Create spec tasks, move them through stages, run agents in parallel, and track progress across your project.
- [Connect a source repository](https://helix.ml/docs/guide-connect-repo): Connect GitHub, GitLab, or Bitbucket repositories to a Helix project so agents can read and commit to your code.
- [Review an agent's work and merge the PR](https://helix.ml/docs/guide-review-and-merge): How to read an agent's execution, give feedback, review the pull request, and handle edge cases before merging.
- [Choose and configure a code agent](https://helix.ml/docs/guide-choose-code-agent): Claude Code, Goose, Qwen Code, and Zed Agent are four pluggable engines for the same agent loop. This guide tells you when to pick which.
- [Build an internal knowledge base](https://helix.ml/docs/guide-knowledge-base): Use Helix Code Intelligence to index your codebase and give agents and humans a searchable, always-current understanding of your repositories.
- [Configure Goose recipes](https://helix.ml/docs/guide-goose-recipes): How to attach parameterised recipe playbooks to a Goose project, what the recipe file format supports, and how spec-task authors fill in recipe parameters at task creation time.
- [Work in a sandbox](https://helix.ml/docs/guide-sandbox): How to interact with an agent's desktop environment. View the live stream, type commands, browse files, and use the terminal.
- [Configure LLM providers](https://helix.ml/docs/guide-llm-providers): Connect Anthropic, OpenAI, Google, Groq, AWS Bedrock, NVIDIA NIM, Ollama, and other providers to Helix so agents have inference available.
- [Build an agent app](https://helix.ml/docs/guide-agent-apps): Create a conversational AI agent with skills, knowledge, and triggers. Covers the full configuration flow.
- [Add RAG knowledge bases](https://helix.ml/docs/guide-rag-knowledge): Attach documents, web content, and data sources to an agent app so it can answer questions grounded in your content.
- [Configure triggers](https://helix.ml/docs/guide-triggers): Extend an agent app beyond the chat UI. Respond in Slack, Teams, Discord, on a schedule, or via webhook.
- [How the agent loop works](https://helix.ml/docs/concept-agent-loop): The plan→implement→review cycle that every spec task runs through, and why each step exists.
- [Projects, spec tasks, and the board](https://helix.ml/docs/concept-projects): The core mental model. What a project is, what a spec task is, and how the Kanban board organises work.
- [Agent apps and code agents](https://helix.ml/docs/concept-agents): Helix has two distinct types of agent. Understanding the difference prevents confusion about what each one does and when to use which.
- [Sandboxes and the desktop environment](https://helix.ml/docs/concept-sandboxes): What a Helix sandbox is, how isolation works, and what runs inside the containerized Linux desktop that agents use.
- [Code intelligence](https://helix.ml/docs/concept-code-intelligence): How Helix builds and uses a deep structural understanding of your codebase, for agents and for humans.
- [Security and data residency](https://helix.ml/docs/concept-security): How Helix isolates agent work, where your code and credentials live, and what "runs on your infrastructure" actually means.
- [Kodit (Open-Source)](https://helix.ml/docs/kodit): Code and Document Indexing Server
- [Helix Org](https://helix.ml/docs/concept-helix-org): Helix Org is a system for running AI agents as persistent workers inside an organisation structure, with roles, streams, and managed activation.
- [Configuration reference](https://helix.ml/docs/ref-configuration): Environment variables, Helm values, project YAML, and agent app YAML schema for Helix deployments.
- [Supported models and providers](https://helix.ml/docs/ref-models): The LLM providers Helix supports and the model identifiers to use in project and assistant configuration.
- [Settings reference](https://helix.ml/docs/ref-settings): Every settings panel in Helix (account, organisation, and admin), with what each control does and where to find it.
- [Sandbox runtimes](https://helix.ml/docs/ref-sandbox-runtimes): Desktop environment options, container images, and resource requirements for Helix agent sandboxes.
- [Architecture for operators](https://helix.ml/docs/deploy-architecture): How Helix's components fit together. What runs where, what talks to what, and what you need to provide.
- [Linux & Kubernetes](https://helix.ml/docs/deploy-linux-kubernetes): Install Helix on a Linux server or Kubernetes cluster, from licensing through first login.
- [Sovereign Server](https://helix.ml/docs/deploy-sovereign-server): A 4U rack server with 8× NVIDIA RTX 6000 Pro GPUs and 768 GB VRAM, Helix pre-installed. Ship to your data centre, power on, run hundreds of concurrent agents with zero cloud dependency.
- [Mac App — operator settings](https://helix.ml/docs/deploy-mac-operators): VM management, disk expansion, LAN sharing, licensing, and updates for the Mac App.
- [Upgrade and migrate](https://helix.ml/docs/deploy-upgrade): How to upgrade a self-hosted Helix deployment to a new version, and how to migrate data between environments.
- [Troubleshooting](https://helix.ml/docs/troubleshooting): Common problems and their fixes. If something isn't working, start here.
- [Glossary](https://helix.ml/docs/glossary): One definition per concept. Use these terms consistently throughout your work with Helix.

---

## What is Helix?

Helix is infrastructure for running AI agents on your own servers. Every agent gets a full isolated environment: desktop, terminal, filesystem, and browser. Your team gets a fleet dashboard showing what every agent is doing in real time. Your data stays on your infrastructure.

Helix hosts three kinds of agent workload:

**Code agents** work through development tasks: read a spec, plan, implement in an isolated sandbox, and open a pull request. Engineers set direction, approve plans, and review output. See [How the agent loop works](/docs/concept-agent-loop).

**Agent apps** are conversational assistants connected to your knowledge, APIs, and communication channels. They respond to user messages, Slack threads, webhooks, and scheduled triggers. See [Build an agent app](/docs/guide-agent-apps).

**Helix Org workers** are persistent, role-based agents that operate as part of an organisation. Workers subscribe to event streams, carry out tasks across activations, collaborate with other workers, and escalate decisions to human managers. See [Helix Org](/docs/concept-helix-org).

All three share the same foundation: isolated sandboxes, fleet-level observability, and infrastructure you control.

## Where it runs

| Deployment | Good for |
|---|---|
| [Helix Cloud](/docs/install-cloud) | Fastest start — sign up and go |
| [Mac App](/docs/install-mac) | Local on Apple Silicon — credentials and code never leave your machine |
| [Linux & Kubernetes](/docs/deploy-linux-kubernetes) | Self-hosted on your own servers or any Kubernetes cluster |
| [Sovereign Server](/docs/deploy-sovereign-server) | Pre-installed rack server shipped to your data centre — zero cloud dependency |

## Where to start

**Evaluating Helix?** → [Quickstart](/docs/quickstart) — one tutorial, one engine, works in under ten minutes.

**Building an agent app or knowledge base?** → [Build an agent app](/docs/guide-agent-apps) or [Set up a knowledge base](/docs/guide-rag-knowledge).

**Setting up Helix Org workers?** → [Helix Org](/docs/concept-helix-org).

**Mid-task and need something specific?** → [Guides](/docs/guide-manage-backlog) — one guide per workflow.

**Want to understand the model before making decisions?** → [Concepts](/docs/concept-agent-loop) — the why behind the how.

**Deploying to production?** → [Deploy & Operate](/docs/deploy-architecture) — install, configure, scale.

---

This tutorial uses Helix Cloud and Claude Code. It picks one path and stays on it — no forks, no "or you could also". Once you've done this once, the [Guides](/docs/guide-manage-backlog) cover everything else.

## 1. Sign up

Go to [app.helix.ml](https://app.helix.ml) and sign in with Google. You'll be asked to create an organization name — this can be your company name or your own name for a personal workspace.

After signing in, complete the onboarding steps:
1. **Create an organization** — give it a name
2. **Add an AI provider** — the built-in Helix providers work on Cloud; or add your own Anthropic or OpenAI key under **Account → AI Providers**

## 2. Create a project and connect a repository

From the dashboard, click **New Project**.

Give the project a name that matches what you're building. On the **Repositories** tab, click **Connect & Browse** and follow the GitHub OAuth flow to authorize Helix. Once authorized, pick the repository you want the agent to work in.

Helix will index the repository for code intelligence — this runs in the background and takes a few minutes for large repos.

## 3. Write a spec task

Inside your new project, click **New Task**.

Write a one-paragraph description of what you want done. Be specific about outcomes, not implementation. For example:

> Add input validation to the `createUser` form. Email addresses should be validated with a regex. Required fields (name, email) should show an inline error message when left blank on submit. No changes to the backend.

Click **Save**, then click **Start Planning**.

## 4. Review and approve the plan

The agent enters a planning loop. It reads your repository, analyses the codebase, and produces a step-by-step execution plan pushed to a `helix-specs` branch in your repository.

Read the plan. If something looks wrong, highlight the text and submit feedback — the agent will revise. When the plan looks right, click **Approve**.

## 5. Watch the implementation

After approval, the agent moves into a sandbox — an isolated Linux desktop with Zed IDE, a terminal, and a browser. You can watch it work live via the video stream in the task view, or switch away and come back later.

The agent makes commits on a working branch as it goes.

## 6. Open the pull request

When the agent finishes, click **Open PR**. This creates a pull request in GitHub from the agent's working branch. From here, follow your normal review process: run CI, request reviews, check the diff, and merge when you're happy.

If CI finds problems, go back to the task and tell the agent what failed — it will fix and push again.

---

## What to do next

- [Manage your backlog on the Kanban board](/docs/guide-manage-backlog) — run multiple tasks in parallel
- [Connect more repositories](/docs/guide-connect-repo) — GitLab and Bitbucket also work
- [Choose a different code agent](/docs/guide-choose-code-agent) — Goose, Qwen Code, and Zed Agent are also available
- [How the agent loop works](/docs/concept-agent-loop) — understand the model behind what you just did

---

Helix Cloud is the fastest path to running agents. Sign up at [app.helix.ml](https://app.helix.ml). Infrastructure, sandboxes, authentication, and scaling are all managed for you.

## Getting started

1. **Sign up** at [app.helix.ml](https://app.helix.ml) with a Google account
2. **Create an organization**
3. **Add an AI provider** — built-in Helix providers work immediately, or bring your own Anthropic or OpenAI key
4. **Create a project** and connect a GitHub, GitLab, or Bitbucket repository
5. **Write spec tasks** and let agents do the work

See the [Quickstart](/docs/quickstart) for a step-by-step walkthrough of the full flow.

## What's included

- **Managed sandboxes** — isolated desktop environments provisioned on demand for each spec task
- **All LLM providers** — Anthropic, OpenAI, Google, and more available out of the box
- **Source control integration** — GitHub, GitLab, and Bitbucket via OAuth
- **Code intelligence** — automatic repository indexing with semantic search
- **Team access** — invite teammates and share projects

## Running Helix on your own infrastructure?

If you want data to stay on your own servers, see:
- [Mac App](/docs/install-mac) — local on Apple Silicon, zero cloud dependency
- [Linux & Kubernetes install](/docs/deploy-linux-kubernetes) — self-hosted on your own servers or a Kubernetes cluster
- [Sovereign Server](/docs/deploy-sovereign-server) — a pre-installed rack server shipped to your data centre

---

The Mac app runs the entire Helix platform on your Mac — agents, sandboxes, control plane, and optionally local models. Your SSH keys, `.env` files, tokens, and development data never leave your hardware.

Requires **Apple Silicon (M1 or later)** with **16 GB+ unified memory** and **macOS 14 (Sonoma) or later**.



## What runs locally

- **Helix control plane** — the API and UI, running on your machine
- **Agent sandboxes** — up to 15 isolated desktop environments simultaneously, GPU-accelerated via Apple Silicon
- **LAN sharing** — give your team access without exposing anything to the internet

For inference, use your Anthropic or OpenAI API key, or run fully local models with Ollama on 64 GB+ unified memory.

## First launch

1. Download and open the Mac app
2. Complete the initial setup wizard — it provisions a local UTM virtual machine for the sandboxes
3. Sign in (local account or connect to Helix Cloud for team features)
4. Open the Helix UI at [http://localhost:8080](http://localhost:8080)
5. Add an AI provider under **Account → AI Providers**
6. Create a project and connect a repository

See the [Quickstart](/docs/quickstart) for the full flow from project to pull request.

## Memory and concurrency

| Unified memory | Concurrent agent desktops |
|---|---|
| 16 GB | ~2–3 |
| 32 GB | ~6–8 |
| 64 GB+ | 12–15, plus local model inference |

## Operator settings

For disk expansion, VM management, updates, and LAN sharing configuration, see [Mac App — operator settings](/docs/deploy-mac-operators).

## Don't have Apple Silicon?

- [Helix Cloud](/docs/install-cloud) — managed, nothing to install
- [Linux & Kubernetes](/docs/deploy-linux-kubernetes) — self-hosted on any server with NVIDIA or AMD GPUs

---

Self-hosting Helix is the first chapter of operating it. The install guide lives alongside the GPU configuration, scaling, and observability docs — so the operator lands in one place and finds everything in sequence.

**→ [Linux & Kubernetes install](/docs/deploy-linux-kubernetes)**

That page covers:
- Licensing requirements
- Single-server install (Linux with NVIDIA or AMD GPU)
- Kubernetes install via Helm (control plane chart + sandbox chart)
- External inference provider configuration
- Environment variables and tuning

## Air-gapped / enterprise deployments

For organisations that require data to stay fully on-premises with no cloud dependency, see:

**→ [Sovereign Server](/docs/deploy-sovereign-server)**

A pre-configured 4U rack server with Helix pre-installed — plug in, power on, done.

## Just evaluating?

If you're not ready to manage infrastructure, start with [Helix Cloud](/docs/install-cloud) — it's free to try and takes under five minutes.

---

An organisation is a shared workspace. Members of an organisation can collaborate on agent apps, share knowledge bases, and use org-level resources (providers, secrets, API keys). Most production deployments run inside an organisation.

## Create an organisation

1. Click your account name in the top bar → **Organisations**.
2. Click **New Organisation**.
3. Enter a **Name** and **Slug** (the short URL identifier). The slug is permanent.
4. Optionally set an **Auto-join domain** — any user who signs up with an email address from that domain is automatically added to the organisation.

## Invite members

Go to **Organisation → People** and click **Invite Member**. Enter the email address. The invited user receives a link and is added to the organisation on first login.

### Roles

| Role | Permissions |
|------|-------------|
| **Owner** | Full access including billing, org deletion, and member management |
| **Admin** | Manage members, providers, secrets, and API keys; cannot delete the org |
| **Member** | Use shared resources; create and manage their own agent apps |

## Teams

Teams are sub-groups within an organisation. Use them to control which agent apps and resources a group of members can access.

1. Go to **Organisation → Teams**.
2. Click **New Team**, give it a name.
3. Add members to the team.
4. Assign teams to specific agent apps in the app's **Access** tab.

## Organisation API keys

Org API keys authenticate API calls to agents on behalf of the organisation (not any individual user). Use them in server-side integrations where you don't want to expose a user's personal key.

Go to **Organisation → API Keys** → **New API Key**. Give it a descriptive name and copy the generated key — it is shown only once.

Use it in the `Authorization: Bearer <key>` header for API requests.

## Secrets

Secrets store sensitive values (API keys, tokens, passwords) and expose them to agent apps as environment variable references. Storing values as secrets means they never appear in plain text in your agent configuration.

### Create a secret

Go to **Organisation → Secrets** → **New Secret**.

- **Name** — the reference name used in configurations, e.g., `OPENAI_API_KEY`
- **Value** — the secret value (stored encrypted at rest)

### Use a secret

Reference a secret anywhere in your agent configuration with `${SECRET_NAME}`:

```yaml
# In an API skill header
Authorization: Bearer ${OPENAI_API_KEY}

# In an MCP server environment variable
env:
  DATABASE_URL: ${DATABASE_URL}
```

Secrets are resolved at runtime and never exposed in logs or API responses.

## Configure org-level AI providers

Org-level providers are shared across all members and agent apps in the organisation. Members use org providers without needing to configure their own API keys.

Go to **Organisation → Providers** → **Add Provider**.

For each provider, enter:
- **Provider type** — Anthropic, OpenAI, Google Gemini, Groq, Ollama, Amazon Bedrock, NVIDIA NIM, xAI, or any OpenAI-compatible custom endpoint
- **Base URL** — for custom providers
- **API key** — use a [secret reference](#secrets) rather than a raw key

See [Configure LLM providers](/docs/guide-llm-providers) for per-user provider setup.

## Organisation settings

**Organisation → Settings** controls:

- **Name** and **Slug** — rename the org (slug changes affect all URLs)
- **Auto-join domain** — automatically add users who sign up with a matching email domain
- **Delete organisation** — permanent; removes all data including agent apps, knowledge bases, and secrets

Only owners can delete an organisation.

---

Each Helix project has a Kanban board where spec tasks move through stages: **Draft → Planning → Approved → Implementing → Review → Done**.

This guide assumes you've already done the [Quickstart](/docs/quickstart) and have a project with at least one repository connected.

## Creating a spec task

Click **New Task** inside a project. Write a one-paragraph description of the desired outcome — not an implementation plan. Good specs describe *what* should be true when done, not *how* to get there.

Tips:
- Be specific about scope. "Add input validation to the login form" is better than "improve the login page".
- Reference specific files, functions, or UI elements if relevant.
- State what should *not* change if there's a risk of over-reach.

## Planning and approval

Click **Start Planning** on a Draft task. The planning agent reads your repository and produces a step-by-step execution plan, pushing it to a `helix-specs` branch in your repository.

**Reviewing the plan:** Read each step. If something looks wrong, highlight the text and submit feedback — the agent will revise and re-plan.

**Approving:** When the plan looks right, click **Approve**. This commits to the plan and moves the task to **Implementing**.

You can approve or reject without reading every line — the pull request is the real review gate.

## Running tasks in parallel

Helix can run multiple tasks at the same time. Each task gets its own isolated sandbox. You don't need to wait for one to finish before starting another.

**Split-screen view:** Click the split-screen icon to see multiple agent desktops side by side. Each panel can be maximized, minimized, or closed independently.

Practical limit: your concurrency is bounded by the number of sandboxes available on your plan or deployment. On Helix Cloud, this scales automatically. On self-hosted, it's bounded by your GPU capacity.

## Reviewing implementation

While a task is **Implementing**, you can:
- Watch the agent's desktop live via the video stream
- Switch away and come back when it finishes
- Interact with the agent directly by typing in the task thread

When the agent finishes, the task moves to **Review**. Click **Open PR** to create a pull request in your repository.

## Handling merge conflicts

If your repository moved while the agent was working, GitHub may report merge conflicts on the PR. Go back to the task and tell the agent to fix them:

> There are merge conflicts on the PR. Please rebase against main and resolve them.

The agent will rebase and force-push to the PR branch. Once CI passes again, merge as normal.

## Using Optimus for backlog management

Optimus is a Helix agent you can enable on a project to help manage the backlog itself. When enabled, it watches your GitHub issues on a schedule and prepares new spec tasks from them — so issues flow automatically into the board without manual triage.

Enable Optimus from the project **Settings** tab under **Automations**.

---

Helix needs access to your repository to index it for code intelligence, clone it into agent sandboxes, and push agent commits. This guide covers connecting repositories for all three supported source control providers.

## GitHub

### Helix Cloud

1. Inside a project, go to the **Repositories** tab
2. Click **Connect & Browse**
3. Follow the GitHub OAuth flow — Helix requests repository access scoped to the repositories you select
4. Pick the repositories to attach to this project
5. Click **Save**

Helix will index the repository immediately. Semantic search and the wiki become available once indexing is complete (a few minutes for most repos, longer for very large ones).

### Self-hosted

If your Helix is behind a firewall and GitHub.com can't reach it, you'll need to configure a GitHub App manually:

1. Go to **Settings → Source Control** in the Helix admin panel
2. Follow the GitHub App setup instructions — Helix will generate the App manifest and callback URL
3. Install the App on your GitHub organization and select the repositories

For GitHub Enterprise Server, also set `HELIX_GITHUB_BASE_URL` to your GHES URL in your Helix configuration.

## GitLab

1. Go to **Settings → Source Control → GitLab** in the Helix admin panel
2. Create a GitLab OAuth application in your GitLab instance:
   - **Redirect URI**: `https://your-helix-url/api/v1/oauth/callback/gitlab`
   - **Scopes**: `api`, `read_user`, `read_repository`
3. Paste the Client ID and Secret into the Helix settings
4. In a project, click **Connect & Browse** and authorize with your GitLab account

Works with gitlab.com and self-hosted GitLab instances.

## Bitbucket

1. Go to **Settings → Source Control → Bitbucket** in the Helix admin panel
2. Create an OAuth consumer in your Bitbucket workspace settings:
   - **Callback URL**: `https://your-helix-url/api/v1/oauth/callback/bitbucket`
   - **Permissions**: Repositories (Read, Write), Pull requests (Read, Write)
3. Paste the Key and Secret into the Helix settings
4. In a project, click **Connect & Browse** and authorize with your Bitbucket account

## Multiple repositories per project

A project can have multiple repositories attached. This is useful when:
- The feature spans a frontend and backend in separate repos
- You want the agent to have access to a shared library repo
- You're using Goose recipes stored in a separate repo

One repository is designated **primary** — that's the repository the agent clones first and where it opens pull requests by default. Set the primary repo on the **Repositories** tab.

## Detaching a repository

Go to the **Repositories** tab, click the three-dot menu on the repository, and click **Detach**. This removes it from the project but does not delete the repository or its code. The agent will no longer have access to it on future tasks.

---

Agents never push code to your main branch or merge pull requests without you. This guide covers what to do between "implementation done" and "PR merged".

## Reading the implementation

While the agent is working, or after it finishes, you can see what it did in two places:

**The task thread** shows the agent's tool calls in sequence — what files it read, what commands it ran, what edits it made. Scan this to understand the agent's reasoning, not just the output.

**The live desktop view** shows the agent's screen in real time via video stream. You can click into the stream and type directly to the agent if you want to redirect it mid-implementation.

## Reviewing the diff

When a task reaches **Review** status, click **Open PR** to create a pull request in your repository. From there, use your normal review process — GitHub / GitLab / Bitbucket diffs, CI results, preview deployments.

Things to look for in an agent diff:
- **Scope creep** — the agent touched files you didn't expect. Read the diff, not just the summary.
- **Test coverage** — did the agent write tests? Are they meaningful or just stubs?
- **Existing patterns** — did the agent follow your project's conventions? If not, see [Giving feedback](#giving-feedback).

## Giving feedback

If the implementation is wrong or incomplete, go back to the task and tell the agent in plain language:

> The validation fires on every keystroke, which is annoying. It should only fire on blur (when the user leaves the field).

The agent will read your feedback, reopen the sandbox, fix the issue, and push to the same PR branch.

You can give feedback as many times as needed. Each round trips through the same plan→implement cycle, so significant changes go through another approval step.

## Requesting changes on the PR

If you request changes via GitHub's review UI, the agent won't automatically see them — you need to go back to the Helix task and explicitly describe what needs fixing. Copy-paste the relevant comments from GitHub into the task thread.

## Handling merge conflicts

If your main branch moved while the agent was working:

1. Go to the task
2. Tell the agent: "There are merge conflicts on the PR. Please rebase against main and resolve them."
3. The agent will rebase and force-push to the branch

Wait for CI to pass again, then merge.

## Merging

Merge the PR from your source control provider — Helix doesn't merge for you. Once merged, Helix marks the task as **Done** (on the next sync).

## If something went badly wrong

If the agent made a mess and you want to start fresh:

1. Close the PR without merging — the branch stays in your repo but the agent won't touch it again
2. Delete the agent's branch if you want a clean slate
3. Reopen the task with updated guidance, or write a new task

The agent's commits are on a separate branch; your main branch was never touched.

---

Every Helix project uses a **code agent** — the software that runs inside the sandbox, reads your codebase, and makes changes. Four engines are available. They all run in the same isolated desktop, stream through the same UI, and produce pull requests the same way. The choice is about the agent's harness, model access, and workflow features.

## Quick reference

| Agent | Runtime value | Best when |
|---|---|---|
| **Claude Code** | `claude_code` | You want Anthropic's latest models with Anthropic's own harness |
| **Goose** | `goose_code` | You want parameterised, reusable task recipes |
| **Qwen Code** | `qwen_code` | You want a fully open-source stack or local models |
| **Zed Agent** | `zed_agent` | You want in-editor agents with no extra CLI to maintain |

If you're not sure, start with Claude Code or Zed Agent — they're the lowest-friction choices.

## Selecting an agent for a project

Set the `runtime` on the agent in your project YAML:

```yaml
apiVersion: helix.ml/v1alpha1
kind: Project
metadata:
  name: my-app
spec:
  repositories:
    - url: "https://github.com/org/my-app"
      branch: main
      primary: true
  agent:
    name: "My Agent"
    runtime: claude_code   # or goose_code, qwen_code, zed_agent
```

---

## Claude Code

[Claude Code](https://www.anthropic.com/claude-code) is Anthropic's official command-line coding agent. Helix launches the `claude` CLI inside the sandbox and connects it to Zed over ACP.

```yaml
  agent:
    name: "Claude Code"
    runtime: claude_code
```

Claude Code manages its own model selection internally — you don't set `model` or `provider`.

### Credential modes

**API key (default):** Routes through the Helix proxy using your configured Anthropic provider. No client-side OAuth needed.

**Subscription:** Use your Claude Pro or Max subscription directly.

```yaml
  agent:
    runtime: claude_code
    code_agent_credential_type: subscription
```

The first session walks through an OAuth flow; credentials are persisted to the sandbox for subsequent sessions.

### Pick Claude Code when

- You want the latest Claude models with Anthropic's own prompt design and tool set
- You want your Claude subscription quota to power agents instead of a metered API key
- You want Claude Code ecosystem integrations (skills, MCPs, hooks) without rebuilding them

---

## Goose

[Goose](https://github.com/block/goose) is an open-source agent from the Agentic AI Foundation. Its key feature is **recipes** — reusable, parameterised playbooks you attach to a project once and invoke per task from a structured form.

```yaml
  agent:
    name: "Goose Agent"
    runtime: goose_code
    model: claude-sonnet-4-6
    provider: anthropic
```

### Project recipes

Recipes are YAML files in your repository. Attach them to the project, and Helix renders a parameter-capture form on the task creation screen for each one:

```yaml
  agent:
    runtime: goose_code
    goose:
      recipes:
        - name: triage
          path: .goose/recipes/triage.yaml
        - name: fix-flaky-test
          path: .goose/recipes/fix-flaky-test.yaml
```

A recipe file looks like:

```yaml
version: "1.0.0"
title: "Triage failing CI"
instructions: |
  Stay focused on the failing CI run. Produce a triage note.
prompt: |
  Investigate the failing CI run at {{ ci_url }} for branch {{ branch }}.
parameters:
  - key: ci_url
    input_type: string
    requirement: required
  - key: branch
    input_type: string
    requirement: required
```

Starter recipes (triage, release notes, fix-flaky-test, implement-from-spec) are available in [`examples/goose_recipes/`](https://github.com/helixml/helix/tree/main/examples/goose_recipes).

For the full recipe configuration reference — parameter types (string, select, file), `recipe_repo_url`, and the spec-task form workflow — see [Configure Goose recipes](/docs/guide-goose-recipes).

### Pick Goose when

- You want to codify recurring task types ("how we triage CI failures", "how we cut release notes") as versioned, reusable recipes
- You want structured parameter capture at task creation time — no free-text prompting for context the agent always needs

---

## Qwen Code

[Qwen Code](https://github.com/QwenLM/qwen-code) is an open-source agent that speaks the OpenAI API — so it works with any provider behind that interface, not just Qwen models.

```yaml
  agent:
    name: "Qwen Coder"
    runtime: qwen_code
    model: qwen3-coder-480b
    provider: helix
```

Helix routes the agent through its `/v1` proxy in OpenAI-compatible mode, so any provider you've configured under **Account → AI Providers** is available — set `provider` to match.

### Pick Qwen Code when

- You want a fully open-source agent stack (no Anthropic dependency)
- You're running local models on a Helix runner
- You need to point the agent at a self-hosted OpenAI-compatible endpoint

---

## Zed Agent

The Zed Agent is the built-in agent panel in the [Zed editor](https://zed.dev). Helix doesn't launch a separate CLI — the user opens Zed's agent panel and interacts with it directly inside the sandbox desktop.

```yaml
  agent:
    name: "Zed Agent"
    runtime: zed_agent
    model: claude-sonnet-4-6
    provider: anthropic
```

Like the other agents, the model routes through Helix's `/v1` proxy, so any configured provider works.

### Pick Zed Agent when

- You want a fully in-editor experience with no extra CLI to install or maintain
- You want to interact with the agent directly in the IDE panel rather than through a separate Helix thread

---

## Switching agents

You can change a project's agent runtime at any time by editing the project YAML. Active spec tasks continue with the agent that started them; new tasks pick up the new runtime.

The [Concepts: Agents vs code agents](/docs/concept-agents) page explains the underlying distinction if you want to understand the model.

---

Helix Code Intelligence (powered by [Kodit](https://github.com/helixml/kodit)) builds a structured index of your repositories. Agents use it automatically when working on spec tasks; you can also query it directly to understand your codebase.

## What gets indexed

When you connect a repository to a project, Helix indexes it immediately:

- **Code structure** — functions, classes, types, imports, exports across all files
- **Semantic embeddings** — vector representations for semantic ("find code that validates email addresses") and keyword search
- **Auto-generated wiki** — a page per major component or module, updated on each push

The index stays current: every push to the repository triggers a re-index of changed files.

## Searching the codebase

Open a project and click the **Code Intelligence** tab. From there you can:

- **Semantic search** — describe what you're looking for in plain language
  > "authentication middleware that validates JWT tokens"
- **Keyword search** — find specific identifiers, function names, or string literals
- **File browser** — list and browse files as the agent sees them
- **Read a file** — inspect any file exactly as the agent would read it
- **Changelog** — an automated commit-by-commit changelog for the repository

These are the same tools the agent uses via MCP — querying the search interface is a good way to verify what the agent can see before writing a spec task.

## Adding external repositories

Code Intelligence works with both private repositories (connected to your project) and external public repositories. To index a public repository without adding it as a project repository:

1. Go to **Settings → Code Intelligence**
2. Click **Add Repository**
3. Enter the repository URL

This is useful for indexing shared libraries, SDKs, or reference codebases that agents and developers need to understand but shouldn't commit to.

## The automated wiki

For each indexed repository, Helix generates a wiki — a set of prose pages describing the major components, their relationships, and their purpose. The wiki is updated automatically on each push.

Access it from the **Code Intelligence** tab → **Wiki**.

The wiki is useful for:
- Onboarding new developers to an unfamiliar codebase
- Giving agents a higher-level understanding of architecture before they start reading files
- Understanding what changed in a recent push (the changelog integrates here)

## For agents: how code intelligence improves output

Without code intelligence, agents re-read many files to build context, sometimes missing relevant code elsewhere in the codebase. With code intelligence, the agent can:

- Search for existing implementations before writing new ones (reduces duplication)
- Find all callers of a function before changing its signature (avoids breakage)
- Read the architectural context of a component before modifying it

In practice this reduces the rate of agents rewriting things that already exist and breaking things they didn't know were connected.

## Connecting MCP to local IDEs

The Kodit MCP server is accessible externally, so you can connect your local IDE or Claude Desktop to the same index your agents use:

1. Go to **Settings → Code Intelligence → MCP Access**
2. Copy the MCP server URL and token
3. Add it to your local MCP client configuration

This gives your local IDE the same semantic search, file browse, and wiki the agents use — a useful way to explore large or unfamiliar codebases.

---

[Goose](https://github.com/block/goose) supports **recipes** — reusable, parameterised playbooks for recurring tasks such as triaging a failing CI run, writing release notes, or reviewing a spec document. You define a recipe once, commit it to a repository, attach it to a Goose project, and Helix renders a structured form on the spec-task creation screen for each recipe. The agent receives a fully baked recipe at session start — no free-text prompting to gather context.

This guide covers everything after the initial [agent selection](/docs/guide-choose-code-agent#goose). For the basic Goose project YAML, start there.

## Attach recipes to a project

Recipes are declared in the `goose.recipes` list on the project agent. Each entry names a recipe and gives its path relative to the repository it lives in:

```yaml
apiVersion: helix.ml/v1alpha1
kind: Project
metadata:
  name: my-app
spec:
  repositories:
    - url: "https://github.com/org/my-app"
      branch: main
      primary: true

  agent:
    name: "Goose Agent"
    runtime: goose_code
    model: claude-sonnet-4-6
    provider: anthropic

    goose:
      recipes:
        - name: triage
          path: .goose/recipes/triage.yaml
        - name: fix-flaky-test
          path: .goose/recipes/fix-flaky-test.yaml
```

By default, `path` resolves against the primary repository. If your recipes live in a separate repository, add that repository to the project and point `recipe_repo_url` at it:

```yaml
spec:
  repositories:
    - url: "https://github.com/org/my-app"
      branch: main
      primary: true
    - url: "https://github.com/org/goose-recipes"
      branch: main

  agent:
    runtime: goose_code
    goose:
      recipe_repo_url: "https://github.com/org/goose-recipes"
      recipes:
        - name: triage
          path: recipes/triage.yaml
        - name: release-notes
          path: recipes/release-notes.yaml
```

`path` is repo-relative and free-form — `.goose/recipes/` is a convention, not a requirement.

## Recipe file format

A recipe is a small YAML file in the repository:

```yaml
version: "1.0.0"
title: "Triage failing CI"
description: "Walk through a failing CI run and produce a triage note."

instructions: |
  You are helping diagnose a failing CI run. Stay focused on the run
  the user provided; do not wander into unrelated branches or issues.

prompt: |
  Investigate the failing CI run at {{ ci_url }} for branch {{ branch }}.
  Identify the failing step, root-cause the failure, and produce a
  triage note covering what failed, the likely cause, the smallest
  plausible fix, and whether the failure looks flaky.

parameters:
  - key: ci_url
    input_type: string
    requirement: required
    description: "URL of the failing CI run"
  - key: branch
    input_type: string
    requirement: required
    description: "Branch the run was for"
```

| Field | Required | Description |
|-------|----------|-------------|
| `version` | Yes | Recipe schema version. Use `"1.0.0"`. |
| `title` | Yes | Display name shown in the recipe dropdown. |
| `description` | No | Shown below the title in the form. |
| `instructions` | No | Prepended to the agent's system prompt at session start. |
| `prompt` | Yes | The opening user message. May contain `{{ param }}` placeholders. |
| `parameters` | No | List of inputs the agent needs; each becomes a form field. |

`prompt` and `instructions` may use Jinja-style `{{ key }}` placeholders. The key must match a `parameters[].key` value.

## Parameter types

Each parameter in the list becomes one field on the task creation form.

### String

The most common type. Renders as a text input.

```yaml
parameters:
  - key: branch
    input_type: string
    requirement: required
    description: "Branch name to operate on"
  - key: head_ref
    input_type: string
    requirement: optional
    default: HEAD
    description: "Ref to compare against (defaults to HEAD)"
```

Set `default` to pre-fill the field. Optional parameters without a default render as empty.

### Select

Renders as a dropdown. Declare the allowed values in `options`:

```yaml
parameters:
  - key: audience
    input_type: select
    requirement: required
    options:
      - engineering
      - customer
      - marketing
    description: "Who the release notes are for"
```

### File

Renders as a dropdown populated from the **Attachments** section of the same spec-task form. The agent receives the absolute path to the file inside the sandbox — no separate upload step, no size limit beyond the attachment limit itself.

```yaml
parameters:
  - key: spec_doc
    input_type: file
    requirement: required
    description: "Spec document to review"
```

When the task is created, Helix commits the attachment to the project's `helix-specs` branch (the same mechanism used for all spec-task attachments), then rewrites the `{{ spec_doc }}` placeholder from the bare filename to the absolute path inside the agent's workspace. The agent can read the file with its normal tool calls.

File inputs work for any file type the agent can consume: spec PDFs, markdown docs, CSVs, log dumps, screenshots.

## Starter recipes

The Helix repository ships six ready-to-use recipes under [`examples/goose_recipes/`](https://github.com/helixml/helix/tree/main/examples/goose_recipes):

| Recipe | Description | Notable parameters |
|--------|-------------|-------------------|
| `triage.yaml` | Triage a failing CI run | `ci_url` (string), `branch` (string) |
| `fix-flaky-test.yaml` | Diagnose and fix a flaky test | `test_name` (string) |
| `release-notes.yaml` | Generate release notes between two refs | `base_ref` (string), `head_ref` (string, default=HEAD), `audience` (select) |
| `review-spec.yaml` | Review a spec document | `spec_doc` (file), `area` (string) |
| `error-log-triage.yaml` | Triage an error log dump | `log_file` (file) |
| `implement-from-spec.yaml` | Implement a feature from a spec | `spec_doc` (file) |

They cover the full range of parameter types. Copy them into your repo at `.goose/recipes/<name>.yaml`, or reference them directly by attaching `helixml/helix` as a second repository and using `recipe_repo_url`:

```yaml
spec:
  repositories:
    - url: "https://github.com/org/my-app"
      branch: main
      primary: true
    - url: "https://github.com/helixml/helix"
      branch: main

  agent:
    runtime: goose_code
    goose:
      recipe_repo_url: "https://github.com/helixml/helix"
      recipes:
        - name: release-notes
          path: examples/goose_recipes/release-notes.yaml
        - name: triage
          path: examples/goose_recipes/triage.yaml
```

## Creating a spec task with a recipe

When you create a spec task against a Goose project that has recipes configured, the task creation form shows a **Goose Recipe** dropdown listing every declared recipe by name.

1. Pick a recipe from the dropdown. The parameter form for that recipe appears below it.
2. Fill in the required fields (and optionally override any optional defaults).
3. For file parameters, stage the file in the **Attachments** section first — it will appear in the file dropdown.
4. Submit the task.

Leave the dropdown on **None (vanilla Goose)** to run the agent without a baked recipe — it starts with only the project-level instructions, and all declared recipes are still available as slash commands inside the thread for interactive use.

## Limits

- Recipes live in a git repository. Edit and version them with your normal review process; there is no in-Helix recipe editor.
- Parameter values are baked at session start. To change values, restart the session with a new spec task.
- A `recipe_repo_url` must be a repository already attached to the project — the URL is a key into `spec.repositories`, not a freestanding URL.
- If a declared recipe file is missing or malformed, Helix surfaces a warning in the project settings UI rather than failing the whole agent. The remaining recipes continue to work.

---

Every spec task runs inside a sandbox — an isolated Linux desktop with Zed IDE, a terminal, and a browser. You watch the agent work via a live video stream in your browser, and can interact directly at any point.

## Viewing the agent's desktop

In the task view, the video stream shows the agent's desktop in real time. The agent works autonomously, but you can watch its progress: file edits appear in the IDE, terminal commands run in the shell, browser navigation is visible.

Click the **Maximize** button to expand the stream to fill your browser window.

## Interacting with the agent

Click anywhere in the stream to focus it, then type. The agent sees your input as a message in its thread. Use this to:
- Redirect the agent mid-implementation ("actually, use the `useState` hook, not `useReducer`")
- Answer a question the agent asked
- Point the agent at a specific file or test that's failing

The agent reads your input and responds in the thread. It continues working in the same sandbox — no restart needed.

## Multiple sandboxes: split-screen mode

Click the split-screen icon in the project view to see multiple agent desktops side by side. Each panel is a separate task running independently.

You can:
- Maximize or minimize individual panels
- Add panels for running tasks
- Remove panels without stopping the underlying task

Split-screen is useful for reviewing multiple tasks in parallel or comparing two implementation approaches side by side.

## What's inside each sandbox

Each sandbox gets:
- **Zed IDE** — the editor the agent uses for reading and editing files
- **Terminal** — bash, full standard tooling (git, docker, curl, etc.)
- **Firefox browser** — for testing web apps, reading docs, accessing APIs
- **Agent thread** — the conversation between the Helix control plane and the agent

The sandbox starts with your repository pre-cloned, based on whatever repos are attached to the project.

## Accessing files from the agent's workspace

While a task is running, you can read files from the agent's working directory via the task view's **Files** tab. This is useful for checking intermediate output — a generated file, a log, a draft — without waiting for the agent to commit.

## Sandbox lifetime

A sandbox lives for the duration of a spec task session. When the session ends:
- The sandbox container is destroyed
- Files are not persisted except what the agent committed to git
- The agent's git commits are on the working branch — nothing is lost if the sandbox disappears

If a session ends unexpectedly (network drop, crash), you can resume from the task view — Helix will start a new sandbox and clone the repository again from where the agent left off.

## Sandboxes and security

Each task runs in its own isolated container with:
- A separate filesystem (no access to the host or other tasks)
- An isolated network (separate subnet per session, no cross-session traffic)
- Its own Docker daemon (via the Hydra isolation layer)

See [Sandboxes — how they work](/docs/concept-sandboxes) for the full architecture.

---

Helix doesn't bundle its own models — it routes to providers you configure. Providers can be set at three levels:

- **User** — personal providers, visible only to you (**Account → AI Providers**)
- **Organisation** — shared across all org members (**Organisation → Providers**); see [Manage your organisation](/docs/guide-organizations)
- **Installation** — configured in Helm values for self-hosted deployments; available to all users on the instance

This guide covers UI configuration and Helm values. For org-level providers, see [Manage your organisation: Configure org-level AI providers](/docs/guide-organizations#configure-org-level-ai-providers).

## Adding a provider in the UI

Go to **Account → AI Providers** and click **Add Provider**. Select the provider type, paste your API key, and save.

### Supported providers

| Provider | Notes |
|---|---|
| **Anthropic** | Claude models (Sonnet, Opus, Haiku). Recommended for coding agents. |
| **OpenAI** | GPT-4o, o1, o3, and other OpenAI models |
| **Google Gemini** | Gemini models via the Gemini API |
| **NVIDIA NIM** | GPU-accelerated inference; add the NIM base URL and API key |
| **AWS Bedrock** | Claude and other models via Amazon Bedrock; configure region and AWS credentials |
| **Groq** | Ultra-low latency open-source model inference (Llama, Mistral, Gemma) |
| **Cerebras** | Wafer-scale inference for fast open-source models |
| **xAI Grok** | Grok models from xAI |
| **Together AI** | Wide catalogue of hosted open-source models |
| **Fireworks AI** | Fast inference for open-source models |
| **Ollama** | Local model server; run models on your own hardware |
| **Custom (OpenAI-compatible)** | Any endpoint that speaks the OpenAI `/v1/chat/completions` API — vLLM, LM Studio, LocalAI, etc. |

Once a provider is added, its models become available in the **Model** dropdown on any project, agent app, or agent.

## Choosing a model for a coding project

Set `model` and `provider` on the agent in your project YAML:

```yaml
spec:
  agent:
    name: "My Agent"
    runtime: claude_code
    model: claude-sonnet-4-6
    provider: anthropic
```

Claude Code is an exception — it manages its own model selection. Set `runtime: claude_code` and omit `model`/`provider`.

## Helix Cloud: built-in providers

On Helix Cloud, built-in Helix inference providers are available by default — you can use these without adding your own API keys. Add your own keys if you want to use a specific model tier or route to your own accounts.

## Self-hosted: configure providers via Helm

For Kubernetes deployments, configure providers under `controlplane.providers` in your `values.yaml`. Use `existingSecret` to keep API keys out of your values file and git history:

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

```yaml
controlplane:
  providers:
    anthropic:
      existingSecret: "anthropic-api-key"
      existingSecretApiKeyKey: "api-key"
    openai:
      existingSecret: "openai-api-key"
      existingSecretApiKeyKey: "api-key"
    groq:
      existingSecret: "groq-api-key"
      existingSecretApiKeyKey: "api-key"
    vllm:
      baseUrl: "http://my-vllm.vllm.svc.cluster.local:8000/v1"
```

See [Linux & Kubernetes](/docs/deploy-linux-kubernetes) for the full Helm values reference.

## Local models with Ollama (Mac App)

On the Mac App with 64 GB+ unified memory, run models locally via Ollama:

1. Install [Ollama](https://ollama.com)
2. Pull a model: `ollama pull llama3.3`
3. In Helix, add an **Ollama** or **Custom (OpenAI-compatible)** provider with base URL `http://localhost:11434/v1` and no API key
4. The model appears in the model dropdown as `llama3.3`

Toggle wifi off and the agent still works — entirely local.

## AWS Bedrock

Bedrock uses AWS IAM credentials rather than an API key:

1. Add an **AWS Bedrock** provider and choose your region.
2. Provide an IAM access key and secret (or use an instance role for EC2/EKS deployments).
3. Enable the models you want in the [AWS Bedrock console](https://console.aws.amazon.com/bedrock) — models must be explicitly enabled per region.

For Helm-based deployments:

```yaml
controlplane:
  providers:
    bedrock:
      region: "us-east-1"
      existingSecret: "aws-credentials"
      existingSecretAccessKeyKey: "access-key-id"
      existingSecretSecretKeyKey: "secret-access-key"
```

## Anthropic via GCP Vertex AI

For organisations that prefer to route Anthropic inference through Google Cloud:

```yaml
controlplane:
  providers:
    anthropic:
      vertexProjectID: "my-gcp-project"
      vertexRegion: "us-east5"
      vertexCredentialsSecret: "gcp-vertex-credentials"
```

See the chart's `values-example.yaml` for the full shape.

## Model availability

The [Reference: Supported models](/docs/ref-models) page lists model identifiers and which providers support them.

---

Agent apps are Helix's chatbot and automation builder. An agent app has a system prompt, an LLM, optional skills (web search, APIs, MCP), optional knowledge bases (RAG), and optional triggers (Slack, cron, webhook). Users interact with it through the Helix chat UI, an embedded widget, or an API call. This guide walks the full configuration flow.

Agent apps are distinct from [spec tasks and coding agents](/docs/concept-agents), which do autonomous software development inside sandbox containers.

## Create an agent app

1. Navigate to **Agents** in the left sidebar.
2. Click **New Agent**.
3. Give the agent a name and, optionally, a description and avatar.

Helix creates a minimal agent: a default model, no system prompt, no skills.

## Configure the model

Open the **Settings** tab. Under **Model**:

- **Provider** — choose from your configured providers (Anthropic, OpenAI, Google, Ollama, etc.). See [Configure LLM providers](/docs/guide-llm-providers).
- **Model** — pick the specific model. Available models depend on which providers are enabled.
- **System prompt** — the instruction context the model receives before every conversation. Write it in first person: *"You are a support assistant for Acme Corp…"*
- **Temperature** — 0 for precise and deterministic, 1 for balanced, 2 for creative.
- **Max tokens** — cap on the response length.
- **Context limit** — number of past messages included per turn (1 = no memory of prior turns; higher values increase context but cost more).

### Reasoning model

For tasks that benefit from an extended thinking step before responding, enable a **Reasoning model** (e.g., Claude 3.7 Sonnet with extended thinking, o3). Helix will use the reasoning model for planning and the main model for the final reply.

## Add skills

Skills are tools the agent can call. Enable them in the **Skills** tab.

### Built-in skills

| Skill | What it does |
|-------|-------------|
| **Web Search** | Searches the internet and reads result pages |
| **Browser** | Opens URLs and extracts page content as markdown |
| **Calculator** | Solves mathematical expressions |
| **Email** | Sends email when the agent decides it's needed |
| **Azure DevOps** | Reads and writes to Azure DevOps work items |
| **Project Manager** | Creates and updates project tasks inside Helix |

Toggle each skill on or off. Each skill exposes one or more tools the LLM can invoke when the user's message makes it relevant.

### API integrations

Connect any REST API by providing an OpenAPI schema. The agent reads the schema and can call any endpoint when relevant.

1. Click **Add API**.
2. Provide a name, description, and OpenAPI schema (paste YAML/JSON or link to a URL).
3. If the API requires authentication, set the `Authorization` header using a [secret reference](/docs/guide-organizations#secrets): `${MY_API_KEY}`.

For OAuth-protected APIs, set the **OAuth provider** field. The user is prompted to authorise once; the agent uses the token automatically after that.

### MCP servers

[Model Context Protocol](https://modelcontextprotocol.io/) lets agents connect to external tool servers. Add an MCP server in the **Skills** tab → **Add MCP**.

**HTTP transport** (most common for remote servers):

```
Name: GitHub
URL: https://mcp.example.com/github
Header: Authorization: Bearer ${GITHUB_TOKEN}
```

**Stdio transport** (runs as a subprocess inside the agent's container):

```
Name: Filesystem
Command: npx
Args: -y @modelcontextprotocol/server-filesystem /workspace
```

For OAuth-authenticated MCP servers, set the **OAuth provider** field.

## Add knowledge bases (RAG)

Knowledge bases give the agent long-term memory over a set of documents. When the user sends a message, Helix searches the knowledge base and injects the relevant chunks into the context.

See [Add RAG knowledge bases](/docs/guide-rag-knowledge) for the full knowledge source configuration.

## Set up triggers

By default, the agent is only reachable through the Helix chat UI. Triggers extend that reach.

See [Configure triggers](/docs/guide-triggers) for detailed setup instructions for each trigger type.

**Supported triggers:**

- **Slack** — the agent responds to @-mentions or messages in configured channels
- **Microsoft Teams** — same pattern as Slack
- **Discord** — responds to messages in configured servers/channels
- **Cron** — runs on a schedule with a fixed input prompt (useful for reports, summaries)
- **Azure DevOps** — responds to work item events
- **Crisp** — handles live chat conversations
- **Webhook** — any external system can POST to a generated URL to trigger the agent

## Configure appearance

The **Appearance** tab controls how the agent looks when embedded:

- **Name** and **Avatar** — displayed in the chat header
- **Conversation starters** — suggested prompts shown to new users
- **Theme** — light or dark
- **Allowed domains** — restrict widget embedding to specific hostnames

## Manage access

The **Access** tab controls who can use the agent:

- **Private** — only you
- **Organisation** — any member of your org
- **Public** — anyone with the link (no login required)

You can also share the agent with specific users.

## API and embedding

The **Developers** tab shows:

- **API endpoint** and an example `curl` request — POST a message and receive the response (streaming or non-streaming)
- **Embed snippet** — drop a `<script>` tag into any page to add a floating chat widget
- **OpenAI-compatible endpoint** — use the agent as a drop-in replacement in any OpenAI SDK client

API calls authenticate with a **user API key** (from **Account → API Keys**) or an **org API key** (from **Organisation → API Keys**).

## Test and evaluate

The **Tests** tab lets you define expected input/output pairs. Run them against the agent to catch regressions when you change the system prompt or model.

The **Evaluation** tab runs a broader question set and scores the agent's responses. This is useful for systematically comparing two model or prompt configurations.

## Monitor usage

The **Usage** tab shows request counts, token consumption, and error rates over time, broken down by model and skill.

---

A knowledge base is a collection of documents that Helix indexes and searches at query time. When the agent receives a message, Helix finds the most relevant chunks and injects them into the context. This is Retrieval-Augmented Generation (RAG).

This guide covers knowledge bases for **agent apps** (the chatbot builder). For indexing codebases used by spec tasks, see [Build an internal knowledge base](/docs/guide-knowledge-base).

## Add a knowledge source

In your agent app, open the **Knowledge** tab and click **Add Knowledge**. Give it a name and description — the description helps the agent decide when to query this source versus another.

Each agent app can have multiple knowledge bases. The agent queries each one independently and combines the results.

## Source types

### Web URLs

Index one or more public URLs. Helix fetches and chunks the page content.

```yaml
source:
  web:
    urls:
      - https://docs.example.com/
      - https://blog.example.com/release-notes
```

Enable **Crawler** to follow links recursively:

```yaml
source:
  web:
    urls:
      - https://docs.example.com/
    crawler:
      enabled: true
      max_depth: 3        # link depth from the seed URL
      max_pages: 200      # hard cap on pages fetched
      readability: true   # strip nav/footer noise, keep article body
```

For password-protected sites:

```yaml
source:
  web:
    urls:
      - https://intranet.example.com/
    auth:
      username: ${INTRANET_USER}
      password: ${INTRANET_PASS}
```

### File uploads

Drag-and-drop or browse files in the **Knowledge** tab. Supported formats: PDF, DOCX, PPTX, XLSX, CSV, Markdown, plain text.

Uploaded files go into the agent's Helix Drive storage and are indexed immediately.

### Helix Drive path

Reference a folder already in Helix Drive (the built-in file storage):

```yaml
source:
  helix_drive:
    path: /my-team/product-docs
```

### S3

```yaml
source:
  s3:
    bucket: my-company-docs
    path: knowledge-base/         # prefix, optional
```

Helix uses the AWS credentials configured in your installation. For Helix Cloud, contact support to configure S3 access.

### Google Cloud Storage

```yaml
source:
  gcs:
    bucket: my-company-docs
    path: knowledge-base/
```

### SharePoint

```yaml
source:
  sharepoint:
    site_id: <sharepoint-site-id>
    drive_id: <drive-id>          # optional; defaults to the default drive
    folder_path: /Documentation   # optional
    oauth_provider_id: <your-sharepoint-oauth-provider>
    filter_extensions:
      - .pdf
      - .docx
    recursive: true
```

SharePoint requires an OAuth provider configured under **Organisation → OAuth Connections**.

### Inline text

For small, stable content that doesn't need an external source:

```yaml
source:
  text: |
    Our return policy: items may be returned within 30 days
    with a receipt for a full refund...
```

## Vision RAG

By default, Helix indexes the text content of documents. Enable **Vision** to also index images and scanned PDFs using a multimodal embedding model:

```yaml
rag_settings:
  enable_vision: true
```

With vision enabled, the agent can answer questions about diagrams, screenshots, charts, and scanned pages that contain no machine-readable text.

Vision indexing is slower and costs more tokens than text-only indexing. Use it when your documents contain meaningful visual content.

## Refresh schedule

Keep the index current with a cron schedule:

```yaml
refresh_enabled: true
refresh_schedule: "0 */6 * * *"   # every 6 hours
```

Standard cron syntax. The agent serves the previous index while the refresh runs; there is no downtime.

## Tuning RAG retrieval

Under **Advanced Settings** in the Knowledge editor:

| Setting | Default | Effect |
|---------|---------|--------|
| **Results count** | 4 | Number of chunks retrieved per query. More chunks = more context but higher cost. |
| **Chunk size** | 1024 | Maximum tokens per chunk when splitting documents. Smaller = more precise retrieval; larger = more context per result. |
| **Chunk overflow** | 64 | Token overlap between adjacent chunks, to avoid splitting mid-sentence. |

Start with the defaults and adjust if the agent gives answers that seem out of context (increase results count) or too verbose (reduce chunk size).

## Monitoring index state

Each knowledge source shows its current state:

- **Indexing** — currently being processed
- **Ready** — indexed and searchable
- **Error** — indexing failed (check the message for details)

You can trigger a manual re-index at any time with the **Re-index** button.

## Multiple knowledge bases

One agent can have multiple knowledge bases. During a conversation, Helix queries all of them and combines the results. Use separate knowledge bases when you have logically distinct content that the agent should search independently — for example, a product manual and a customer FAQ.

---

By default, an agent app is only reachable through the Helix chat UI. Triggers let the agent respond in external channels or run on a schedule.

Configure triggers in your agent app under the **Triggers** tab.

## Cron (scheduled)

Run the agent on a schedule with a fixed input:

```
Schedule: 0 9 * * 1-5
Input: Generate a summary of open issues assigned to the team.
```

Standard 5-field cron syntax, UTC. The agent runs the input prompt at each scheduled time and sends the result to the channel where the trigger is configured (Slack, email, webhook) — or stores it if no output channel is set.

Useful for: daily standup summaries, weekly reports, monitoring alerts.

## Slack

1. In the **Triggers** tab, click **Add Trigger → Slack**.
2. Click **Connect to Slack** and authorise the Helix Slack app in your workspace.
3. Choose the channels to monitor.

The agent responds to:
- Direct messages to the bot
- @-mentions in the configured channels
- (Optionally) all messages in the channel

The agent replies in the same thread. Conversation history within a thread is preserved as context.

Store the bot token as a secret if you need to configure it manually:

```
SLACK_BOT_TOKEN: xoxb-...
```

## Microsoft Teams

1. Click **Add Trigger → Teams**.
2. Follow the OAuth flow to authorise the Helix Teams app.
3. Choose the team and channels to monitor.

The agent responds to @-mentions and direct messages. Replies appear in the same thread.

## Discord

1. Click **Add Trigger → Discord**.
2. Provide the Discord bot token (stored as a secret).
3. List the server and channel names to monitor.

The agent responds to messages that @-mention the bot or are posted in configured channels.

## Webhook

Webhooks let any external system trigger the agent with a POST request.

1. Click **Add Trigger → Webhook**.
2. Helix generates a unique URL. Copy it.

Call it with a JSON body:

```bash
curl -X POST https://app.helix.ml/api/v1/sessions/webhook/<id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"input": "Summarise the latest deployment status"}'
```

The response body is the agent's reply. Use `?stream=true` to stream tokens as they are generated.

Webhooks are useful for integrating with CI/CD pipelines, incident management tools, or any system that can make an HTTP request.

## Azure DevOps

The Azure DevOps trigger fires when work items are created or updated.

1. Click **Add Trigger → Azure DevOps**.
2. Enter your Azure DevOps organisation URL and a personal access token (store it as a secret).
3. Choose the event types (work item created, updated, commented, etc.).

The agent receives the work item payload and can comment back on the item, update fields, or route it to another system using API skills.

## Crisp (live chat)

Connect the agent to a Crisp live chat inbox:

1. Click **Add Trigger → Crisp**.
2. Provide your Crisp website ID and API credentials (store as secrets).
3. Choose whether the agent responds automatically or assists a human agent.

The agent sees the full conversation history in the Crisp inbox and can reply to customer messages directly.

## Combining triggers

An agent can have multiple triggers — for example, a Slack trigger for team use and a webhook for CI/CD integration. Each trigger fires independently; the agent handles them the same way regardless of source.

---

Every spec task in Helix runs through the same loop:

```
1. Define   You write a spec describing the desired outcome
2. Plan     An agent reads your codebase and proposes an execution plan
3. Approve  You review and approve (or give feedback to revise)
4. Implement The agent works inside an isolated sandbox
5. Review   A pull request is opened for human review and merge
```

This isn't just a workflow convention — each step exists for a specific reason.

## Why planning comes before implementation

Agents that jump straight to implementing make more irreversible mistakes. A plan is cheap to revise; committed code is expensive to undo.

The planning step also surfaces assumptions early. If the agent misunderstood the scope — planning to change the backend when you only wanted a frontend fix — you catch it before any code is written.

The plan lives in a `helix-specs` branch in your repository, which means it's reviewable, versioned, and linkable.

## Why you approve the plan

Agents are capable but not infallible. The approval step keeps a human in the loop at the highest-leverage point: before implementation starts. This is when changing direction is cheapest.

Helix doesn't require you to read every line of the plan — many teams scan the top-level steps and spot-check the details. The pull request is the real review gate.

## What happens during implementation

The agent runs inside an isolated sandbox — a containerized Linux desktop with Zed IDE, a terminal, and a browser. The sandbox has:
- Your repository pre-cloned to the approved plan's starting state
- Access to your configured LLM provider for inference
- No access to the host machine, other sandboxes, or the internet beyond what the task needs

The agent uses the same tools a developer would: reads files, edits them, runs tests, commits. It can browse the web, install packages, and run arbitrary commands — inside the container.

Each edit is committed to a working branch. If the sandbox crashes mid-implementation, commits are preserved and the agent can resume.

## Why pull requests, not direct pushes

The agent never merges to your main branch. Pull requests give you:
- A standard diff review in your existing tooling
- CI to run before merge
- A record of what changed and why (the spec task is linked)
- The ability to close the PR and try again with a revised spec

This also means Helix integrates with your existing code review culture — reviewers don't need to know Helix exists. They see a normal pull request.

## The agent loop and your role

Helix is designed around the idea that agents do better work when humans stay in the loop at the right moments:

| Step | Agent's role | Your role |
|---|---|---|
| Define | — | Write the spec |
| Plan | Analyse codebase, propose steps | Review and approve (or give feedback) |
| Implement | Make the changes | Optional: watch live, redirect if needed |
| Review | — | Review the diff and merge |

The agent handles implementation; you handle direction and quality gates.

## Parallel tasks

Multiple spec tasks can be in the Implement phase simultaneously. Each gets its own sandbox — they don't share files, processes, or network. Running tasks in parallel doesn't increase the risk to any individual task.

See [Manage your backlog](/docs/guide-manage-backlog) for how to run tasks in parallel in practice.

---

## Projects

A **project** is a workspace that links a set of repositories to a set of spec tasks and a configured agent. Everything in Helix — code intelligence, agent configuration, task history — is scoped to a project.

Think of a project as the intersection of:
- **What you're building** (the repositories)
- **How you're building it** (the agent configuration)
- **What's in progress** (the spec tasks on the board)

One project per product area or service is a common starting point. Teams with strong monorepo discipline often use one project per repo.

## Spec tasks

A **spec task** is a discrete unit of work. You describe the desired outcome; the agent plans and implements. The task is the contract between you and the agent.

A well-formed spec task has:
- A clear, testable outcome ("the login form validates email format before submission")
- A bounded scope (one feature, one fix, one change — not "improve the whole auth flow")
- No implementation instructions — those are the agent's job

Spec tasks are not the same as tickets. Tickets track intent; spec tasks track execution. Many teams write tickets in GitHub Issues or Jira and use Helix's Optimus automation to draft spec tasks from them.

## The Kanban board

Spec tasks move through stages:

| Stage | Meaning |
|---|---|
| **Draft** | Task written, not yet sent to the agent |
| **Planning** | Agent is preparing the execution plan |
| **Planned** | Plan ready, waiting for approval |
| **Approved** | Plan approved, agent about to start |
| **Implementing** | Agent is working in the sandbox |
| **Review** | Implementation done, pull request open |
| **Done** | PR merged |

The board gives you the status of all in-flight work at a glance. Multiple tasks can be in Planning or Implementing simultaneously.

## The spec branch

When a task enters Planning, the agent pushes its plan to a `helix-specs` branch in your primary repository. The plan is a Markdown file — human-readable, reviewable, and versioned in git.

This branch also accumulates implementation artifacts: notes, scratch outputs, anything the agent wants to persist across sessions. The branch is never merged to main.

## Agent configuration on a project

Each project has one agent configuration: which runtime (Claude Code, Goose, Qwen, Zed), which model and provider, and any runtime-specific settings (Goose recipes, for example).

The agent configuration is stored in the project YAML alongside the spec tasks. Changing the agent configuration affects new tasks; tasks already in progress continue with the agent they started with.

See [Choose and configure a code agent](/docs/guide-choose-code-agent) for the runtime options.

## Optimus: automated backlog management

Optimus is an optional agent you can enable on a project. When enabled, it watches your GitHub Issues on a schedule and drafts new spec tasks from them — so issues flow into the board without manual triage.

Optimus is also available interactively: ask it to plan the next sprint, estimate task complexity, or review a draft spec for completeness.

---

Helix has two types of agent. They look similar on the surface — both use LLMs and have tools — but they serve different purposes and are configured differently.

## Agent apps

**Agent apps** are conversational agents you build in the Helix UI. An agent app has a system prompt, an LLM, optional skills (web search, APIs, MCP servers), optional knowledge bases (RAG), and optional triggers (Slack, cron, webhook). You might build an agent app to:

- Answer customer questions grounded in your product documentation (RAG)
- Respond to support tickets via Slack or Teams
- Generate weekly reports on a schedule
- Call internal APIs based on user requests
- Handle live chat with a Crisp integration

Agent apps are created in **Agents → New Agent** and accessed via the Helix chat UI, an embedded widget, or the API. See [Build an agent app](/docs/guide-agent-apps) for the full configuration walkthrough.

## Code agents

**Code agents** run inside sandboxes and do software development. They read and write files, run tests, commit code, and open pull requests. They're what powers spec tasks.

Four code agent engines are available: Claude Code, Goose, Qwen Code, and Zed Agent. They all run in the same sandbox desktop; the difference is the harness, model access, and workflow features each brings.

Code agents are configured per project (as the `agent:` block in the project YAML) and are not interchangeable with agent apps.

## Why two types?

The distinction reflects a difference in how the two agents are used and what they're optimised for:

| | Agent apps | Code agents |
|---|---|---|
| **Where they run** | In the Helix API process | Inside isolated sandbox containers |
| **What they do** | Converse, answer, call APIs | Read code, edit files, commit, test |
| **Time horizon** | One conversation turn | Hours of autonomous work |
| **Approval model** | None (conversational) | Plan approval before implementation |
| **Output** | Text, structured data | Git commits, pull requests |

An agent app that you ask "what does this function do?" is a different thing from a code agent that rewrites it.

## The four code agent engines

These are not four different products — they're four pluggable engines for the same loop. Pick one per project:

- **Claude Code** — Anthropic's own CLI, best model quality for coding, uses your Anthropic key or subscription
- **Goose** — open-source, adds parameterised recipes for repeatable task types
- **Qwen Code** — open-source, works with any OpenAI-compatible provider including local models
- **Zed Agent** — Zed's built-in agent panel, no extra CLI, in-editor experience

See [Choose and configure a code agent](/docs/guide-choose-code-agent) for when to pick which.

## The agent loop

All code agents run through the same plan→implement→review loop. The engine choice doesn't change the structure of the loop; it changes the quality, cost, and workflow features within the implement step.

See [How the agent loop works](/docs/concept-agent-loop) for the full picture.

---

## What a sandbox is

A **sandbox** is an isolated Linux desktop environment that Helix provisions for each spec task session. It's where the code agent actually runs — not in the Helix control plane, and not on your workstation.

Each sandbox gets:
- A containerized Ubuntu Linux desktop (Wayland/Sway or GNOME/Xwayland)
- Zed IDE with the agent connected via the Agent Client Protocol (ACP)
- A terminal with standard developer tooling (git, docker, curl, etc.)
- Firefox browser
- Your repository pre-cloned from its connected source

The agent's desktop is streamed to your browser over WebSocket as H.264 video, so you see exactly what the agent sees in real time.

## Isolation model

Helix uses a three-tier isolation model:

```
HOST MACHINE
│
├── Helix Control Plane (API, UI, Postgres)
│
└── Helix Sandbox Container (Docker-in-Docker)
    │
    └── Hydra (multi-tenant isolation layer)
        ├── Agent Session A  ← separate dockerd, separate network
        ├── Agent Session B  ← separate dockerd, separate network
        └── ...
```

**Hydra** is the isolation layer inside the sandbox. Each concurrent agent session gets:
- Its own Docker daemon
- Its own network bridge with a non-overlapping subnet
- Its own filesystem

Sessions cannot see each other's containers, processes, or network traffic. A malicious or runaway agent in one session cannot affect other sessions or the host.

## What the agent can and can't do

Inside its sandbox, an agent can:
- Read and write any file in its filesystem
- Run arbitrary shell commands, install packages, start Docker containers
- Browse the web and call external APIs from its browser and terminal
- Commit to git and push to the connected repository's working branch

An agent cannot:
- Access the host machine's filesystem
- See or affect other sandboxes or sessions
- Read secrets from the Helix control plane (API keys are proxied, not exposed)
- Push directly to your main branch (Helix creates a working branch)

## Hardware video encoding

The agent's desktop is captured and encoded to H.264 before streaming. Helix uses hardware encoding where available:
- **NVIDIA GPUs**: NVENC
- **AMD/Intel GPUs**: VA-API
- **No GPU**: software OpenH264 / x264 fallback

Hardware encoding gives 60 FPS streaming with minimal CPU overhead. The Mac App uses Apple Silicon's media encoders.

## Sandbox lifetime and persistence

A sandbox exists for the duration of a spec task session. When a session ends:
- The container is destroyed
- Uncommitted files are lost
- Committed files are on the agent's working branch in your repository

If a session ends unexpectedly (network drop, host restart), start a new session from the task view — Helix re-clones the repository from the last committed state and the agent picks up where it left off.

## Operating sandboxes

For configuration, tuning, and resource planning, see:
- [Linux & Kubernetes](/docs/deploy-linux-kubernetes) — sandbox chart install, GPU config, video streaming tuning
- [Work in a sandbox](/docs/guide-sandbox) — how to interact with an agent's desktop day-to-day

---

## What code intelligence is

Helix Code Intelligence (powered by [Kodit](https://github.com/helixml/kodit)) builds a structured, searchable representation of your repositories. It's not a simple file index — it understands code structure: what each function does, how it connects to others, what patterns the codebase uses.

This index powers both human tools (semantic search, the wiki, the changelog) and agent tools (the same search capabilities, exposed via MCP so agents can query it during implementation).

## Why it matters for agents

An agent without code intelligence works like a developer who's never seen your codebase:
- Re-reads large swaths of files to build context
- Misses relevant code elsewhere in the repository
- Writes new implementations of things that already exist
- Changes function signatures without finding all callers

An agent with code intelligence can:
- Search for existing implementations before writing new ones
- Find all callers of a function before changing it
- Understand the architecture of a component before modifying it

In practice: less duplication, fewer broken interfaces, faster implementation.

## How the index is built

When you connect a repository, Helix indexes it in the background:

1. **Parse** — extract the code structure (functions, classes, imports, relationships) across all files and languages
2. **Embed** — generate vector representations for semantic similarity search
3. **Store** — write the index to Kodit's vector database (pgvector + vectorchord)
4. **Refresh** — re-index changed files on every push

For most repositories, initial indexing completes in a few minutes. Very large repositories (500k+ lines) may take 15–30 minutes on first index.

## Supported languages

Kodit supports all common languages including Go, Python, TypeScript/JavaScript, Java, Rust, C/C++, Ruby, and PHP. The index quality is best for languages with strong structural conventions; dynamic languages with heavy metaprogramming may have lower recall.

## The automated wiki

For each indexed repository, Helix generates a wiki — prose pages describing major components, their purpose, and their relationships. The wiki is:
- Generated automatically from the code, not from comments or README
- Updated on each push
- Accessible to humans via the Code Intelligence tab and to agents via MCP

The wiki is not a substitute for good documentation, but it provides a floor: even undocumented codebases get a navigable overview.

## Cross-repository search

Code intelligence works across all repositories attached to a project. An agent working on a frontend can search the backend's API to understand the contract before changing a type, for example.

You can also index external public repositories (shared libraries, SDKs) separately from your project repositories.

## MCP access for local IDEs

The Kodit MCP server is accessible externally. Connect your local IDE or Claude Desktop to the same index your agents use:

```json
{
  "mcpServers": {
    "helix-code-intelligence": {
      "url": "https://your-helix-url/mcp/kodit",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}
```

Find the URL and token in **Settings → Code Intelligence → MCP Access**.

## Performance benchmark

In internal experiments on the SWE-bench coding benchmark, code intelligence improved agentic coding performance by 20% compared to agents without it. The improvement is largest on tasks that require finding and modifying existing code, and smallest on tasks that require writing new code from scratch.

---

## The core promise

Helix is designed so that code and credentials stay where you put them. When you run Helix on your own infrastructure, your source code, API keys, SSH keys, and `.env` files never leave your hardware — not even for inference, if you configure local models.

When you use Helix Cloud, your code is held in our infrastructure within the region you selected. We don't train on your data.

## Agent isolation

Every spec task session runs in its own isolated container with:
- **Separate filesystem** — no access to the host or other sessions
- **Separate network** — each session gets its own network bridge with a non-overlapping subnet; sessions cannot see each other's traffic
- **Separate Docker daemon** — via the Hydra isolation layer inside the sandbox

Even if an agent runs a malicious command (or you make a mistake in a spec task), the blast radius is the session's container. The host machine and other sessions are unaffected.

See [Sandboxes and the desktop environment](/docs/concept-sandboxes) for the technical architecture.

## Credentials and secrets

Credentials used by agents are never stored in plaintext. Helix uses AES-256-GCM encryption at rest for:
- Git provider OAuth tokens (GitHub, GitLab, Bitbucket)
- SSH keys
- AI provider API keys
- Any secrets you configure for assistants or API integrations

The encryption key is operator-controlled (set at install time via `helix-encryption-key`). Helix never sees an unencrypted copy of your secrets after they're stored.

Inside a sandbox, agents access your source control provider via Helix's credential proxy — the agent never receives your raw OAuth token or SSH key. If the sandbox is compromised, the credential it used expires with the session.

## Inference routing

When agents call LLMs, the request routes through Helix's `/v1` proxy on your control plane. The raw API key is on the control plane; the agent in the sandbox gets a short-lived session token to the proxy.

For users who want LLM inference to stay on-premises entirely, local models can be served via Ollama or vLLM on the same cluster. In this configuration, no request leaves your infrastructure.

## Code never reaches Anthropic/OpenAI directly

When an agent calls an LLM via the Helix proxy, the prompt content (which may include code snippets) goes to the LLM provider you configured. For Anthropic and OpenAI, this is subject to their API terms. If this is a concern:
- Use a self-hosted vLLM or Ollama endpoint (inference stays on-premises)
- Use Anthropic's zero data retention API tier (opt-in via their console)

## Data residency

| Deployment | Where your data lives |
|---|---|
| Helix Cloud | HelixML-managed infrastructure (region selected at sign-up) |
| Mac App | Your machine only — nothing leaves your hardware |
| Linux / Kubernetes | Your cluster — you control every node |
| Sovereign Server | Your data centre — the physical hardware is yours |

## Access controls

- **Organization-level isolation** — all resources (projects, tasks, repos, secrets) are scoped to an organization. Users in organization A cannot see organization B's data.
- **Role-based access** — team members can be granted admin, member, or read-only roles per project
- **SSO** — Helix supports OIDC-compatible SSO providers; see [Sovereign Server — SSO & RBAC](/docs/deploy-sovereign-server) for configuration
- **Audit logging** — all user actions are logged on self-hosted deployments

For enterprise access control configuration (RBAC, SSO, SCIM), see [Sovereign Server — SSO & RBAC](/docs/deploy-sovereign-server).

---

> 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

---

Helix Org is a framework for running AI agents as **workers** inside a structured organisation. Where regular Helix agent apps respond to individual user requests, Helix Org workers are persistent, role-based agents that subscribe to event streams, collaborate with each other, and escalate to human managers when needed.

This is distinct from [user organisations](/docs/guide-organizations), which are shared workspaces for collaboration. Helix Org is an AI-native org chart.

## Core concepts

### Workers

A worker is a running AI agent with a defined role and identity. The worker model is designed for two kinds:

- **AI workers** — powered by an LLM, activated by events, execute tasks autonomously. This is the only kind currently available.
- **Human workers** — real people who receive escalations and send instructions. Support for hiring human workers is under development.

Workers are hired into roles. A worker's behaviour is governed by three files: `role.md` (what the worker does), `identity.md` (how the worker behaves), and `agent.md` (org-wide policy).

### Roles

A role defines a worker's responsibilities, tools, and activation conditions. Roles are version-controlled YAML/Markdown files. An operator edits a role to change what a worker does; the change takes effect on the next activation.

Example roles: Documentation Engineer, QA Analyst, Code Reviewer, Customer Support Agent.

### Streams

Streams are typed event channels. Workers subscribe to streams that are relevant to their role and publish to streams when they produce output. Streams decouple producers from consumers: a stream can have many subscribers, and a worker doesn't need to know who is listening.

**Stream types:**

| Type | Used for |
|------|----------|
| GitHub | Push events, PR comments, issue activity |
| Local | Internal org communication |
| Direct message | 1:1 channel restricted to the reporting graph — a worker can only DM its direct managers or its own direct reports |
| Team | Broadcast to all direct reports |
| Activation log | Per-worker transcript of each activation |

### Activations

An activation is a single turn of a worker's work loop. A worker is activated when an event arrives on a subscribed stream, runs its task, and exits. The next event triggers the next activation. Workers are stateless between activations; persistent state is stored in a designated state file in the helix-specs branch.

## How Helix Org differs from agent apps

| | Agent apps | Helix Org workers |
|---|---|---|
| **Trigger** | User sends a message | Event on a subscribed stream |
| **Lifecycle** | One request → response | One activation per event, indefinitely |
| **Coordination** | None | Reporting lines, escalation, DMs |
| **State** | Conversation history | State file persisted to git |
| **Identity** | System prompt | role.md + identity.md + agent.md |
| **Use case** | User-facing chatbot | Background process in an org workflow |

## Typical Helix Org patterns

**Automated documentation** — a Documentation Engineer worker subscribes to the main branch push stream. When code changes land, it reads the diff, decides if docs need updating, and opens a PR.

**QA analysis** — a QA Analyst worker subscribes to CI result streams and DMs the team when a test suite regresses.

**Support triage** — a Support Triage worker subscribes to a webhook from your support platform, classifies incoming tickets, and routes them to the right team.

**Multi-worker pipelines** — a Planner worker receives a feature request, breaks it into tasks, and publishes them to a task stream where individual Developer workers pick them up.

## Setting up Helix Org

Helix Org is configured via the **Helix Org** section in the left sidebar. From there you can:

- **Workers** — view running workers; filter the list by role using the dropdown above the table. Hire a new worker with **+ New Worker**: select a role, optionally set a **Reports to** parent worker to place them in the org hierarchy, then confirm. The hired worker starts on its next triggering event.
- **Roles** — create roles with **+ New Role** and edit existing role specifications. Every role — new or existing — automatically includes a set of baseline read tools: `subscribe`, `read_events`, `managers`, `reports`, `worker_log`, and `mint_credential`. These are injected at role creation and backfilled on existing roles at API start, so a role specification never needs to list them explicitly.

`managers` returns the workers the caller reports to; `reports` returns its direct reports. Each result includes the `dmStreamId` needed to open a direct message. Because `dm` enforces reporting-graph scope, these tools are the correct way to discover valid DM targets before sending a message.
- **Streams** — create and monitor event streams
- **Org chart** — visualise the reporting structure; connect workers with reporting lines and delete connections by hovering over a line

Worker runtime settings (which LLM, which code agent engine) are configured per-worker in **Helix Org → Settings**.

## Worker credentials

Workers that run `git`, `gh`, or authenticated API calls need a GitHub token. Tokens are not pre-loaded into the container — instead, workers call the `mint_credential` MCP tool at the start of any authenticated operation and again if they receive a 401 or 403.

`mint_credential` is included in every worker's baseline tools and returns a short-lived token tied to the org's GitHub identity:

```
mint_credential provider=github
→ { token: "ghs_…", expires_at: "2026-06-11T12:59:00Z" }
```

The pattern a worker role should follow:

1. Call `mint_credential` with `provider=github` before the first `git` or `gh` command each activation.
2. Export the result: `export GH_TOKEN=<token>`.
3. If a command returns 401 or 403, call `mint_credential` again and re-export — token expiry is expected for long-running work.

This means tokens are always fresh. A single token injected at container start would expire silently after ~1 hour; minting on demand removes that failure mode entirely.

## State and memory across activations

Workers persist state between activations using a dedicated branch in their per-worker git repository (`helix-specs` branch). State is written as Markdown files and committed after each activation. This means:

- State survives process restarts and re-deployments
- State is version-controlled and auditable
- Multiple workers can read each other's public state files

The recommended pattern is a `state.md` file that the worker updates after each meaningful activation, acting as a running log for the worker's future self.

---

## Project YAML

Projects are defined in YAML. The full schema:

```yaml
apiVersion: helix.ml/v1alpha1
kind: Project
metadata:
  name: my-app                    # Used as the project identifier

spec:
  description: "What this project is for"

  repositories:
    - url: "https://github.com/org/my-app"
      branch: main
      primary: true               # The primary repo is cloned first and receives PRs
    - url: "https://github.com/org/shared-lib"
      branch: main

  agent:
    name: "My Agent"
    runtime: claude_code          # claude_code | goose_code | qwen_code | zed_agent
    model: claude-sonnet-4-6      # omit for claude_code
    provider: anthropic           # anthropic | openai | helix | (any configured provider)
    code_agent_credential_type: api_key  # api_key (default) | subscription (Claude Code only)

    # Goose-specific:
    goose:
      recipes:
        - name: triage
          path: .goose/recipes/triage.yaml
```

## Agent app YAML

Agent apps (called `assistants` in the YAML schema) configure conversational agents with skills, knowledge, and triggers. See [Build an agent app](/docs/guide-agent-apps) for a walkthrough.

```yaml
name: My Assistant
description: "What this agent app does"

assistants:
- name: Support
  model: claude-sonnet-4-6
  provider: anthropic
  system_prompt: |
    You are a helpful assistant.
  temperature: 0.3
  max_tokens: 4096
  max_iterations: 10
  agent_type: helix_agent          # helix_basic | helix_agent

  # Skills
  web_search:
    enabled: true
    max_results: 10

  browser:
    enabled: true

  # Knowledge bases (RAG) — see guide-rag-knowledge
  knowledge:
  - name: my-docs
    description: "Product documentation"
    refresh_enabled: true
    refresh_schedule: "0 */6 * * *"
    rag_settings:
      results_count: 4
      chunk_size: 1024
      chunk_overflow: 64
      enable_vision: false         # true to index images and scanned PDFs
    source:
      web:
        urls:
        - https://docs.example.com/
        crawler:
          enabled: true
          max_depth: 2
          max_pages: 200
          readability: true

  # API integrations (OpenAPI)
  apis:
  - name: My API
    description: "Internal API"
    url: https://api.example.com
    schema: ./openapi.yaml
    headers:
      Authorization: Bearer ${MY_API_KEY}

  # MCP servers — HTTP transport
  mcps:
  - name: My MCP Server
    url: https://mcp.example.com/tools
    headers:
      Authorization: Bearer ${MCP_TOKEN}

  # MCP servers — stdio transport (runs as subprocess)
  # mcps:
  # - name: Filesystem
  #   type: stdio
  #   cmd: npx
  #   args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

  # Triggers — see guide-triggers
  triggers:
  - slack:
      bot_token: ${SLACK_BOT_TOKEN}
      channels:
      - support
  - teams:
      tenant_id: ${TEAMS_TENANT_ID}
      client_id: ${TEAMS_CLIENT_ID}
      client_secret: ${TEAMS_CLIENT_SECRET}
  - discord:
      bot_token: ${DISCORD_BOT_TOKEN}
      guild_id: "123456789"
  - cron:
      schedule: "0 9 * * 1-5"
      input: "Generate daily summary"
  - webhook: {}                    # Helix generates a unique URL
  - azure_devops:
      org_url: https://dev.azure.com/myorg
      token: ${AZURE_DEVOPS_TOKEN}
      events: [work_item_created, work_item_updated]
  - crisp:
      website_id: ${CRISP_WEBSITE_ID}
      api_key: ${CRISP_API_KEY}
      api_secret: ${CRISP_API_SECRET}
```

## Control plane environment variables

These are passed via `controlplane.extraEnv` in the Helm chart (or as environment variables in a non-Kubernetes deploy). See [Linux & Kubernetes](/docs/deploy-linux-kubernetes) for how to set them.

### Desktop streaming

| Variable | Default | Description |
|---|---|---|
| `HELIX_VIDEO_MODE` | `zerocopy` | PipeWire capture: `zerocopy` (DMA-BUF→CUDA, fastest), `native` (DMA-BUF via GStreamer), `shm` (shared memory, most compatible). Use `shm` if browser shows endless reconnects. |
| `HELIX_ENCODER` | auto | H.264 encoder: `nvenc` (NVIDIA), `vaapi`/`vaapi-legacy` (Intel/AMD), `openh264`/`x264` (software). |
| `HELIX_GOP_SIZE` | `120` | Group of Pictures size in frames (120 = 2s at 60fps). Lower = faster mid-stream join. |
| `HELIX_RENDER_NODE` | unset | VA-API render device path (e.g. `/dev/dri/renderD129`). Set on multi-GPU hosts. Use `SOFTWARE` to disable VA-API. |

### Control plane behaviour

| Variable | Default | Description |
|---|---|---|
| `HELIX_DISABLE_VERSION_CHECK` | unset | Disable the upstream version-check ping at startup. Set to any non-empty value. |
| `HELIX_SKIP_AUTOMIGRATE` | unset | Skip GORM AutoMigrate on startup. Only set if you run schema migrations out-of-band. |
| `HELIX_GITHUB_BASE_URL` | `https://github.com` | Override for GitHub Enterprise Server. |
| `FRONTEND_URL` | (from serverUrl) | Public URL of the Helix UI, injected into email links and OAuth callbacks. |

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

| Variable | Default | Description |
|---|---|---|
| `HELIX_SANDBOX_APT_MIRROR` | unset | Override APT mirror for dev container bootstrapping. Useful in air-gapped environments. |

## Helm chart key reference

### helix-controlplane

| Key | Description |
|---|---|
| `global.serverUrl` | Public URL of the deployment. **Must be set correctly** — sandboxes use it to reach the control plane. |
| `controlplane.licenseKeyExistingSecret` | Kubernetes secret name containing the license key |
| `controlplane.encryptionKeyExistingSecret` | AES-256-GCM encryption key secret. **Do not rotate after data is written.** |
| `controlplane.runnerTokenExistingSecret` | Shared token for sandbox↔control-plane auth |
| `controlplane.providers.*` | LLM provider configuration (see [Configure LLM providers](/docs/guide-llm-providers)) |
| `controlplane.extraEnv` | Additional environment variables for the control plane pod |
| `global.extraEnv` | Environment variables for all pods (useful for proxy settings) |

### helix-sandbox

| Key | Description |
|---|---|
| `sandbox.apiUrl` | URL of the control plane, as seen from inside the cluster |
| `sandbox.runnerTokenExistingSecret` | Must match `controlplane.runnerTokenExistingSecret` |
| `sandbox.extraEnv` | Additional environment variables for the sandbox pod |

Full `values-example.yaml` files are in the [Helix repository](https://github.com/helixml/helix/tree/main/charts).

---

Helix routes inference to external providers — it doesn't bundle models. You configure providers under **Account → AI Providers** (UI) or `controlplane.providers` (Helm).

## Providers

| Provider | Type | Notes |
|---|---|---|
| **Anthropic** | Cloud API | Claude models. Recommended for coding agents. |
| **OpenAI** | Cloud API | GPT-4 and o-series models |
| **Google** | Cloud API | Gemini models via the Gemini API |
| **Together AI** | Cloud API | Hosted open-source models (Llama, Mistral, Qwen, etc.) |
| **Helix** | Built-in | Available on Helix Cloud. Useful for getting started without your own keys. |
| **OpenAI-compatible** | Any | Any endpoint serving `/v1/chat/completions` — vLLM, Ollama, LM Studio, Anyscale, etc. |
| **Anthropic via Vertex** | Cloud API | Anthropic models routed through GCP Vertex AI |

## Model identifiers

Use these in `model:` fields in project and assistant YAML.

### Anthropic

| Model ID | Description |
|---|---|
| `claude-opus-4-8` | Most capable Claude model |
| `claude-sonnet-4-6` | Balanced capability and speed. Default for most coding tasks. |
| `claude-haiku-4-5-20251001` | Fastest, lowest cost |

### OpenAI

| Model ID | Description |
|---|---|
| `gpt-4o` | GPT-4 Omni — multimodal, strong reasoning |
| `gpt-4o-mini` | Smaller, faster, lower cost |
| `o3` | High-reasoning model for complex tasks |
| `o4-mini` | Fast reasoning |

### Google

| Model ID | Description |
|---|---|
| `gemini-2.5-pro` | Most capable Gemini model |
| `gemini-2.5-flash` | Fast and cost-efficient |

### Qwen (via Together AI or Helix runner)

| Model ID | Description |
|---|---|
| `qwen3-coder-480b` | Large coding-tuned Qwen model |
| `qwen3:8b` | Small Qwen model, runs locally |
| `qwen3:30b-a3b` | Mid-size Qwen model |

### Local / self-hosted (OpenAI-compatible)

Any model served by Ollama, vLLM, LM Studio, or another OpenAI-compatible server. The model ID is whatever that server uses:

```yaml
  agent:
    model: llama3.3          # or deepseek-r1, gemma3, mistral, etc.
    provider: ollama          # whatever you named this provider in Helix
```

## Model selection for code agents

| Code agent | Model selection |
|---|---|
| **Claude Code** | Managed internally — you don't set `model` or `provider` |
| **Goose** | Set `model` and `provider` in the project YAML |
| **Qwen Code** | Set `model` and `provider`. Works with any OpenAI-compatible provider. |
| **Zed Agent** | Set `model` and `provider`. Routes through Helix's `/v1` proxy. |

## Recommendations

For **coding tasks** (spec tasks, implementation):
- Claude Code with Anthropic → best overall code quality
- Sonnet 4.6 or Opus 4.8 for Goose/Zed/Qwen → strong alternatives
- Qwen3-Coder-480b via Together AI → best open-source option

For **chat assistants** (knowledge bases, support bots):
- Qwen3:8b → fast, low cost, runs locally
- GPT-4o-mini → good for cost-sensitive cloud deployments
- Gemini Flash → fast and multimodal

For **planning and analysis** (complex reasoning):
- o3 or Claude Opus → highest reasoning quality

---

This page lists every settings panel in Helix and what each control does. For how to configure specific features, see the relevant guide instead: [LLM providers](/docs/guide-llm-providers), [organisations](/docs/guide-organizations), [source control](/docs/guide-connect-repo).

---

## Account settings

Access from the user menu (top right) → **Account**.

### General

| Setting | What it does |
|---|---|
| **Full name** | Display name shown in comments, activity, and the org member list |
| **Password** | Change your login password (available when using email/password auth) |
| **Claude subscription** | Link a Claude Pro or Team subscription for Claude Code agent access via subscription (see [choose a code agent](/docs/guide-choose-code-agent)) |
| **Usage** | Token count, total cost, and request count for your account this billing period |
| **Quota** | Per-resource limits set by your instance admin |

### API keys

Each account has one API key used to authenticate requests to the Helix API and SDK.

| Control | What it does |
|---|---|
| **Show / Copy** | Reveal and copy the key value |
| **Regenerate** | Issue a new key; the old key stops working immediately |

The key is also accepted in the `Authorization: Bearer <key>` header and as `?api_key=<key>` in query strings.

### Chat settings

| Setting | What it does |
|---|---|
| **Theme** | Light or dark UI mode |

---

## Organisation settings

Access from the org selector → **Settings** (or **Organisation → Settings** in the sidebar). You must be an org owner to change most of these.

### General

| Setting | What it does |
|---|---|
| **Name** | Human-readable org name shown in the UI |
| **Slug** | URL-safe identifier used in org URLs (`/orgs/<slug>/...`). Cannot be changed after creation. |
| **Auto-join domain** | Email domain (e.g. `acme.com`) whose users are automatically added to this org on first sign-in |
| **Delete organisation** | Permanently deletes the org and all its projects. Irreversible. |

### Members

Invite, manage, and remove org members. Roles:

| Role | Capabilities |
|---|---|
| **Owner** | Full admin — change settings, delete org, manage members |
| **Member** | Create and run projects; cannot change org settings |

### API keys

Org-level API keys authenticate service accounts and CI integrations. They carry org-member permissions.

### Providers

Configure AI providers shared across the whole org. Members who haven't added their own providers fall back to these. See [Configure LLM providers — Organisation level](/docs/guide-llm-providers).

### Billing

Subscription and credit balance for Helix Cloud orgs. On self-hosted deployments this section is not shown.

### Secrets

Secrets are key-value pairs injected as environment variables into agent sandboxes and coding sessions for all projects in the org. Use them for API keys, tokens, and other credentials that projects need at runtime.

| Control | What it does |
|---|---|
| **Add secret** | Create a new key-value secret |
| **Delete** | Remove a secret; existing running sessions are not affected until they restart |

---

## Admin panel

Access from **Admin** in the left sidebar. Visible to instance administrators only.

### Analytics & Monitoring

#### LLM Calls

A live log of every LLM API call made through the instance — model, provider, token counts, latency, and the requesting user. Useful for auditing cost and debugging slow responses.

### Infrastructure

#### Inference Providers

Configure instance-level LLM providers available to all users. Equivalent to the per-user and per-org provider settings but applied globally. See [Configure LLM providers — Self-hosted](/docs/guide-llm-providers#self-hosted-configure-providers-via-helm) for Helm configuration; this panel lets you configure them at runtime without a redeploy.

#### OAuth Providers

Configure identity providers for user authentication:

| Provider | Notes |
|---|---|
| GitHub | OAuth App or GitHub App |
| Google | Google Cloud OAuth 2.0 client |
| OIDC | Any OIDC-compatible IdP (Okta, Keycloak, Azure AD, etc.) |

#### Service Connections

Register external service integrations (webhooks, outbound channels) used by the instance.

#### Runners

Manage compute runners from a single master-detail page. The top of the page shows instance-wide stats: online runner count, active sandbox count, and user count. Below that, a GPU statistics panel gives a global view of fleet utilisation. A runner picker dropdown (defaulting to the first online runner) lets you select any registered runner; the detail panel below shows:

- **Profile** — which inference profile is assigned to this runner
- **Logs** — live-tail log stream from the selected runner
- **Sandboxes** — sandbox containers currently running on this runner, with resource usage and session context

### Models & Configuration

#### Helix Models

Configure custom model endpoints served by Helix's own inference layer (as opposed to external API providers). Applies to self-hosted GPU deployments running Helix-served models.

#### Runner Profiles

Inference profiles map runner hardware to model configurations. A profile specifies which model to serve on which runner type, with memory and concurrency constraints.

#### Pricing

Set credit costs for sandbox usage:

| Setting | What it controls |
|---|---|
| **Headless sandbox price** | Credits per second for headless (no-desktop) sandboxes |
| **Desktop sandbox price** | Credits per second for full Ubuntu desktop sandboxes |
| **Max concurrent headless sandboxes** | Per-org limit on simultaneous headless sessions |
| **Max concurrent desktop sandboxes** | Per-org limit on simultaneous desktop sessions |

#### System Settings

Instance-wide configuration:

| Setting | What it does |
|---|---|
| **Hugging Face token** | API token for downloading gated models from HuggingFace Hub. Can also be set via the `HUGGING_FACE_HUB_TOKEN` environment variable — the UI shows which source is active. |
| **Kodit enrichment model** | LLM used by Kodit to generate semantic descriptions of code symbols during indexing |
| **Kodit text embedding model** | Embedding model used to vectorise code for semantic search |

### Code Intelligence

#### Kodit Repositories

View and manage the repositories Kodit has indexed. Trigger re-indexing or remove a repository from the index.

#### Kodit Queue

Monitor the Kodit indexing job queue — pending, running, and completed indexing tasks with timing and error information.

### User Management

#### Users

Browse all users on the instance. View last active date, org membership, and admin status. Grant or revoke admin privileges.

#### Organizations

Browse all orgs on the instance. View member count and creation date. Useful for support and billing audits.

---

## Environment variables

For self-hosted deployments, many of these settings can also be applied via environment variables passed through the Helm chart rather than the UI. See [Configuration reference — Control plane environment variables](/docs/ref-configuration#control-plane-environment-variables) for the full list.

---

## Desktop environments

Each agent sandbox runs one of three desktop configurations:

| Environment | Display server | Base image | Best for |
|---|---|---|---|
| **Sway** | Native Wayland | Ubuntu 22.04 + Sway | Lightweight, fast startup, lowest resource usage |
| **Ubuntu** | GNOME (Xwayland) | Ubuntu 22.04 + GNOME | Full desktop experience, broader app compatibility |
| **Zorin** | GNOME (Xwayland) | Zorin OS | User-friendly interface |

All three include:
- Zed IDE (connected to the code agent via ACP)
- Firefox browser
- Docker CLI
- Git
- Standard developer tooling (curl, jq, make, etc.)

The default desktop is Sway. This can be changed per-deployment in the sandbox configuration.

## Resource requirements per session

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 vCPU | 4 vCPU |
| RAM | 4 GB | 8 GB |
| GPU | Not required | 1 GPU for hardware H.264 encoding |
| Disk | 20 GB | 50 GB (for larger repo clones and Docker images) |

On NVIDIA hardware, one GPU is typically shared across multiple sessions. The sandbox streams video via H.264; without a GPU, software encoding still works but uses more CPU.

## Video streaming

The agent desktop is streamed as H.264 video over WebSocket (HTTPS). The streaming pipeline:

1. Desktop renders to Wayland compositor
2. PipeWire captures the frame
3. GStreamer encodes to H.264 (hardware or software)
4. WebSocket delivers the stream to your browser

**Encode modes** (set via `HELIX_VIDEO_MODE`):
- `zerocopy` — DMA-BUF → CUDA → NVENC. Fastest; requires NVIDIA GPU
- `native` — DMA-BUF via GStreamer 1.24+. Works on Intel/AMD
- `shm` — Shared memory. Most compatible; higher CPU usage

**Encoders** (set via `HELIX_ENCODER`):
- `nvenc` — NVIDIA (default on NVIDIA hardware)
- `vaapi` — Intel/AMD (default on AMD hardware where supported)
- `openh264` / `x264` — Software fallback

## Session lifecycle

| Event | What happens |
|---|---|
| Session start | Container created, repo cloned, agent process started |
| Session running | Video streamed, agent makes commits to working branch |
| Session end (normal) | Container destroyed, commits preserved on branch |
| Session end (crash) | Container destroyed, commits preserved on branch; new session can resume |
| Keep-alive timeout | Session ends if idle for the configured timeout (default: 30 minutes) |

## Concurrency limits

| Deployment | Concurrent sessions |
|---|---|
| Helix Cloud | Scales automatically with your plan |
| Mac App (16 GB) | ~2–3 |
| Mac App (32 GB) | ~6–8 |
| Mac App (64 GB+) | 12–15 |
| Linux / K8s | Limited by available GPU memory and CPU |

On Kubernetes, the sandbox chart's `sandbox.maxSessions` value caps concurrent sessions.

---

## Components

Helix has three distinct tiers:

### 1. Control plane

The control plane is the main Helix API and UI. It manages:
- User authentication and organizations
- Projects, spec tasks, and the Kanban board
- Repository connections and code intelligence indexing
- Assistant and agent configuration
- Orchestration of sandbox sessions

The control plane is a single Go binary serving HTTP on port 8080 (or whatever you configure). It ships as a Docker image and a Helm chart (`helix-controlplane`).

**Dependencies:**
- PostgreSQL (main database; bundled in the chart or external)
- pgvector with vectorchord extension (for RAG and code intelligence; bundled separately)
- An LLM provider for inference (configured via `controlplane.providers`)

### 2. Sandbox (Hydra)

The sandbox is a separate service that runs agent desktop sessions. It uses Docker-in-Docker to provide isolated container environments for each session.

The sandbox ships as a Helm chart (`helix-sandbox`). It connects to the control plane via a shared runner token.

**Dependencies:**
- The control plane must be reachable from inside the sandbox
- Privileged pods (for Docker-in-Docker)
- GPU nodes (for hardware video encoding; software fallback available)
- Large persistent volumes (for Docker image cache)

### 3. Agent (inside the sandbox)

The code agent (Claude Code, Goose, Qwen Code, or Zed Agent) runs inside a container that the sandbox provisions per session. The agent:
- Connects to Zed IDE via ACP
- Routes inference through the control plane's `/v1` proxy
- Clones the project's repositories
- Makes commits to a working branch

The agent process is started automatically when a sandbox session starts.

## Network diagram

```
Internet / User Browser
        │
        │ HTTPS (port 443 or 8080)
        ↓
Control Plane (API + UI)
        │
        ├── Postgres (main DB)
        ├── pgvector (vector DB for RAG/code intelligence)
        ├── SearXNG (web search for assistants)
        └── Chrome (headless browser for assistants)
        │
        │ Internal HTTP (runner token auth)
        ↓
Helix Sandbox (Docker-in-Docker host)
        │
        └── Hydra (session isolation)
            ├── Agent Session A ──────────────┐
            │   └── Code Agent                │ WebSocket
            ├── Agent Session B               │ (H.264 video)
            └── ...                           ↓
                                       User Browser
```

The video stream for agent desktop sessions goes directly from the sandbox to the user browser over WebSocket — the control plane doesn't proxy video.

## Ports

| Service | Port | Notes |
|---|---|---|
| Control plane API + UI | 8080 | The main entry point for users |
| Sandbox (internal) | 8080 | Internal only; not exposed to users |
| Agent video WebSocket | 8080+ | Multiplexed through the control plane URL |

For production, put a reverse proxy (nginx, Traefik) in front of the control plane to handle TLS and serve on 443.

## `global.serverUrl`

The `global.serverUrl` Helm value (or `FRONTEND_URL` env var) is the public URL that:
- Users type into their browsers
- OAuth callbacks return to
- Sandbox containers use to reach the control plane API for inference

**This must be set correctly.** In Kubernetes, `localhost` resolves to the pod itself — if you set this to `http://localhost:8080`, agent inference will fail with connection errors. Set it to either:
- The cluster-internal service URL: `http://my-helix-controlplane.helix.svc.cluster.local`
- Your public ingress hostname: `https://helix.example.com`

## What you provide

| What you provide | Notes |
|---|---|
| LLM provider API keys | Anthropic, OpenAI, etc. — or a self-hosted endpoint |
| Source control OAuth app | GitHub App, GitLab OAuth consumer, or Bitbucket OAuth consumer |
| TLS termination | Ingress with cert-manager or a load balancer |
| License key | From [your account](/account/licenses) |
| Encryption key | 32-byte hex string; generate once, never rotate |
| Storage | PVCs for Postgres, pgvector, and the control plane data volume |
| GPU nodes (optional) | For hardware video encoding; software fallback available |

## Scaling

- **Control plane**: Stateless beyond the database. Scale horizontally by adding replicas; use a shared Postgres and pgvector.
- **Sandbox**: Scales by adding GPU nodes. The sandbox chart can run on multiple nodes; Hydra distributes sessions.
- **Database**: Use a managed Postgres (Amazon RDS, Cloud SQL, Azure Flexible Server) for production HA. Keep pgvector on the bundled chart (it requires extensions that managed services don't provide).

---

## 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 RBAC, SSO, SOC 2 Type II, and dedicated onboarding. [Enterprise licensing →](/account/enterprise)

Helix runs on any Kubernetes cluster — bare metal, Hetzner, OVH, AWS (EKS), GCP (GKE), or Azure (AKS). If you can run containers, you can run Helix.

For air-gapped deployments, see [Sovereign Server](/docs/deploy-sovereign-server).

---

## Single Linux server

To install Helix on a Linux server with NVIDIA or AMD GPU support:

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

The installer detects your hardware and configures the sandbox automatically. On NVIDIA GPUs, hardware H.264 encoding is enabled automatically.

After installation, access Helix at `http://localhost:8080`. The first registered user becomes an admin.

---

## Kubernetes install

### Helm charts

Helix ships as two separate Helm charts:

| Chart | Purpose | Required? |
|---|---|---|
| `helix-controlplane` | API, UI, RAG, and orchestration | Yes |
| `helix-sandbox` | Docker-in-Docker host for agent desktop sessions | Recommended (required for spec tasks and coding agents) |

Both charts are published to `https://charts.helixml.tech`.

### Prerequisites

- Kubernetes 1.28+. AKS/EKS/GKE Autopilot is not supported (sandbox requires privileged pods).
- `kubectl` and Helm 3.x
- A Helix license key from [your account](/account/licenses)
- A `StorageClass` that supports `ReadWriteOnce` PVCs
- At least **8 vCPU / 24 GiB RAM** for a minimal control-plane-only install (the Haystack embedding sidecar loads a ~4 GB model on first start)
- At least one LLM provider (OpenAI, Anthropic, Together, or any OpenAI-compatible endpoint)

### Cloud GPU quota

On fresh AWS/Azure/GCP accounts, GPU quota is 0 by default. Request quota before starting:
- **AWS**: `g5`/`p4d` EC2 families per region
- **Azure**: `NVadsV710v5` (AMD) or `NC*`/`ND*` (NVIDIA) families + "Total Regional vCPUs"
- **GCP**: `nvidia-*` GPU quotas per region

### Step 1: Create namespace and secrets

```bash
kubectl create namespace helix
kubectl config set-context --current --namespace=helix

# Postgres credentials
kubectl create secret generic postgresql-auth-secret \
  --from-literal=username="helix" \
  --from-literal=password="$(openssl rand -hex 16)" \
  --from-literal=database="helix"

# pgvector credentials
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"

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

# Encryption key — generate once, never rotate
kubectl create secret generic helix-encryption-key \
  --from-literal=encryption-key="$(openssl rand -hex 32)"

# Runner token — shared between control plane and sandbox
kubectl create secret generic helix-runner-secrets \
  --from-literal=api-token="$(openssl rand -hex 32)"
```

### Step 2: Create values.yaml

```yaml
global:
  # Public URL — must be reachable from inside the cluster for sandbox inference.
  # Do NOT use localhost here.
  serverUrl: http://my-helix-controlplane.helix.svc.cluster.local

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

controlplane:
  licenseKeyExistingSecret: "helix-license"
  licenseKeyExistingSecretKey: "license-key"
  runnerTokenExistingSecret: "helix-runner-secrets"
  runnerTokenExistingSecretKey: "api-token"
  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"

  # Add at least one LLM provider
  # providers:
  #   anthropic:
  #     apiKey: "sk-ant-..."
  #   openai:
  #     apiKey: "sk-..."

persistence:
  enabled: true
  size: 100Gi

postgresql:
  enabled: true
  auth:
    existingSecret: "postgresql-auth-secret"
    usernameKey: "username"
    passwordKey: "password"
    databaseKey: "database"
  persistence:
    enabled: true
    size: 10Gi
```

### Step 3: Add LLM provider secrets and configure them

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

Add to `controlplane.providers` in your values.yaml:

```yaml
controlplane:
  providers:
    anthropic:
      existingSecret: "anthropic-api-key"
      existingSecretApiKeyKey: "api-key"
```

See [Configure LLM providers](/docs/guide-llm-providers) for all supported providers.

### Step 4: Install the control plane

```bash
helm repo add helix https://charts.helixml.tech
helm repo update

helm upgrade --install my-helix-controlplane helix/helix-controlplane \
  -f values.yaml
```

First boot pulls the embedding model (~4 GB). Budget 5–10 minutes before the main pod becomes Ready.

### Step 5: Install the sandbox chart

```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 in the repository:
- [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)

### Step 6: Access the control plane

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

Open [http://localhost:8080](http://localhost:8080). The first registered user becomes an admin.

For production, configure an ingress with TLS and set `global.serverUrl` to the public HTTPS URL.

---

## Environment variables and tuning

See [Configuration reference](/docs/ref-configuration) for the full list of `controlplane.extraEnv` and `sandbox.extraEnv` variables (video streaming tuning, encoder selection, GPU render node, etc.).

---

## External Postgres

The control plane chart can use a managed Postgres instead of the bundled one. However, the bundled **pgvector** sidecar requires the `vectorchord` and `vectorchord-bm25` extensions, which managed services (Azure Flexible Server, RDS, Cloud SQL) don't provide out of the box. Keep `pgvector.enabled: true` and use the bundled pod for the vector index.

---

## Upgrading

See [Upgrade & migrate](/docs/deploy-upgrade) for the recommended procedure.

---

We ship a fully configured rack server to your data centre with Helix pre-installed. 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.

[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)

---

## Hardware

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

**Base configuration:**

| Component | Specification |
|---|---|
| **GPUs** | 8× NVIDIA RTX 6000 Pro (Blackwell, 96 GB GDDR7 each — 768 GB total VRAM) |
| **CPU** | Dual Intel Xeon 6 Series |
| **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 spec the server to your workload during onboarding.

---

## What's included

**Hardware** — Server assembled, tested, and burned in before shipping.

**Software** — Full Helix stack pre-installed: inference, RAG, agents, agent desktops, fleet orchestration, observability. Ready on first boot.

**Onboarding** — An 8-week structured onboarding with the Helix team covering git workflow integration, CI/CD pipelines, SSO, and Slack/Teams setup. Weekly check-ins.

**First-year license** — Enterprise license included. Renews annually after year one.

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

---

## SSO and RBAC

The Sovereign Server runs Helix Enterprise, which includes:

- **OIDC SSO** — connect to any OIDC-compatible provider (Okta, Azure AD, Google Workspace, Keycloak)
- **SAML 2.0** — for providers that don't support OIDC
- **RBAC** — admin, member, and read-only roles per organization and project
- **SCIM provisioning** — automate user lifecycle via your IdP

### Configuring SSO

SSO is configured in the Helix admin panel under **Settings → Authentication**. You'll need:
- Your IdP's authorization endpoint, token endpoint, and JWKS URI
- A client ID and client secret from your IdP
- The Helix callback URL to register: `https://your-helix-url/api/v1/auth/callback`

For Azure AD / Entra ID, create an App Registration. For Okta, create an OIDC application. The Helix team will help configure this during onboarding.

---

## Air-gapped operation

The Sovereign Server is designed to operate with no outbound internet access after initial setup. All inference runs on the local GPUs; all data stays on the hardware.

In air-gapped mode:
- Disable the version check: set `HELIX_DISABLE_VERSION_CHECK=1` in the control plane environment
- Configure an internal APT mirror for sandbox container bootstrapping: set `HELIX_SANDBOX_APT_MIRROR` to your mirror URL
- For private CAs and internal TLS: inject your CA certificate into the system trust store during onboarding
- For internal git servers (GitHub Enterprise, GitLab self-hosted): set `HELIX_GITHUB_BASE_URL` or the equivalent for your provider

---

## License and activation

The server ships pre-licensed for the first year. License keys are managed by the Helix team via the onboarding process.

For renewal and additional seat licenses, contact [sales@helix.ml](mailto:sales@helix.ml) or log in to [your account](/account/sovereign).

---

## Upgrade and maintenance

Helix software upgrades are delivered as Docker image updates. The Helix team coordinates upgrades during onboarding and provides a maintenance schedule.

See [Upgrade & migrate](/docs/deploy-upgrade) for the general upgrade procedure.

---

This page covers settings for people managing the Mac App for a team. If you're setting up the Mac App for the first time, see [Mac App (Get Started)](/docs/install-mac).

## Licensing

The Mac App requires a license activated against your Helix account.

- **Individual**: Included with a personal Helix Cloud subscription
- **Team**: Up to 15 seats under one Mac App license. Each Mac is a separate deployment.
- **Enterprise**: Unlimited seats, SSO, RBAC — [contact sales →](/contact)

Licenses are managed at [app.helix.ml/account/licenses](/account/licenses).

## Local VM management

The Mac App runs a local UTM virtual machine to host the sandbox containers. This VM is created on first launch and runs in the background.

**Disk expansion**: Agent sessions clone repositories and may cache Docker images. If the VM runs low on disk, expand it from the Mac App menu → **Virtual Machine → Expand disk**. Add at least 50 GB at a time; the VM cannot shrink.

**VM restart**: If agent sessions hang or the video stream stops, restart the VM from the Mac App menu → **Virtual Machine → Restart**. Active sessions will be lost; in-progress commits are preserved on the working branch.

**VM reset**: Recreates the VM from scratch. Use this if the VM is badly corrupted. All uncommitted agent work and cached Docker images will be lost. Do this during off-hours.

## LAN sharing

LAN sharing lets your team access your Mac's Helix instance from other machines on the same network without exposing anything to the internet.

Enable it in the Mac App settings. Once enabled, the app displays a LAN URL like `http://192.168.1.42:8080` that teammates can open in their browsers.

LAN sharing is read/write — teammates can create projects, run spec tasks, and watch agent desktops. There is no per-user authentication on the LAN URL by default; configure network-level access controls if needed.

## Updates

The Mac App updates automatically. Check the current version and update status from the Mac App menu → **Check for Updates**.

Major version updates may require VM recreation — the app will prompt you before proceeding. Minor updates apply without restarting active sessions.

## Running fully local (no internet)

The Mac App can run entirely without an internet connection if you:
1. Use a local LLM provider via Ollama (requires 64 GB+ unified memory for useful models)
2. Connect only to local or self-hosted git servers

Toggle wifi off — the app continues to work. Sandboxes may fail to install packages if they require internet access; pre-warm the Docker image cache for the packages your agents use.

## Connecting to Helix Cloud

If your team uses both the Mac App and Helix Cloud, you can connect the Mac App to Helix Cloud for shared projects, team members, and billing:

Go to the Mac App settings → **Cloud Account** and sign in with your Helix Cloud credentials.

When connected, Helix Cloud projects appear in the Mac App. Spec tasks you run locally use the Mac's sandbox (data stays local); spec tasks run from a teammate's browser use Cloud sandboxes.

---

## Kubernetes upgrade

Helix uses rolling updates via Helm. The general procedure:

```bash
helm repo update

# Check the new chart version before applying
helm search repo helix/helix-controlplane --versions | head -5

# Upgrade the control plane
helm upgrade my-helix-controlplane helix/helix-controlplane \
  -f values.yaml

# Upgrade the sandbox
helm upgrade 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
```

The control plane runs database migrations automatically on startup (`GORM AutoMigrate`). If you prefer to run migrations out-of-band, set `HELIX_SKIP_AUTOMIGRATE=1` and apply the schema changes before upgrading the pod.

### Before upgrading

1. **Check the release notes** for breaking changes. Find them in the [GitHub releases](https://github.com/helixml/helix/releases).
2. **Back up Postgres** before any major version upgrade (see [Backup & restore](#backup--restore) below).
3. **Check active sessions**: active spec task sessions will be interrupted when the sandbox pod restarts. Schedule upgrades during low-activity periods.

### Pinning a specific version

The chart's `appVersion` is pinned to a tested release. To pin to a specific Helix version:

```bash
helm upgrade my-helix-controlplane helix/helix-controlplane \
  -f values.yaml \
  --set image.tag="2.9.31"
```

Do not use `image.tag=latest` — no `:latest` tag is published.

---

## Single-server upgrade

For installations using the install script (`install.sh`), pull the latest images and restart:

```bash
docker compose pull
docker compose up -d
```

The control plane runs database migrations automatically on startup.

---

## Backup & restore

### What to back up

| Data | Where it lives | How to back up |
|---|---|---|
| Main database | Postgres (postgresql PVC or external) | `pg_dump helix > helix_backup.sql` |
| Vector database | pgvector pod (pgvector PVC) | Can be rebuilt from repos; backup optional |
| File store | controlplane data PVC | `kubectl cp` or volume snapshot |

The main Postgres database contains everything critical: users, organizations, projects, spec tasks, secrets, and repository connections. The vector database and file store can be rebuilt if lost.

### Postgres backup

```bash
# Port-forward to the Postgres pod
kubectl port-forward svc/my-helix-controlplane-postgresql 5432:5432 &

# Dump
pg_dump -h localhost -U helix helix > helix_$(date +%Y%m%d).sql

# Restore (on a new cluster)
psql -h localhost -U helix helix < helix_20260610.sql
```

For production, use scheduled `pg_dump` to an S3 bucket or equivalent, or use your cloud provider's managed backup feature.

### Restoring after disaster

1. Provision a new Kubernetes cluster
2. Create the same secrets (same encryption key — if you lose this, secrets at rest are unrecoverable)
3. Restore the Postgres dump
4. Run the Helm install
5. The control plane migrates the schema on startup; existing data is preserved

---

## Migrating between environments

To move from one cluster to another (e.g., dev → prod):

1. `pg_dump` the source Postgres
2. Provision the target cluster with the same encryption key (it's needed to decrypt stored secrets)
3. Install Helix on the target with `HELIX_SKIP_AUTOMIGRATE=1`
4. Restore the dump to the target Postgres
5. Re-enable migrations (remove `HELIX_SKIP_AUTOMIGRATE`) and restart

Source control OAuth tokens and API keys were encrypted with the encryption key — they travel with the dump and work on the target as long as the encryption key matches.

---

## Observability

See your platform logs:

```bash
docker compose logs -f            # single-server
kubectl logs -f deploy/my-helix-controlplane    # Kubernetes
kubectl logs -f deploy/my-helix-sandbox         # sandbox
```

Key log patterns to watch:
- `schema migrated` — database migration completed
- `bootstrapping org` — first-request org setup ran
- `session started` — agent session provisioned
- `error starting session` — sandbox session failed to start (check GPU resources)

---

## Agent session won't start

**Symptom:** Clicking "Start Planning" or "Start Implementation" does nothing, or the session shows "Starting..." indefinitely.

**Check:**
1. Is the sandbox running? In the Helix admin panel, check **System → Sandbox status**.
2. Is there an LLM provider configured? Without a provider, the agent can't generate plans. Go to **Account → AI Providers**.
3. Does the sandbox have GPU resources? On Kubernetes, check that GPU nodes are available: `kubectl get nodes -l accelerator=nvidia`.

**Fix:** Restart the sandbox pod (`kubectl rollout restart deploy/my-helix-sandbox`), or check the sandbox logs for the error.

---

## "Still waiting for setup..." in the agent desktop

**Symptom:** The agent's video stream shows "Still waiting for setup..." and never proceeds to Zed.

**Cause:** The desktop setup script (`helix-workspace-setup.sh`) exited early. Usually because:
- The `HELIX_REPOSITORIES` environment variable was empty (the project has no repository connected)
- The repository clone failed (authentication problem or network issue)

**Fix:**
1. Check that the project has at least one repository connected under the **Repositories** tab.
2. Check that the repository OAuth token is still valid (re-authorize under **Settings → Source Control** if needed).
3. Stop the session, fix the issue, and start a new session.

---

## Video stream shows black screen or constant reconnects

**Symptom:** The agent desktop stream is black or disconnects and reconnects every few seconds.

**Check:**
```bash
kubectl logs -f deploy/my-helix-sandbox | grep -i "desktop-bridge\|pipeline\|encoder"
```

If you see `failed to set pipeline to playing` after `Received CUDA context via set_context`, the DMA-BUF → CUDA import is failing (common on managed-GPU clusters like GKE T4).

**Fix:** Set the video mode to shared memory in `controlplane.extraEnv`:
```yaml
controlplane:
  extraEnv:
    - name: HELIX_VIDEO_MODE
      value: shm
```

Then `helm upgrade` and restart active sessions.

---

## Agent keeps re-implementing the same thing

**Symptom:** The agent makes the change, but on the next session it does the same thing again from scratch.

**Cause:** The agent's commits didn't get pushed to the repository, or the task is being started fresh each time.

**Check:**
1. Is there a working branch in your repository? Look for a branch with the spec task ID.
2. Did the agent push commits? Check the branch's commit history.

**Fix:** If the agent isn't pushing, check the source control OAuth token permissions. The token needs write access to the repository.

---

## Pull request shows no changes

**Symptom:** The PR was created but the diff is empty.

**Cause:** The agent committed to the wrong branch, or the base branch moved after the PR was opened.

**Fix:** Check the PR's base branch. If it's set to the agent's working branch instead of main, close the PR and manually create one with the correct base.

---

## "Connection refused" errors in the control plane logs

**Symptom:** Logs show `error sending request for url (http://localhost:8080/...)` from inside sandbox containers.

**Cause:** `global.serverUrl` is set to `http://localhost:8080`, which resolves to the sandbox container itself, not the control plane.

**Fix:** Set `global.serverUrl` to the cluster-internal service URL or the public ingress URL:
```yaml
global:
  serverUrl: http://my-helix-controlplane.helix.svc.cluster.local
```

This is the most common configuration mistake on Kubernetes deployments.

---

## Code intelligence search returns no results

**Symptom:** Semantic search and keyword search return nothing, even for identifiers that definitely exist.

**Check:** Is the repository indexed? Go to the **Code Intelligence** tab and check the index status. Look for "Indexing" or "Error" status.

**Fix:**
1. If indexing is stuck, go to **Settings → Code Intelligence** and trigger a manual re-index.
2. If indexing failed, check the control plane logs for errors from the `kodit` component.
3. For very large repositories (500k+ lines), initial indexing can take 30+ minutes — wait before concluding it's stuck.

---

## I need help

- **Helix Cloud**: Use the in-app chat support button
- **Self-hosted / Enterprise**: Email [support@helix.ml](mailto:support@helix.ml) with your Helix version (`docker compose exec api ./helix version`) and relevant logs
- **GitHub Issues**: [github.com/helixml/helix/issues](https://github.com/helixml/helix/issues)
- **Discord community**: [discord.gg/helixml](https://discord.gg/helixml)

---

**Agent** — A general term for any AI that uses tools to accomplish tasks. In Helix, "agent" is the broad category; "code agent" and "assistant" are the two specific types. When something is ambiguous between the two, say "code agent" or "assistant" explicitly.

**Assistant** — A Helix agent configured as a conversational tool: it responds to user messages, calls APIs, queries knowledge bases, and sends outputs to Slack, Discord, or webhooks. Assistants are defined in YAML and accessed via the Helix chat interface. Distinct from a code agent.

**Code agent** — The software that runs inside a sandbox and does software development: reads files, edits them, runs tests, commits code, and opens pull requests. Four engines are available: Claude Code, Goose, Qwen Code, and Zed Agent. Distinct from an assistant.

**Code intelligence** — Helix's structured understanding of your codebase, powered by Kodit. Provides semantic search, keyword search, an auto-generated wiki, and a changelog. Exposed to agents via MCP during implementation sessions.

**Hydra** — The multi-tenant isolation layer inside the Helix sandbox. Each concurrent agent session gets its own Docker daemon and network bridge via Hydra, so sessions can't see each other.

**Kodit** — The open-source code indexing library Helix uses for code intelligence. Builds a structured, searchable index of repositories, exposed to agents and humans via MCP.

**Project** — A Helix workspace linking a set of repositories to a set of spec tasks and a configured code agent. All work in Helix is scoped to a project.

**Recipe** — A reusable, parameterised task playbook used by the Goose code agent. Recipes are YAML files in your repository; Helix renders a parameter-capture form for each one on the spec task creation screen.

**Sandbox** — An isolated Linux desktop environment provisioned per spec task session. Contains Zed IDE, a terminal, a browser, and the code agent. Streamed to the user's browser as H.264 video.

**Spec branch** — The `helix-specs` branch that Helix creates in your primary repository. The agent pushes execution plans and implementation artifacts here. Never merged to main.

**Spec task** — A discrete unit of work in a Helix project. You describe the desired outcome; the agent plans and implements. Spec tasks are not the same as tickets — they represent active execution, not intent.

**Zed** — The IDE that runs inside agent sandboxes. Connects to the code agent via the Agent Client Protocol (ACP), surfacing tool calls, file edits, and approvals in a streaming thread.