Imported from Heyo-Computer/skills (heyvm-sandbox/SKILL.md). Install upstream with npx skills add Heyo-Computer/skills --skill heyvm-sandbox. Copyright stays with the author.

heyvm CLI — Sandbox Manager

See also: load the heyvm-docs skill for an overview of the heyvm platform and an index of the other heyvm-* skills (deploy, proxy, api, firecracker, login, system).

You are interacting with the heyvm CLI, the sandbox management tool for the Heyo platform. Use it to create and manage isolated sandbox environments backed by multiple runtimes.

Binary Location

The binary is heyvm. If it is not on PATH, build it from mvm-ctrl/:

cargo build --release -p heyvm

Global Options

Available Subcommands

Sandbox Lifecycle

Execution

Compound Commands

When running compound commands with heyvm exec, wrap them in sh -c with a quoted string:

# Compound commands via sh -c
heyvm exec my-sandbox -- sh -c 'echo hello && echo world'

# Pipes
heyvm exec my-sandbox -- sh -c 'cat /etc/os-release | head -5'

# Redirects
heyvm exec my-sandbox -- sh -c 'echo data > /tmp/file.txt'

# Simple commands work directly
heyvm exec my-sandbox -- python -c "print('hello')"

The -- separator is required before the command to prevent flag parsing.

Listing

Mounts & Storage

Networking & Sharing

Important: heyvm bind only works for local sandboxes. For deployed (cloud) sandboxes, expose ports at deploy time with heyvm deploy ... --port <p> (or via the cloud API) — see the heyvm-deploy skill.

Deployed Sandbox Management

These commands work for both local and cloud-deployed sandboxes. The CLI resolves deployed sandboxes by name, slug, or ID via the cloud API.

Note: Cloud deployment is a 3-command flow: heyvm create --cloud ... --backend libvirt --image ubuntu:24.04 --start-command '...' --port P boots an empty cloud sandbox, then heyvm archive-dir <dir> + heyvm update <name> --archive <id> push your code in. Works on macOS and Linux. For details (and the Linux-only --deploy-from advanced form), load the heyvm-deploy skill.

Git & Development

Skills & Setup

Maintenance

Create Options

--name <NAME>              Sandbox name (required)
--image <IMAGE>            Container image (default from settings)
--slug <SLUG>              URL-safe slug (default: slugified name)
--type <TYPE>              shell | python | node
--mount <HOST:SANDBOX>     Mount path (repeatable)
--ttl-seconds <SECS>       Time-to-live
--start-command <CMD>      Custom start command
--backend <TYPE>           msb | wasix | wasip2 | docker | apple_container | apple_virt | sandbox_exec | bubblewrap | libvirt | firecracker
                           (alias: --backend-type. See backend constraints below.)
--env <KEY=VALUE>          Environment variable (repeatable)
--setup-hook <CMD>         Shell command to run after creation or mount replacement (repeatable)

Connect Options

<TICKET_URL>               heyo:// connection URL or shortname
-p, --port <PORT>          Local port to listen on (default: random)
-r, --relay <URL>          Relay server URL for short ticket lookup
--save <NAME>              Save connection under a shortname
--shell                    Open interactive SSH shell after connecting
--run-host                 Mount remote workspace via SSHFS and run a host command
--mount-path <PATH>        Sandbox path to mount (default: /workspace, used with --run-host)

Archive-dir Options

[PATH]                     Local directory to archive (default: current directory)
--name <NAME>              Optional archive name
--mount-path <PATH>        Mount path prefix in the archive (default: /workspace)
--token <TOKEN>            JWT token (or set HEYO_ARCHIVE_TOKEN env var)
--no-ignore                Include build assets (node_modules, target, dist, etc.)

Mount Options

<ID>                       Deployed sandbox ID, slug, or name
--mount-path <PATH>        Remote path to mount (default: /workspace)
--local-path <PATH>        Local directory to mount into (default: auto-generated)
[COMMAND]                  Host command to run after mounting (use -- before command)

Update Options

<ID>                       Deployed sandbox ID, slug, or name
--archive <ARCHIVE_ID>     Archive ID to replace the mount with (required)
--mount-path <PATH>        Mount path to replace (default: /workspace)

Bind-Mount Semantics (bubblewrap)

heyvm create --mount HOST:SANDBOX (and the implicit workspace mount) under the bubblewrap backend uses a kernel bind mount inside the sandbox's mount namespace. The host directory is the source of truth; the sandbox sees the same files via the same inodes.

What you can rely on:

• Atomic rename across the boundary. Renames inside the sandbox land atomically on the host because both ends share an inode under one filesystem. Editors that write .tmp + rename work normally; git index/lockfile churn is safe.
• Inode preservation. A file's inode number stays stable for tools that stat-match across writes (some agents, make, content-addressed caches).
• Live round-trip. Reads on the host see writes from the sandbox without any sync step, and vice versa.

Caveats:

• Delete mid-run. If the sandbox is deleted (heyvm rm) while a process inside has open writes, those writes flush to the host normally — the host directory is not touched by sandbox teardown, only the sandbox's mount namespace is. Long-tail in-flight writes (e.g. fsync still pending in the kernel) follow normal Linux semantics: open fds remain valid until the killed process exits, and buffered data is flushed.
• Project snapshot mode is different. --project-snapshot DIR switches the workspace to overlayfs (lower=DIR, upper=per-sandbox). In that mode changes do not round-trip live to the host — they live in the upper layer until you copy them out.

Backend Types

CRITICAL — local vs cloud backends. All of the backends below are LOCAL ONLY except libvirt, firecracker, and kvm, which are the only backends the Heyo cloud (heyvm create --cloud / --deploy-from, regions US / EU) can run. apple_virt, apple_container, sandbox_exec, bubblewrap, docker, msb, wasix, wasip2 are host-only — passing them to heyvm create --cloud --backend X will fail with a clear error. See heyvm-deploy for the cloud side.

• msb (local only) — Microsandbox (default)
• wasix (local only) — WASIX WebAssembly
• wasip2 (local only) — WASI Preview 2
• docker (local only) — Docker container
• apple_container (local only, macOS) — Apple Container, uses Apple's container CLI
• apple_virt (local only, macOS arm64) — Apple Virtualization native VM, uses Virtualization.framework directly
• sandbox_exec (local only, macOS) — macOS sandbox-exec
• bubblewrap (local only, Linux) — Linux namespaces
• libvirt (local + cloud, Linux) — QEMU/KVM via libvirt
• firecracker (local + cloud, Linux) — Firecracker microVMs
• kvm (local + cloud, Linux) — Direct KVM via kvmbind

Common pitfalls — wrong-platform backend

heyvm create --backend X will reject X if X isn't available on the current host, with a message that names the available backends and a copy-pasteable command. The following invocations are intentionally invalid and the CLI is expected to reject them:

heyvm create --backend nonexistent_backend --name testbad

This catches the most common confusion: agents that pick a Linux-only backend (firecracker / bubblewrap / libvirt / kvm) on a macOS dev host, or a macOS-only backend (apple_virt / apple_container / sandbox_exec) on a Linux host. The error tells the agent what to use instead.

Workflow

When the user asks to interact with sandboxes:

1. First, check what's running: heyvm list to see active sandboxes.
2. Create if needed: Use heyvm create with appropriate --type and --backend-type.
3. Execute commands: Use heyvm exec <id-or-slug> -- <command> for non-interactive work.
4. Use slug or ID: All commands that take <id> also accept the sandbox slug.

When the user provides $ARGUMENTS, interpret them as a subcommand and arguments to pass directly to heyvm. For example, /heyvm list should run heyvm list.

If $ARGUMENTS is empty, ask the user what they want to do with their sandboxes.