HelixML

Sandboxes and the desktop environment

What a Helix sandbox is, how isolation works, and what runs inside the containerized Linux desktop that agents use.

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: