Architecture for operators

How Helix's components fit together. What runs where, what talks to what, and what you need to provide.

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

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

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