Architecture for operators

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

SearXNG and Chrome serve the web search API and the agents' web search and browser skills. See Configure web search.

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