API Overview & Authentication

heyvm exposes everything it can do over an HTTP API, so editors, scripts, and the desktop app can drive sandboxes programmatically. There are two API surfaces:

• The heyvm local API — embedded in the heyvm binary, manages sandboxes on your machine.
• The Cloud API — the multi-tenant control plane that adds deployed sandboxes, networks, shared databases, and daemon registration.

Ports

In --dev mode the CLI points at http://localhost:4445 (cloud) and http://localhost:3001 (auth); in production it uses https://server.heyo.computer and https://auth.heyo.computer.

Authentication

HTTP authentication uses Authorization: Bearer <token>. There are three schemes. A few routes are open by design: GET /health on every service, and the cloud's /traefik/config (internal, consumed by Traefik without auth). Note that the local API only enforces auth when a JWT_SECRET or internal API key is configured — an unconfigured local instance (the same-machine dev case) accepts requests without a token.

JWT (default)

The auth/ service (Better-Auth) issues JWTs and API keys. Services validate the JWT bearer token (issuer auth-service, audience heyo-app). The cloud also supports exchanging an API key for a JWT at the edge.

Static token (cloud-lite / on-prem)

For stripped-down, self-hosted deployments without an auth server, set HEYO_CLOUD_API_TOKEN. When present, the cloud authenticates by comparing the SHA-256 digest of the presented token against that single token's digest instead of validating JWTs, synthesizing admin claims for the configured account (HEYO_CLOUD_STATIC_ACCOUNT_ID, default default). In this mode API-key exchange, entitlement checks, and billing are bypassed.

Subsystems can be toggled independently with HEYO_CLOUD_ENABLE_PROXY, HEYO_CLOUD_ENABLE_EMAIL, HEYO_CLOUD_ENABLE_SQLITE_SAAS, and HEYO_CLOUD_ENABLE_WEBHOOKS.

Internal service-to-service keys

Backend services authenticate to each other with shared internal API keys (for example, heyosecret requires an internal API key on every route). These are not used by end-user clients.

Health checks

Every service exposes GET /health.