Skip to main content

HelixVM: Local VM Sandbox

What really holds AI Agents back isn't just model capability — it's the conflict between permissions and safety: grant too little and the Agent stops to ask you at every step; grant too much and it might delete your files or break your environment.

HelixVM offers a third path: run the Agent inside a lightweight local virtual machine. Isolation happens underneath, but the complexity never reaches you.

No cloud servers. No VMware. No virtualization course required. Pick an image, click create, and let the Agent work.

Why a Sandbox​

Traditional Agent permission models swing between two bad options:

ModelExperienceProblem
Frequent approvalConfirm every risky actionUsers go numb, approval becomes a formality, efficiency collapses
Full accessAgent runs fully automated on the hostCould delete real files, corrupt the system, pollute global dependencies

HelixVM offers a third option:

Security comes from an isolated runtime, not from frequent approvals.

Inside the VM, the Agent can execute continuously at full speed. Even if it makes mistakes, the damage is contained in the virtual environment — never touching your real system.

Three-Layer Architecture​

From the user's perspective, HelixVM is simple: choose a VM workspace → pick an image → create → enter a ready-to-use Agent workspace. Underneath, three layers cooperate:

┌────────────────────────────────────────────────┐
│  Helix (UI layer)                               │
│  VM entry · image selection · create · ports ·  │
│  status                                         │
├────────────────────────────────────────────────┤
│  HelixVM (VM control plane)                     │
│  VM registry · image downloads · launch plan ·  │
│  start/stop · health checks · residue cleanup   │
├────────────────────────────────────────────────┤
│  Helix Agent (guest execution layer)            │
│  workspace read/write · shell · builds/tests ·  │
│  Agent API                                     │
└────────────────────────────────────────────────┘
  • Helix — the product entry you actually see; owns the end-to-end VM workspace experience
  • HelixVM — wraps complex virtualization (QEMU and friends): VM registry, templates and images, control/SSH/service port allocation, launch plan generation, VM lifecycle, guest readiness checks, residue cleanup
  • Helix Agent — runs inside the guest and does the real work: workspace access, shell, builds and tests, session management, Agent API

What you open is not an abstract VM — it's a ready-to-use Agent workspace.

Key Capabilities​

Template & Image Marketplace​

HelixVM doesn't hand you a blank VM; it hands you a usable development environment. The built-in template/marketplace covers common scenarios:

  • Lightweight Linux + Helix Agent
  • Common dev toolchain environments
  • Browser-capable automation environments
  • Language- or project-specific development images

Picking an image is picking an environment — turning "secure isolation" from an ops chore into a product choice.

Seamless Pairing​

The traditional pairing dance (find a pairing code → type it into the client → bind) is completely hidden in HelixVM:

  1. When creating the VM, Helix generates a one-time bootstrap secret and injects it into the guest boot parameters
  2. The Helix Agent inside the guest reads the secret and uses it as the first-time binding credential
  3. Helix calls the pairing API, verifies the secret, and issues a long-term credential on success

All the user sees: the VM was created, and the Agent workspace connected itself.

Two-Level Readiness​

"VM running" doesn't mean the Agent inside is usable. HelixVM waits for two levels of readiness:

  1. HelixVM reports the guest control plane is ready
  2. The Helix Agent's health check inside the guest passes

You enter a workspace where the Agent can genuinely start working.

Port Forwarding​

The Agent runs inside the VM while Helix runs on the host; they communicate over port forwarding. HelixVM automatically allocates control, SSH, and service ports, so services inside the VM are reachable like local services — and when you need to expose them externally, pair with the self-hosted tunnel.

Cross-Platform Support​

  • macOS — native QEMU support (Apple Silicon & Intel)
  • Windows — WHPX hardware-acceleration setup wizard, no extra virtualization software
  • Linux — standard QEMU/KVM path

Workflow​

New VM workspace → pick an image → create (auto-download image, boot VM)
→ wait for two-level readiness → enter Agent workspace → chat and execute

The creation flow looks simple, but underneath it's far more than "launching a VM process" — image management, port allocation, pairing, and readiness checks are all automated.

Typical Scenarios​

  • Dangerous-operation isolation — let the Agent freely install dependencies, modify system config, or batch-delete; the host stays safe
  • Environment consistency — one clean environment per task, no pollution of your dev machine
  • Browser automation — run web scraping and automation in a browser-capable image without touching your real browser
  • Team template sharing — package the standard dev environment as an image; new teammates get a consistent environment in one click

Synergies with Other Capabilities​

With Workspaces​

VMs are one class of Workspace target — local directories, remote hosts, and VM workspaces are managed uniformly; switching Workspace switches the execution environment.

With Self-Hosting / Remote Access​

HelixVM solves "local isolation"; self-hosted tunnels/VPN solve "remote access." Services inside the VM are exposed via port forwarding, then traverse NAT through the tunnel — reaching sandboxed services from anywhere.

With Context Management​

Sessions inside VMs enjoy the same Cache/Compact context management — isolation doesn't sacrifice long-task capability.