Skip to content
Spinbox is experimental: APIs change and data may be lost. Status lists what is built and what proves it.

HostService

View Markdown

POST /spin.v1.HostService/ActivateHost

Activate a drained host (set to healthy, admin only)

Request

FieldTypeWhat it is
idstring

Response

FieldTypeWhat it is
hostHost

POST /spin.v1.HostService/DrainHost

Set host to draining (admin only)

Request

FieldTypeWhat it is
idstring
suspendbooleanSuspend every running workspace off the host: its memory and disk go to the object store, and it is resumed on whichever other host has room, on its own - or, suspended without its memory, on its owner’s next start. Answered once each is suspended or has failed to be; a workspace that failed runs on as it was.
leaveStoppedbooleanleave_stopped is for a drain that shrinks the fleet: the workspaces it suspends stay stopped, and each resumes on another host when its owner starts it. Without it they are resumed elsewhere at once, waiting for a host where the installation is bringing one up.

Response

FieldTypeWhat it is
hostHost
suspendedWorkspaceIdslist of string
failureslist of WorkspaceSuspendFailure

POST /spin.v1.HostService/GetFleet

The fleet as a whole (admin only): how many hosts there are against how many the installation has asked its cloud for, and what it is waiting for. A fleet that scales from none looks broken without this - no hosts, no explanation, and a workspace that waits minutes for a machine to boot with nothing saying so.

Request

No fields: {}.

Response

FieldTypeWhat it is
autoscalingbooleanFalse when no fleet is configured: the hosts of this installation are whatever somebody registered by hand, and none of the numbers below mean anything.
connectedinteger (int32)The hosts that are connected now, of every class, which lags what was asked for by a machine’s boot.
idleMinutesinteger (int32)How long a class’s group may be idle before it is emptied, and the window in which it is emptied at once. Empty quiet_hours is none.
quietHoursstring
timeZonestring
maxHostsinteger (int32)The most hosts of every class together; 0 is no limit of the installation’s own.
classeslist of FleetClassEach host class’s group, the default first.

POST /spin.v1.HostService/GetHost

Get host details (admin only)

Request

FieldTypeWhat it is
idstring

Response

FieldTypeWhat it is
hostHost
departureHostDepartureWhat taking the host out would do to each workspace on it, as the server would do it: asked of one host, because it reads every workspace there.

POST /spin.v1.HostService/GetHostPolicy

What a host may do, as against what it is (admin only). A host reads what it *is* from its own environment, before it can reach this; everything else it is told, on its heartbeat, and it reports back the revision it is running under.

Request

FieldTypeWhat it is
hostIdstring

Response

FieldTypeWhat it is
policyHostPolicy
writebackPresetslist of WritebackPresetThe writeback thresholds an operator chooses from without testing them on the host, each with what it measured. The first is unset: what the host booted with.
writebackTestWritebackTestThe last writeback test of this host, while SetHostPolicy still takes its thresholds.

POST /spin.v1.HostService/ListHosts

List all hosts (admin only)

Request

FieldTypeWhat it is
pagePageRequest
stateFilterHostState

Response

FieldTypeWhat it is
hostslist of Host
pagePageResponse

POST /spin.v1.HostService/RemoveHost

Takes a machine of an autoscaling group out of the fleet (admin only), as Host.removal says: given back to its group (GIVE_BACK), or forgotten (FORGET). A host whose removal is REVOKE is refused: RevokeRunner is its removal. Asked with taken, the host leaves as one believed compromised: its credentials revoked and every team’s disk whose key it was given marked for re-keying (ListRekeys), as RevokeRunner does, and its machine given back all the same.

Request

FieldTypeWhat it is
idstring
takenbooleanThe host is believed taken - compromised - rather than only no longer wanted. Its credentials are deleted and its stream cut before its group is asked anything, and every team’s disk whose key it was given is marked for re-keying. A routine removal - a scale-in, a machine reclaimed - leaves it unset, and marks none.
leaveWorkspacesbooleanRemove a taken host although it is the only home of workspaces’ disks. Refused without it, naming them; with it each runs again only once it is recovered onto another host (RecoverWorkspace), which gives up what this host had not published. Only with taken: a routine removal loses no disk.

Response

FieldTypeWhat it is
removalHostRemovalremoval is what was done: GIVE_BACK or FORGET.
givenBackbooleangiven_back is the machine terminated and its group asked for one less; false where the group no longer had it.
forgottenbooleanforgotten is the host’s row gone. A host given back while connected is not: it drains under its termination hook, and its row goes when its stream ends.
markedForRekeyinteger (int32)marked_for_rekey is how many teams’ disks were marked for re-keying: those whose key a host removed as taken was given. Zero for a routine removal.
keptstringkept is why the row was not forgotten, where it was not and should have been: the workspace whose disk is only there, or the volume that would not leave it and whose that is. Empty when forgotten, and for a host given back while connected.

POST /spin.v1.HostService/SetHostPolicy

Request

FieldTypeWhat it is
policyHostPolicySent whole: what is left unset is unset, so a write is the policy and not a patch.

Response

FieldTypeWhat it is
policyHostPolicy

POST /spin.v1.HostService/TestHostWriteback

Measures a host’s disk under writeback thresholds no preset names, against the ones it holds (admin only). SetHostPolicy refuses such thresholds for a host until it has been tested with them; the test loads that host’s disk for about forty seconds.

Request

FieldTypeWhat it is
hostIdstring
limitBytesstring (int64)The candidates, as HostPolicy holds them.
backgroundBytesstring (int64)

Response

FieldTypeWhat it is
testWritebackTest

Generated by task reference from spin/internal/controlplane/apidocs/spin.v1.openapi.json at 51f7e0dea.

Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.