HostService
ActivateHost
Section titled “ActivateHost”POST /spin.v1.HostService/ActivateHost
Activate a drained host (set to healthy, admin only)
Request
| Field | Type | What it is |
|---|---|---|
id | string |
Response
| Field | Type | What it is |
|---|---|---|
host | Host |
DrainHost
Section titled “DrainHost”POST /spin.v1.HostService/DrainHost
Set host to draining (admin only)
Request
| Field | Type | What it is |
|---|---|---|
id | string | |
suspend | boolean | Suspend 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. |
leaveStopped | boolean | leave_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
| Field | Type | What it is |
|---|---|---|
host | Host | |
suspendedWorkspaceIds | list of string | |
failures | list of WorkspaceSuspendFailure |
GetFleet
Section titled “GetFleet”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
| Field | Type | What it is |
|---|---|---|
autoscaling | boolean | False when no fleet is configured: the hosts of this installation are whatever somebody registered by hand, and none of the numbers below mean anything. |
connected | integer (int32) | The hosts that are connected now, of every class, which lags what was asked for by a machine’s boot. |
idleMinutes | integer (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. |
quietHours | string | |
timeZone | string | |
maxHosts | integer (int32) | The most hosts of every class together; 0 is no limit of the installation’s own. |
classes | list of FleetClass | Each host class’s group, the default first. |
GetHost
Section titled “GetHost”POST /spin.v1.HostService/GetHost
Get host details (admin only)
Request
| Field | Type | What it is |
|---|---|---|
id | string |
Response
| Field | Type | What it is |
|---|---|---|
host | Host | |
departure | HostDeparture | What 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. |
GetHostPolicy
Section titled “GetHostPolicy”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
| Field | Type | What it is |
|---|---|---|
hostId | string |
Response
| Field | Type | What it is |
|---|---|---|
policy | HostPolicy | |
writebackPresets | list of WritebackPreset | The 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. |
writebackTest | WritebackTest | The last writeback test of this host, while SetHostPolicy still takes its thresholds. |
ListHosts
Section titled “ListHosts”POST /spin.v1.HostService/ListHosts
List all hosts (admin only)
Request
| Field | Type | What it is |
|---|---|---|
page | PageRequest | |
stateFilter | HostState |
Response
| Field | Type | What it is |
|---|---|---|
hosts | list of Host | |
page | PageResponse |
RemoveHost
Section titled “RemoveHost”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
| Field | Type | What it is |
|---|---|---|
id | string | |
taken | boolean | The 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. |
leaveWorkspaces | boolean | Remove 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
| Field | Type | What it is |
|---|---|---|
removal | HostRemoval | removal is what was done: GIVE_BACK or FORGET. |
givenBack | boolean | given_back is the machine terminated and its group asked for one less; false where the group no longer had it. |
forgotten | boolean | forgotten 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. |
markedForRekey | integer (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. |
kept | string | kept 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. |
SetHostPolicy
Section titled “SetHostPolicy”POST /spin.v1.HostService/SetHostPolicy
Request
| Field | Type | What it is |
|---|---|---|
policy | HostPolicy | Sent whole: what is left unset is unset, so a write is the policy and not a patch. |
Response
| Field | Type | What it is |
|---|---|---|
policy | HostPolicy |
TestHostWriteback
Section titled “TestHostWriteback”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
| Field | Type | What it is |
|---|---|---|
hostId | string | |
limitBytes | string (int64) | The candidates, as HostPolicy holds them. |
backgroundBytes | string (int64) |
Response
| Field | Type | What it is |
|---|---|---|
test | WritebackTest |
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.

