v4

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-05-09283767.7 KB

vm-services

Register a service on a VM

Registers an HTTP service on the VM under name, listening on port. The service immediately becomes addressable at https://<name>--<vmIdHexNoHyphens>.proxy.<stack-domain> once the firewall is applied (synchronous).

Idempotent: a POST with a name that already exists at the same (port, h2c) returns 201 with the existing entry. POST with a name that already exists at a different port OR different h2c returns 409 — use PUT to update an existing service.

Per-VM cap: currently 16 services per VM (configurable via MAX_SERVICES_PER_VM on the scheduler).

post/v1/vms/{id}/services

Request body

namestring required

portinteger required

h2cboolean

Optional. When true, the proxy uses HTTP/2 cleartext to the backend (required for gRPC). Defaults to false (HTTP/1.1).

Response

Service registered (or idempotent same-(port, h2c) re-register)

namestring required

Service name (1–29 chars). Embedded in the public URL as <name>--<vmIdHexNoHyphens>.proxy.<stack-domain>.

portinteger required

TCP port the service listens on inside the VM. Privileged ports (<1024) are rejected.

h2cboolean required

When true, the proxy speaks HTTP/2 cleartext (h2c) to the backend. Required for gRPC and h2c-only apps. When false (default), the proxy uses HTTP/1.1 — covers HTTP/1.1 apps, Server-Sent Events, and WebSocket pass-through.