Sandbox runtimes
Desktop environment options, container images, and resource requirements for Helix agent sandboxes.
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.
Per-task sandbox size
An individual spec task can run in a larger or smaller sandbox than the default. Three sizes are accepted, and only these three:
| Size | vCPU | RAM |
|---|---|---|
| 1 CPU | 1 | 2 GB |
| 4 CPU | 4 | 8 GB |
| 8 CPU | 8 | 16 GB |
4 CPU / 8 GB is the default. Set it per task from the task's execution controls — see Change how one task runs.
Video streaming
The agent desktop is streamed as H.264 video over WebSocket (HTTPS). The streaming pipeline:
- Desktop renders to Wayland compositor
- PipeWire captures the frame
- GStreamer encodes to H.264 (hardware or software)
- WebSocket delivers the stream to your browser
Encode modes (set via HELIX_VIDEO_MODE):
zerocopy— DMA-BUF → CUDA → NVENC. Fastest; requires NVIDIA GPUnative— DMA-BUF via GStreamer 1.24+. Works on Intel/AMDshm— 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 |
| Idle timeout | Session ends if nobody interacts with it for the configured timeout (default: 1 hour, HELIX_DESKTOP_IDLE_TIMEOUT), checked every 5 minutes |
| Keep Alive is on | The session is exempt from the idle timeout, and is left running when its task reaches Done. Its workspace is also never garbage-collected, with no time limit. |
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.