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.

Running setup commands at sandbox start

If your project needs dependencies installed or a dev server running before an agent can do useful work, give it a startup script. Edit it under project Settings → Sandbox → Startup script.

The script is a file in git, not a database field. It lives at .helix/startup.sh on the helix-specs branch of your primary repository — the same branch agents push their plans to, never your code branch. Saving in the settings panel commits it there, so the script is versioned and reviewable, and you can equally edit it by pushing to helix-specs yourself; the panel picks up whatever is on the branch.

Putting .helix/startup.sh on main instead has no effect — Helix does not look there.

Helix runs the script each time a sandbox starts, in parallel with the IDE coming up, with the working directory set to your primary repository's checkout:

#!/usr/bin/env bash
set -e
npm install
npm run dev &

A failing startup script does not stop the sandbox. The desktop still comes up and the error is left in the terminal, so you can debug it there and fix the script — rather than losing the whole environment to a bad npm install.

If the helix-specs branch has no script, Helix falls back to a startup script defined in the project YAML. When that fallback is in use the settings panel shows the script read-only, because the YAML is the source of truth.

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 the agent crashes, Helix automatically restarts the sandbox and resumes the task — up to 3 consecutive times with backoff. No action is needed for crash recovery. If a session ends for another reason (network drop, manual cancellation), 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.