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.

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:

HeaderValue
service-codecloud_user
AuthorizationBearer {token}

VPS queries and mutations also send these headers on each operation (the frontend passes them through Apollo context.headers):

HeaderValue
x-vps-project-id<VPS_PROJECT_ID>
x-vps-subscription-id{subscriptionId} (only when known)

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.

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 operation as success,
  • drops or refetches the cached instance, list and activity log (power mutations refetch Instance_getInstance, Instance_listInstances and Instance_listInstanceActivities; create, delete, resize and rebuild evict instance_listInstances and/or instance_getInstance from the cache),
  • polls the activity log every 5 s while any activity is PENDING or IN_PROGRESS,
  • derives a "starting… / stopping…" state when desiredRuntime differs from observedRuntime (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:

EnumValues
instance_LifecycleStateLIFECYCLE_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_RuntimeStateRUNTIME_STATE_UNSPECIFIED, RUNTIME_STATE_RUNNING, RUNTIME_STATE_STOPPED
instance_OperationKindOPERATION_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_OperationStateOPERATION_STATE_UNSPECIFIED, OPERATION_STATE_PENDING, OPERATION_STATE_RUNNING, OPERATION_STATE_COMPENSATING, OPERATION_STATE_SUCCEEDED, OPERATION_STATE_FAILED, OPERATION_STATE_NEEDS_ATTENTION
instance_OperationPhaseOPERATION_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_StepStateSTEP_STATE_UNSPECIFIED, STEP_STATE_PENDING, STEP_STATE_DISPATCHING, STEP_STATE_IN_FLIGHT, STEP_STATE_SUCCEEDED, STEP_STATE_FAILED
instance_AddressFamilyADDRESS_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.

Reference

SectionContents
InstancesList, get and create instances
Power & lifecycleStart, stop, restart, resize, rebuild and delete an instance
Plans & imagesThe plans (sizes) and OS images an instance can use
SSH keysList, add and delete the account's SSH public keys
Monitoring & activityLive status, time-series metrics and the instance activity log
ConsoleOpen a VNC or serial web console session
Operations & eventsRead 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.