Getting Started with the CLI on MacOS
Download, Install, and Update
curl -fsSL https://heyo.computer/heyvm/install.sh | sh
# version:
heyvm --version
> heyvm v0.34.2
> Update available: v0.34.2 -> v0.35.1
> Run `heyvm --upgrade` to update.
# upgrade:
heyvm --upgrade
> Current version: 0.34.2
> Latest version: 0.35.1
> Downloading https://heyo-cli-releases.s3.amazonaws.com/heyvm/v0.35.1/heyvm-0.35.1-apple-darwin-aarch64.tar.gz ...
> Upgraded heyvm 0.34.2 -> 0.35.1
> Location: /Users/samcurrie/.cargo/bin/heyvm
Fetching public images
On MacOS, the default backend is apple_virt which uses the native Apple Virtualization framework. Apple Containers are supported as well for OCI compatibility, this needs installed separately.
heyvm images list
> ID NAME BACKEND FORMAT SIZE DESCRIPTION
> ------------------------------------------------------------------------------------------
> im-762fc9af agents-v1 kvm ext4 3.5 GB KVM rootfs with preinstalled coding agents
> ...
# download via the ID:
heyvm images add im-50cd7f6b
> Downloading image im-50cd7f6b (backend: apple_virt, format: tar.gz)...
> Image saved: /Users/samcurrie/.heyo/images/apple_virt/ubuntu-24.04 (1159.1 MB)
> Use with: heyvm create --backend apple_virt --image ubuntu-24.04
Creating a VM locally
The CLI ships with several test commands to check system readiness for different backends including apple_virt on MacOS.
heyvm test-apple-virt
> [1/6] Checking Apple Virtualization image (auto-download if missing)...
> [2/6] Creating apple_virt sandbox: avf-test-1781980936
> Sandbox created in 5042ms: sb-a3efcd2a
> [3/6] Verifying guest IP capture...
> Guest IP: 192.168.64.76
> [4/6] Verifying SSH reachability + auth...
> SSH exec: PASS in 78ms
> | ssh-ok
> | Linux aarch64
> | root
> [5/6] Verifying manager.execute() routes via SSH...
> manager.execute: PASS
> [6/6] Stopping sandbox...
> Sandbox stopped and cleaned up
>
> PASS - apple_virt + SSH end-to-end
Creating a new VM locally:
# use the ubuntu image we just downloaded:
heyvm create --backend apple_virt --image ubuntu-24.04
Running commands and accessing Shells
Running commands can be done in a couple of ways, a docker style exec or by accessing a shell session directly via ssh.
# list running VMs
heyvm list
# run a command in a VM
heyvm exec apple-test pwd
> /home/user
# get a long lived shell session:
heyvm sh apple-test
> #>
Share with Other Machines
The CLI ships with P2P networking features so that you can securely share and access VMs remotely.
Start by creating a ticket for the shell session:
heyvm share verify-ubuntu --pair-programming
> Sharing sandbox 'apple-test' SSH over iroh
> On the client run:
> heyvm ssh heyo://..,.
# on the remote machine:
heyvm ssh pair-programming
The desktop app automates the networking setup and management. The Rust, TypeScript and Swift SDKs additionally have interfaces for programmatically managing VMs over a virtual network.
Deploy to the Cloud
We can deploy a copy of the sandbox to the cloud by cloning the root filesystem and creating a new VM from it. In this example we also open up a port on the sandbox which will automatically create a public URL that binds to that port.
# list running sandboxes:
heyvm list
> NAME ID STATUS BACKEND TYPE / IMAGE
> ------------- ----------- ------- ---------- --------------------
> verify-ubuntu sb-a2bb96a6 Running apple_virt Shell / ubuntu-24.04
# deploy a copy using the ID:
heyvm create --deploy-from sb-a2bb96a6 \
--name ubuntu \
--backend libvirt \
--region US \
--port 8080 \
# optionally give it a start command like --start-command "cd /workspace && npm start"
Next Steps: Desktop App & Daemon
Installing the desktop app also installs the daemon, heyvmd; the daemon manages lifecycles for VMs exposed over a virtual network so that they are restarted when accessed and that the P2P connection is maintained.
Log into https://app.heyo.computer to download the desktop app for Apple Silicon or x86 Linux machines.