# HostService

**Spinbox is experimental: APIs change and data may be lost.** What is built and what proves it is on [Status](https://spin-stack.github.io/website/reference/status.md); what Spinbox does not do is on [Limitations](https://spin-stack.github.io/website/overview/limitations.md).

> spin.v1.HostService: each procedure, its request and its response.

<!-- Generated by tools/refgen from spin:internal/controlplane/apidocs/spin.v1.openapi.json. Edit the source, not this file. -->

## 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](https://spin-stack.github.io/website/reference/api/types.md#host) |  |

## 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](https://spin-stack.github.io/website/reference/api/types.md#host) |  |
| `suspendedWorkspaceIds` | list of string |  |
| `failures` | list of [WorkspaceSuspendFailure](https://spin-stack.github.io/website/reference/api/types.md#workspacesuspendfailure) |  |

## 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 group is configured: the hosts of this installation are whatever somebody registered by hand, and none of the numbers below mean anything. |
| `group` | string | The group the control plane sizes, as its cloud names it. |
| `desired` | integer (int32) | What it last asked the group for, and the most it may ask: zero of one is a fleet at rest, which is what an idle installation looks like. |
| `most` | integer (int32) |  |
| `connected` | integer (int32) | The hosts that are connected now, which lags desired by a machine's boot: one desired and none connected is a machine on its way. |
| `waiting` | integer (int32) | Workspaces that have nowhere to run yet, and when the first of them started waiting: this is what makes the control plane ask for a machine. |
| `oldestWaiting` | `Timestamp` |  |
| `busy` | integer (int32) | Workspaces that are keeping the fleet up. |
| `idleMinutes` | integer (int32) | How long the fleet may be idle before the group is emptied, and the window in which it is emptied at once. Empty quiet_hours is none. |
| `quietHours` | string |  |
| `timeZone` | string |  |

## 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](https://spin-stack.github.io/website/reference/api/types.md#host) |  |

## 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](https://spin-stack.github.io/website/reference/api/types.md#hostpolicy) |  |
| `writebackPresets` | list of [WritebackPreset](https://spin-stack.github.io/website/reference/api/types.md#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](https://spin-stack.github.io/website/reference/api/types.md#writebacktest) | The last writeback test of this host, while SetHostPolicy still takes its thresholds. |

## ListHosts

`POST /spin.v1.HostService/ListHosts`

List all hosts (admin only)

**Request**

| Field | Type | What it is |
|---|---|---|
| `page` | [PageRequest](https://spin-stack.github.io/website/reference/api/types.md#pagerequest) |  |
| `stateFilter` | [HostState](https://spin-stack.github.io/website/reference/api/types.md#hoststate) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `hosts` | list of [Host](https://spin-stack.github.io/website/reference/api/types.md#host) |  |
| `page` | [PageResponse](https://spin-stack.github.io/website/reference/api/types.md#pageresponse) |  |

## SetHostPolicy

`POST /spin.v1.HostService/SetHostPolicy`

**Request**

| Field | Type | What it is |
|---|---|---|
| `policy` | [HostPolicy](https://spin-stack.github.io/website/reference/api/types.md#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](https://spin-stack.github.io/website/reference/api/types.md#hostpolicy) |  |

## 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](https://spin-stack.github.io/website/reference/api/types.md#writebacktest) |  |