The heyvm binary embeds an HTTP API server (mvm-ctrl/src/api.rs). Start it with:
heyvm --api --port 3000
Under the TUI or daemon the same API is served on port 34099.
Public routes
| Method | Path | Purpose |
|---|---|---|
GET |
/health |
Liveness check |
GET |
/capabilities |
What this host/backends support |
GET |
/l/:micro_id/:slug |
Public short links |
When an auth upstream is configured, auth routes proxy to the auth server:
/api/auth, /api/auth/*path, /api/api-keys, /api/users/features.
Sandboxes
Sandbox routes require a bearer token when a JWT_SECRET or internal API key is
configured; an unconfigured local instance accepts requests without one.
| Method | Path | Purpose |
|---|---|---|
GET / POST |
/sandboxes |
List / create sandboxes |
GET |
/sandboxes/inactive |
List inactive sandboxes |
POST |
/sandboxes/from-archive |
Create from an archive |
GET / PATCH / DELETE |
/sandboxes/:id |
Get / update / delete a sandbox |
POST |
/sandboxes/:id/start …/stop …/restart …/kill …/force-stop |
Lifecycle |
POST |
/sandboxes/:id/resize |
Resize resources |
POST |
/sandboxes/:id/execute |
Run a command |
POST |
/sandboxes/:id/exec-operations |
Start an async exec (+ GET …/exec-operations/:operation_id to poll) |
POST |
/sandboxes/:id/webhook-exec |
Run via webhook |
POST |
/sandboxes/:id/checkpoint …/restore …/snapshot-image |
Checkpoint / restore / snapshot |
* |
/sandboxes/:id/shell-session …/display-session …/shell-stream |
Interactive shell / display sessions |
POST |
/sandboxes/:id/tcp-tunnel |
Open a TCP tunnel |
POST |
/sandboxes/:id/expose …/unexpose |
Publish / unpublish ports |
POST |
/sandboxes/:id/links |
Create a shareable link |
GET |
/sandboxes/:id/internal-url |
Internal connection info |
* |
/sandboxes/:id/proxy |
Proxy into the sandbox |
POST |
/sandboxes/:id/backup |
Back up |
GET |
/sandboxes/:id/logs |
Logs |
* |
/sandboxes/:id/mounts …/replace-mount |
Mounts (DELETE …/mounts/*path to remove one) |
POST |
/sandboxes/:id/export-rootfs-tar |
Export rootfs |
GET / POST |
/sandboxes/:id/files (+ …/files/*path, …/files/upload) |
Browse, download, upload, delete files |
GET |
/sandboxes/:id/macos-status …/macos-bootstrap |
macOS guest status / bootstrap |
VM transfer
Destination side of heyvm transfer: the sending CLI calls the destination
daemon's API to start the pull, then polls for progress.
| Method | Path | Purpose |
|---|---|---|
POST |
/sync/receive |
Accept an inbound VM transfer; pulls and restores the bundle in the background |
GET |
/sync/receives/:id |
Poll an inbound transfer's status and progress |
Images, routes, SQLite
| Method | Path | Purpose |
|---|---|---|
POST |
/images/prewarm (+ status) |
Prewarm an image |
POST |
/service-routes |
Service route management |
GET |
/host/heyvm/status |
Host daemon status |
GET / POST |
/sqlite |
List / create embedded SQLite databases |
* |
/sqlite/:id (+ exec, snapshot, restore) |
Embedded SQLite databases |
Cloud-compatibility shims
For drop-in compatibility with the cloud API, the local server also serves
/sandbox-deploy, /deployed-sandboxes (+ GET/DELETE …/:id, …/:id/ttl,
…/:id/shell-stream), and /sandbox/:id/{exec,stop,start,read-file,write-file}.