Getting Started

A step-by-step guide to installing heyvm, creating your first sandbox, running code, mounting project files, and deploying an app.

1. Install heyvm

curl -fsSL https://heyo.computer/heyvm/install.sh | sh

The script detects your OS and architecture and places the binary in /usr/local/bin (or ~/.local/bin if not writable). To upgrade later, run heyvm --upgrade.

2. Set up a backend

heyvm needs at least one sandbox backend. Pick the one that fits your platform:

BackendPlatformBest for
MicrosandboxLinux, macOSGeneral use, cloud deployment
BubblewrapLinuxLightweight namespace isolation
LibvirtLinuxFull VM isolation with KVM
Apple ContainermacOSNative macOS virtualization

For a quick local setup, Microsandbox is recommended. See the individual backend pages for installation instructions.

3. Create your first sandbox

heyvm create --name hello --type shell

This creates a shell sandbox using the default backend and image from your settings. You can also specify a backend and image explicitly:

heyvm create --name hello \
  --type shell \
  --backend-type bubblewrap \
  --image ubuntu:24.04

Available sandbox types: shell, python (alias: py), node (aliases: nodejs, js).

4. Run commands

Execute a one-off command in your sandbox:

heyvm exec hello -- echo "Hello from inside a sandbox!"

Or open an interactive shell:

heyvm sh hello

5. Mount project files

Mount a local directory into a sandbox so your code is available inside:

heyvm create --name my-app \
  --type node \
  --mount ./my-project:/workspace

You can also add mounts to an existing sandbox:

heyvm mount-add -i my-app --host-path ./my-project --sandbox-path /workspace

Then run your project:

heyvm exec my-app -- npm install
heyvm exec my-app -- npm start

6. Expose a port

If your app runs a server inside the sandbox, expose its port:

heyvm bind my-app 3000

This proxies the sandbox port to a public hostname (requires API_HOSTNAME to be set). For local development, you can also use P2P tunnels — see Local Tunnels & Proxies.

7. Work with git worktrees

Create a sandbox backed by a git worktree for a feature branch — great for isolated development and parallel agent work:

# Create + attach (VM shuts down when you exit the shell)
heyvm wt feat/my-feature -b

# Detached: VM keeps running after the CLI exits
heyvm wt feat/my-feature --detach

# Reattach later
heyvm wt feat/my-feature --shell

# Deploy the worktree to a cloud sandbox
heyvm wt feat/my-feature --deploy

See the full worktree sandboxes guide for detached workflows, custom images, and cloud deploys (including cross-arch --publish-image).

8. Share a sandbox

Share a running sandbox with a teammate over P2P:

# On your machine
heyvm share my-app --name pair-session

# On their machine
heyvm ssh pair-session

No VPN or port forwarding needed — it uses iroh-based P2P tunnels.

9. Deploy to the cloud

To deploy an app to Heyo's cloud infrastructure:

  1. Archive your sandbox mounts:

    heyvm archive my-app --name v1

    Or archive a local directory directly:

    heyvm archive-dir ./my-project --name v1

  2. Deploy using the Heyo cloud API (requires a paid account).

  3. Mount and update a deployed sandbox remotely:

    heyvm mount <deployed-id>
heyvm update <deployed-id> --archive <archive-id>

For full deployment details, see Deployment.

10. Manage sandboxes

List, stop, restart, and clean up:

# List running sandboxes
heyvm list

# List stopped sandboxes
heyvm list-inactive

# Stop a sandbox
heyvm stop my-app

# Restart a sandbox
heyvm restart my-app

# Start a stopped sandbox
heyvm start my-app

Next steps