Sandbox Commands

Lifecycle

heyvm create --name demo --image default   # create a sandbox (--name is required)
heyvm create --name demo --backend firecracker --image default
heyvm start <id>                        # start a stopped sandbox
heyvm stop <id>                         # stop it
heyvm restart <id>
heyvm get <id>                          # inspect one
heyvm rm <id>                           # delete (aliases: delete, destroy)

rm prompts for confirmation and refuses to prompt when stdin is not a TTY — always pass -y (--yes) from scripts and CI.

Backend support for the duplication commands varies, and is not uniform across platforms:

--project-snapshot is honored only by the bubblewrap backend; on any other backend it is accepted and ignored. See macOS Capabilities for the full macOS matrix.

Exposing ports

--open-port maps a guest port to a host port when the sandbox is created. The argument is HOST:GUEST, or a single value to use the same port on both sides:

heyvm create --name api --open-port 18734:5000   # host 18734 -> guest 5000
heyvm create --name api --open-port 8080         # host 8080  -> guest 8080

The mapping is fixed at creation time — it cannot be added to a running sandbox. To expose a port afterwards, use heyvm port-forward on a backend with SSH. Note that apple_virt ignores --open-port: its guests get a host-routable NAT IP and are reached directly. See Networking & Sharing.

Running code

heyvm exec <id> -- <command>     # run a command, capture output
heyvm sh <id>                    # interactive shell
heyvm run-host -- <command>      # run on the host
heyvm logs <id>                  # view logs

# Run an isolated code snippet (experimental, hyperlight-based — no sandbox id)
heyvm run --lang js --code 'console.log(1 + 1)'
heyvm run --lang python --file script.py

exec semantics

Everything after -- is the command. exec does not run a shell for you, so pipes, redirects, and compound commands need an explicit wrapper:

heyvm exec <id> -- ls -la
heyvm exec <id> -- sh -c 'ls -la | wc -l'        # pipes need sh -c
heyvm exec <id> --env KEY=value -- printenv KEY
heyvm exec <id> --cwd /srv --user root -- whoami

exec does not forward stdin. Piping into it (echo … | heyvm exec <id> -- bash -s) sends nothing to the guest. To run a local script remotely, pass it as an environment variable and decode it guest-side:

B64=$(base64 < script.sh)
heyvm exec <id> --env B64="$B64" -- sh -c 'echo "$B64" | base64 -d | bash'

Background processes survive the call that launched them, so a long-running service can be started with exec and left running:

heyvm exec <id> -- bash -c 'nohup my-server & disown'

Use heyvm sh <id> when you need a real interactive terminal.

Transferring VMs

heyvm transfer moves a VM to another machine over P2P: disks, config, and (where the backend supports it) the memory snapshot travel directly to the destination daemon, and the source sandbox is destroyed once the destination verifies the restore.

# Move a VM to one of your registered daemons (by name or id),
# or directly to a daemon's heyo:// connection ticket
heyvm transfer demo --to office-mac
heyvm transfer demo --to heyo://…

# Copy instead of move — the source keeps running
heyvm transfer demo --to office-mac --keep-source

# No cloud account? Serve the bundle and pull it from the other machine
heyvm transfer demo --serve          # prints a sync ticket
heyvm sync pull <ticket>             # run this on the destination

# Skip the memory snapshot — or insist on it
heyvm transfer demo --to office-mac --disk-only
heyvm transfer demo --to office-mac --require-memory

# Rename on arrival and leave it stopped
heyvm transfer demo --to office-mac --name demo-2 --no-start

Memory snapshots travel on the Firecracker backend; KVM and macOS (Apple Virtualization) transfers carry disk + config only. If the memory snapshot can't be restored on the destination, the transfer degrades to disk-only — pass --require-memory to make that a hard failure instead.