Bare metal

Run heyvm as an HTTP API on a physical server or VPS without containers. The API runs as a persistent system service and can be placed behind a reverse proxy for HTTPS.

Prerequisites

At least one sandbox backend configured: Microsandbox, Bubblewrap, or Apple Container
Linux (recommended for production) or macOS
For MSB backend: Microsandbox server running and API key set

Install heyvm

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

The script installs to /usr/local/bin when writable, otherwise ~/.local/bin. See the Quickstart for more options.

Environment variables

Variable	Description	Required
`MSB_API_KEY`	Microsandbox API key (for MSB backend)	Yes (MSB)
`MSB_SERVER_HOST`	Microsandbox server host (default: localhost)	No
`JWT_SECRET`	JWT secret for API authentication. If set, protected endpoints require `Authorization: Bearer <token>`. If unset, authentication is disabled.	No
`S3_ENABLED`	Enable S3 persistence for mounts (set to `true` or `1`)	No
`S3_BUCKET`	S3 bucket name (required if `S3_ENABLED` is true)	If S3 enabled
`AUTH_SERVER_URL`	Auth server URL for proxying auth endpoints	No

For the full list, see the mvm-ctrl README.

Run the API

heyvm --api --port 3000

The API binds to 0.0.0.0:3000 by default. Use --port to change the port. See CLI reference for options.

Run as a service

Linux (systemd)

Create a systemd unit file:

[Unit]
Description=heyvm API server
After=network.target

[Service]
Type=simple
User=heyvm
ExecStart=/usr/local/bin/heyvm --api --port 3000
Restart=on-failure
RestartSec=5
Environment=MSB_API_KEY=your-key
Environment=MSB_SERVER_HOST=localhost
Environment=HEYVM_FIRECRACKER_CONTAINERD_CTR_COMMAND=sudo -n firecracker-ctr

[Install]
WantedBy=multi-user.target

Save as /etc/systemd/system/heyvm-api.service, create the heyvm user if needed, and add a matching sudoers rule for the real firecracker-ctr binary if you plan to use the firecracker_containerd backend from an unprivileged service, then:

sudo systemctl daemon-reload
sudo systemctl enable heyvm-api
sudo systemctl start heyvm-api

macOS (launchd)

On macOS, heyvm is typically run interactively. For a persistent service, use a launchd plist with ProgramArguments set to /usr/local/bin/heyvm --api --port 3000 and appropriate EnvironmentVariables.

Reverse proxy (HTTPS)

Place nginx or Caddy in front of the API for HTTPS:

Caddy (automatically obtains TLS certificates):

api.example.com {
    reverse_proxy localhost:3000
}

nginx (with certbot for certificates):

server {
    listen 443 ssl;
    server_name api.example.com;
    # ssl_certificate /etc/letsencrypt/...;
    # ssl_certificate_key /etc/letsencrypt/...;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Verify

curl http://localhost:3000/health

Expected response: {"status":"ok"}

For the full HTTP API reference and endpoints, see the mvm-ctrl README.