HelixML

Work in a sandbox

How to interact with an agent's desktop environment. View the live stream, type commands, browse files, and use the terminal.

Every spec task runs inside a sandbox — an isolated Linux desktop with Zed IDE, a terminal, and a browser. You watch the agent work via a live video stream in your browser, and can interact directly at any point.

Viewing the agent's desktop

In the task view, the video stream shows the agent's desktop in real time. The agent works autonomously, but you can watch its progress: file edits appear in the IDE, terminal commands run in the shell, browser navigation is visible.

Click the Maximize button to expand the stream to fill your browser window.

Interacting with the agent

Click anywhere in the stream to focus it, then type. The agent sees your input as a message in its thread. Use this to:

  • Redirect the agent mid-implementation ("actually, use the useState hook, not useReducer")
  • Answer a question the agent asked
  • Point the agent at a specific file or test that's failing

The agent reads your input and responds in the thread. It continues working in the same sandbox — no restart needed.

Multiple sandboxes: split-screen mode

Click the split-screen icon in the project view to see multiple agent desktops side by side. Each panel is a separate task running independently.

You can:

  • Maximize or minimize individual panels
  • Add panels for running tasks
  • Remove panels without stopping the underlying task

Split-screen is useful for reviewing multiple tasks in parallel or comparing two implementation approaches side by side.

What's inside each sandbox

Each sandbox gets:

  • Zed IDE — the editor the agent uses for reading and editing files
  • Terminal — bash, full standard tooling (git, docker, curl, etc.)
  • Firefox browser — for testing web apps, reading docs, accessing APIs
  • Agent thread — the conversation between the Helix control plane and the agent

The sandbox starts with your repository pre-cloned, based on whatever repos are attached to the project.

Accessing files from the agent's workspace

While a task is running, you can read files from the agent's working directory via the task view's Files tab. This is useful for checking intermediate output — a generated file, a log, a draft — without waiting for the agent to commit.

Sandbox lifetime

A sandbox lives for the duration of a spec task session. When the session ends:

  • The sandbox container is destroyed
  • Files are not persisted except what the agent committed to git
  • The agent's git commits are on the working branch — nothing is lost if the sandbox disappears

If a session ends unexpectedly (network drop, crash), you can resume from the task view — Helix will start a new sandbox and clone the repository again from where the agent left off.

Sandboxes and security

Each task runs in its own isolated container with:

  • A separate filesystem (no access to the host or other tasks)
  • An isolated network (separate subnet per session, no cross-session traffic)
  • Its own Docker daemon (via the Hydra isolation layer)

See Sandboxes — how they work for the full architecture.