CLI reference

The heyvm binary launches the TUI when no subcommand is given and --api is not passed. With a subcommand, it runs that command and exits (pure CLI). With --api, it runs only the API server.

Global options

• --api — Run only the HTTP API server (no TUI). Default port 3000; use --port to override.
• --port <PORT> — API server port when using --api (default: 3000). When running with TUI, API and TUI use port 34099.
• --msb-host <HOST> — Microsandbox server host (default: localhost).
• --dev — Development mode: TUI/CLI uses localhost for auth (default: https://auth.heyo.computer).
• --cloud-url <URL> — Cloud server URL.
• --auth-url <URL> — Auth server URL.
• --debug — Enable verbose logging.
• --upgrade — Self-upgrade to the latest version.

Sandbox types

Used with --type on create and other commands:

• shell
• python (alias: py)
• node (aliases: nodejs, javascript, js)

Backend types

Used with --backend-type:

• msb — Microsandbox
• wasix — WASIX
• wasip2 (aliases: wasi-p2, wasi_p2) — WASI Preview 2
• apple_container (aliases: apple-container, apple_vf, apple-vf) — Apple Container (macOS only)
• apple_virt (alias: apple-virt) — Apple Virtualization native VM (macOS only)
• bubblewrap — Bubblewrap namespace isolation (Linux only)
• sandbox_exec (alias: sandbox-exec) — macOS sandbox (macOS only)
• libvirt — Libvirt/KVM (Linux only)
• docker — Docker container
• firecracker — Firecracker microVMs (Linux only)

Subcommands

These run without starting the HTTP server. Sandbox identifiers can be id or slug where applicable.

create

Create a sandbox.

heyvm create --name my-sandbox \
  [--image microsandbox/python] \
  [--slug my-slug] \
  [--type shell|python|node] \
  [--mount HOST_PATH:SANDBOX_PATH ...] \
  [--ttl-seconds 3600] \
  [--start-command CMD] \
  [--backend-type msb|apple_container|apple_virt|bubblewrap|libvirt|firecracker|...] \
  [--env KEY=VALUE ...] \
  [--setup-hook CMD ...]

list

List running sandboxes.

heyvm list

list-inactive

List inactive (stopped) sandboxes.

heyvm list-inactive [--count 10] [--cursor ID] [--slug FILTER]

stop / restart / start

Stop, restart, or start a sandbox.

heyvm stop <id-or-slug>
heyvm restart <id-or-slug>
heyvm start <id-or-slug>

exec

Execute a command in a sandbox.

heyvm exec <id-or-slug> -- COMMAND [ARGS...]
# Example:
heyvm exec my-slug -- python -c "print(1)"

sh

Start an interactive shell in a sandbox.

heyvm sh <id-or-slug>

mount-add

Add a mount to a sandbox.

heyvm mount-add --id <id-or-slug> --host-path /path/on/host --sandbox-path /path/in/sandbox [--read-only]

bind

Bind a sandbox port to a public hostname. Requires the API_HOSTNAME environment variable to be set.

export API_HOSTNAME=example.com
heyvm bind <id-or-slug> <PORT>

run-host

Run a host CLI command in the directory backing a sandbox mount. Useful for running tools that aren't installed in the sandbox but need to operate on the sandbox's files.

heyvm run-host <id-or-slug> -- COMMAND [ARGS...]
# Example:
heyvm run-host my-sandbox -- npm install

wt

Create a git worktree sandbox and launch a shell in it. Pairs a branch with a sandbox whose /workspace is the worktree directory. See the worktree sandboxes guide for the full workflow including detach, reattach, and cloud deploy.

# Create + attach (VM dies when the shell exits)
heyvm wt feat/cool-feature -b

# Create + background (VM persists; attach later with --shell)
heyvm wt feat/cool-feature --detach

# Attach to an existing wt sandbox
heyvm wt feat/cool-feature --shell

# List wt-* sandboxes only
heyvm wt --list

# Deploy the worktree to a cloud sandbox
heyvm wt feat/cool-feature --deploy
heyvm wt feat/cool-feature --deploy --publish-image --deploy-dockerfile ./Dockerfile

pull

Pull a Docker image for use with the apple_container backend.

heyvm pull <IMAGE> [--force]
# Example:
heyvm pull ubuntu:24.04
heyvm pull python:3.11-slim --force

images-list

List pulled Docker images.

heyvm images-list

images build

Build a custom sandbox rootfs image from a Dockerfile. Today supports --backend-type apple_virt; for firecracker see heyvm mvm build or heyvm wt --deploy --publish-image.

heyvm images build --backend-type apple_virt \
  --file ./Dockerfile \
  --name my-image \
  [--context DIR] \
  [--size-mb 4096]

Requires Docker Desktop. After build: heyvm wt <branch> --image <name> or heyvm create --backend apple_virt --image <name>.

logs

Tail a sandbox's owner log. Today only apple_virt sandboxes started with --detach have one (the owner process writes ~/.heyo/sandboxes/<id>/owner.log).

heyvm logs <id-or-slug> [-n LINES] [-f]
# Example:
heyvm logs sb-abc12345 -f

archive

Archive sandbox mounts to the Heyo server (persists to S3).

heyvm archive <id-or-slug> [--token <TOKEN>] [--name <NAME>]

normalize-wasix-images

Normalize persisted WASIX sandbox image values.

heyvm normalize-wasix-images [--dry-run] [--to <IMAGE>]

archive-dir

Create an archive from a local directory (without needing an existing sandbox).

heyvm archive-dir [PATH] [--name <NAME>] [--mount-path <PATH>] [--no-ignore]
# Example:
heyvm archive-dir ./my-project --name v1

mount

Mount a deployed sandbox workspace locally via SSHFS.

heyvm mount <id-or-slug> [--mount-path <PATH>] [--local-path <PATH>] [-- COMMAND ARGS...]
# Example:
heyvm mount my-deployed-app
heyvm mount my-deployed-app -- code .

update

Replace a deployed sandbox's mount contents from an archive.

heyvm update <id-or-slug> --archive <ARCHIVE_ID> [--mount-path <PATH>]
# Example:
heyvm update my-deployed-app --archive abc123

resize

Resize a deployed sandbox to a different size class.

heyvm resize <id-or-slug> --size-class <CLASS>

Size classes:

proxy / connect / share / ssh

Expose local ports over P2P, connect to remote services, and share sandbox shells. See Local Tunnels & Proxies.

test-proxy

End-to-end proxy test: creates a VM, starts an HTTP server, binds a port, and verifies connectivity. Linux only (requires libvirt backend).

heyvm test-proxy [--keep]

Pass --keep to leave the sandbox running after the test.

install-skills

Download and install Claude Code skills into the current project. Skills provide Claude Code with knowledge of heyvm commands and deployment workflows.

heyvm install-skills [--path <PATH>] [--base-url <URL>]

After installation, Claude Code automatically detects the skills in .claude/skills/.

install-codex-plugin

Download and install the heyvm Codex plugin. The plugin bundles heyvm MCP server wiring plus Codex skills such as $heyvm-use and $heyvm-workspace.

heyvm install-codex-plugin [--path <PATH>] [--base-url <URL>]

After installation, restart Codex. Codex does not currently expose a non-interactive plugin install subcommand, so the installer writes the plugin cache and enables heyvm@heyvm in ~/.codex/config.toml directly. The bundled heyvm --mcp server and skills load automatically on the next Codex startup.

Environment variables

Examples

Create a shell sandbox and run a command:

heyvm create --name my-sandbox --type shell
heyvm exec my-sandbox -- echo hello

Create a Python sandbox with a mount:

heyvm create --name py-app --type python --mount ./src:/app/src
heyvm exec py-app -- python -c "print('ok')"

Start an interactive shell:

heyvm sh my-sandbox

Create a worktree sandbox for a feature branch:

heyvm wt feat/new-feature -b

For proxy/connect usage, see Local Tunnels & Proxies.