VPS
VPS (Virtual Private Server) lets a user run a virtual machine on Sabay
infrastructure. All VPS operations use the gateway's instance_* fields. The
console treats each VPS subscription as holding one instance: the instance
detail page lists the subscription's instances and shows the first one.
Verified against app.web.cloud.sabay.com (commit bcd97ff4) and the testing
gateway schema on 2026-11-16.
GraphQL Gateway
All VPS operations go through a single GraphQL endpoint:
https://cloud-gateway.sabay.com/graphql
Headers
Every request carries the standard authentication headers:
| Header | Value |
|---|---|
service-code | cloud_user |
Authorization | Bearer {token} |
VPS queries and mutations also send these headers on each operation (the
frontend passes them through Apollo context.headers):
| Header | Value |
|---|---|
x-vps-project-id | <VPS_PROJECT_ID> |
x-vps-subscription-id | {subscriptionId} (only when known) |
Every VPS HTTP operation in the frontend (all 20 queries and mutations in this
section) builds its headers with vpsHeaders(subscriptionId?). It always adds
x-vps-project-id and adds x-vps-subscription-id only when a subscription ID
is passed. The app hard-codes a single project ID for every user; it is shown
here as <VPS_PROJECT_ID>. All UI callers pass the route's :subscriptionId
(see Subscriptions). The one exception is the unused
useListInstancePlan hook, which sends only the project header. The
instance_watchOperation subscription
goes over WebSocket (graphql-ws) and sends no VPS headers, only
Authorization and service-code in connectionParams.
Replace {token} with your own access token. Never commit tokens to source
control.
The service code for VPS is cloud_vps (ServiceCode.CLOUD_VPS).
BusinessCategoryCode.VPS = "BS-107" is defined in the frontend but not used
yet, since the VPS service option has categoryCode: "". Like every product
code, it is never sent as the service-code header.
A comment in the frontend's src/constants/constants.ts, above
ALL_SERVICE_CODES, says CLOUD_VPS is left out because the gateway's
sb_ServiceCode enum has no VPS member. That comment is out of date on both
counts: the array does include ServiceCode.CLOUD_VPS, and the testing
gateway's sb_ServiceCode enum now does include CLOUD_VPS. The VPS entry
in the service list also has no business category yet (categoryCode: "").
Async operation model
Every instance-changing mutation (create, delete, start, stop,
restart, resize, rebuild) returns at once with an operation object
(id, kind, state, steps, error fields, timestamps). The work then runs
in the background. All of them select the same operation fields, shown in each
Request block.
You can follow an operation by ID with Get Operation or Watch Operation. The frontend does not do that. Instead it:
- shows a "… started" or "Instance is starting/stopping/restarting" toast and
treats a returned
operationas success, - drops or refetches the cached instance, list and activity log (power mutations
refetch
Instance_getInstance,Instance_listInstancesandInstance_listInstanceActivities; create, delete, resize and rebuild evictinstance_listInstancesand/orinstance_getInstancefrom the cache), - polls the activity log every
5 s while any activity is
PENDINGorIN_PROGRESS, - derives a "starting… / stopping…" state when
desiredRuntimediffers fromobservedRuntime(see Power-state handling).
Every operation-starting mutation sends a fresh idempotencyKey built as
<prefix>-<first 8 chars of a random UUID>. The prefix is the instance ID, or
the new instance's name on create.
Enums
From the gateway schema:
| Enum | Values |
|---|---|
instance_LifecycleState | LIFECYCLE_STATE_UNSPECIFIED, LIFECYCLE_STATE_PROVISIONING, LIFECYCLE_STATE_ACTIVE, LIFECYCLE_STATE_REBUILDING, LIFECYCLE_STATE_SUSPENDED, LIFECYCLE_STATE_DELETING, LIFECYCLE_STATE_DELETED, LIFECYCLE_STATE_FAILED, LIFECYCLE_STATE_ORPHANED |
instance_RuntimeState | RUNTIME_STATE_UNSPECIFIED, RUNTIME_STATE_RUNNING, RUNTIME_STATE_STOPPED |
instance_OperationKind | OPERATION_KIND_UNSPECIFIED, OPERATION_KIND_CREATE, OPERATION_KIND_DELETE, OPERATION_KIND_START, OPERATION_KIND_STOP, OPERATION_KIND_RESTART, OPERATION_KIND_RESIZE, OPERATION_KIND_REBUILD, OPERATION_KIND_SUSPEND, OPERATION_KIND_RESUME, OPERATION_KIND_MIGRATE |
instance_OperationState | OPERATION_STATE_UNSPECIFIED, OPERATION_STATE_PENDING, OPERATION_STATE_RUNNING, OPERATION_STATE_COMPENSATING, OPERATION_STATE_SUCCEEDED, OPERATION_STATE_FAILED, OPERATION_STATE_NEEDS_ATTENTION |
instance_OperationPhase | OPERATION_PHASE_UNSPECIFIED, OPERATION_PHASE_PREPARING, OPERATION_PHASE_PROVISIONING, OPERATION_PHASE_NETWORKING, OPERATION_PHASE_CONFIGURING, OPERATION_PHASE_STOPPING, OPERATION_PHASE_REMOVING, OPERATION_PHASE_STARTING, OPERATION_PHASE_FINALIZING |
instance_StepState | STEP_STATE_UNSPECIFIED, STEP_STATE_PENDING, STEP_STATE_DISPATCHING, STEP_STATE_IN_FLIGHT, STEP_STATE_SUCCEEDED, STEP_STATE_FAILED |
instance_AddressFamily | ADDRESS_FAMILY_UNSPECIFIED, ADDRESS_FAMILY_IPV4, ADDRESS_FAMILY_IPV6 |
google__protobuf__Timestamp is an RFC 3339 date-time string (for example
2019-12-03T09:54:33Z). BigInt is a whole number.
Sample responses in this section are generated from the schema: each value shows the field's type, not real data.
Reference
| Section | Contents |
|---|---|
| Instances | List, get and create instances |
| Power & lifecycle | Start, stop, restart, resize, rebuild and delete an instance |
| Plans & images | The plans (sizes) and OS images an instance can use |
| SSH keys | List, add and delete the account's SSH public keys |
| Monitoring & activity | Live status, time-series metrics and the instance activity log |
| Console | Open a VNC or serial web console session |
| Operations & events | Read or stream the state of a background operation |
See also Realtime events for how subscriptions connect over WebSocket, and the API inventory for every operation across services.