API Endpoints

Cloud API

The cloud control plane (cloud/src/main.rs) is the multi-tenant service behind https://server.heyo.computer. It exposes roughly 150 routes; the major resource groups are below. All routes use Authorization: Bearer <token> except GET /health and the internal /traefik/config — see Authentication.

Sandboxes

Method Path Purpose
GET /sandbox-deploy-options Available deploy targets
POST /sandbox-deploy Deploy a sandbox
GET /deployed-sandboxes List deployed sandboxes
PATCH / DELETE /deployed-sandboxes/{id} Update / delete a deployed sandbox
* /deployed-sandboxes/{id}/… shell-session, shell-stream, replace-mount, restart, checkpoint, restore, resize, ttl, delete-protection, export-docker, webhooks
* /sandbox/{id}/… exec, exec-operations (+ /{operation_id} polling), write-file, read-file, start, stop, status

Networks (SDN)

Method Path Purpose
* /networks CRUD for networks
GET /networks/me Your network
* /networks/{id}/members, /networks/me/members Membership
* /networks/me/nodes (+ heartbeat) Nodes
* /networks/me/services (+ /dial) Service discovery & dialing

Daemons

These manage your heyvmd hosts:

Method Path Purpose
GET /me/daemons List registered daemons
* /me/daemons/{id}/connection-ticket iroh connection ticket
* /me/daemons/{id}/sandboxes Sandboxes on that daemon
POST /me/daemons/{id}/reconcile-network-membership Reconcile networking
* /me/daemons/{id}/… Per-sandbox shell / display / macOS bootstrap & status sessions

Images, proxy, webhooks

  • Images: /sandbox-images/* (presign, finalize, multipart upload, list, download) and /public-images/* (the same, plus /{image_id}/meta metadata and base/* base-image registration).
  • Proxy / domains: /proxy-endpoints (+ for-deployed), /custom-domains (+ verify), /traefik/config, /p2p-proxy-endpoints.
  • Webhooks / cron: /me/webhooks (+ trigger, cron-triggers), /me/cron-triggers, /me/webhook-events, /webhooks/sandbox-exec/{id}.
  • Jobs (agent v2): /jobs/{job_id}/email-outputs, …/email-triggers, …/webhook-triggers, …/cron-triggers.
  • Archives: /sandbox-archives (presign / finalize / list / get / delete).
  • Email: POST /api/email/send, POST /api/email/poll.

Internal routes

Service-to-service routes live under /internal/* (orchestration, mvm-ctrl backend registration, proxy endpoints, local storage) and /admin/* (NATS, secrets). These are not for end-user clients.