Helix Architecture
Helix is a full-stack AI engineering platform. It couples a Next.js control plane, an agent server, and Daytona sandboxes into a single loop where a user can describe a task in natural language and Helix can carry it out.
Components
Control plane (Next.js)
The Next.js app provides the UI, API routes, auth, billing, team management, and long-running conversation storage in Supabase.
Key responsibilities:
- Render the chat panel, workspace, and plan approval UI.
- Authenticate users and enforce team-level quotas.
- Expose REST endpoints for runs, messages, plans, and settings.
- Stream events from the agent server to the browser.
Agent server
The agent server is a long-running Node.js/WebSocket service that owns the reasoning loop. It receives a conversation and a goal, then drives the LLM, tools, and planner until the task is complete.
Key modules:
agent.ts— the main reasoning loop.controller.ts— decides which tool to call next and how to advance the task list.goal-controller.ts— tracks the high-level goal and completion criteria.critic.ts— reviews risky actions before they run.executor.ts— dispatches tool calls to the sandbox or external services.
Sandbox runtime (Daytona)
Every conversation gets one or more isolated Daytona workspaces. The workspace is a Linux container with a persistent /workspace/repo directory. Helix runs shell commands, reads files, writes files, and executes code inside the sandbox.
The runtime enforces its own filesystem and network boundary. Helix's policy layer does not duplicate that boundary with hardcoded path guards; instead it relies on Daytona for isolation and uses guardrails only for high-level policy (roles, secrets, destructive actions).
LLM layer
Helix routes LLM calls through LLM.acompletion() / aresponses() with a RetryMixin for transient failures. Supported providers include Groq, OpenAI, Anthropic, and others via LiteLLM. The manifest of available tools is cached so cold starts are minimized.
Event stream
All run events flow through a server-sent event (SSE) stream from the agent server to the Next.js API, then to the client. Events include:
MessageEvent— assistant messages and user messages.ToolEvent— a tool was invoked.ObservationEvent— the result of a tool.InterruptEvent— the run was paused by the user or by a safety gate.FinishEvent— the run completed successfully.
Data flow
- User sends a message in the Helix chat panel.
- Next.js creates or resumes a conversation and starts a run.
- Agent server receives the run and calls the planner.
- Agent server selects tools, sends them to the sandbox, and records observations.
- Agent server streams events back to the Next.js API.
- Client renders messages, tool activity, and workspace updates in real time.
Scaling and quotas
Each team has a plan_tier with limits for concurrent sandboxes, context tokens, and allowed models. Usage is tracked per run and reconciled with the billing tables.