v4

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

vm-services

Register or update a service on a VM

Idempotent register-or-update: same name + new port updates the port; same name + same port is a no-op. Returns the resulting entry. Used to change the upstream port for an existing service registration without dropping and re-creating it.

put/v1/vms/{id}/services/{serviceName}

Request body

portinteger required

New TCP port. Same value as the existing entry is a no-op.

h2cboolean

Optional. When true, the proxy uses HTTP/2 cleartext to the backend. Same value as the existing entry is a no-op; a different value updates the registered transport.

Response

Service updated (or no-op same-port re-issue)

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.