HostShellService
HostShellService is a root shell on a host, asked for by an administrator, for a while, with a. reason (spin#712). The host is emptied of its workspaces first - unless the request is an. incident’s, which says so - and retired after, whatever happened in it: once a person has had root. on a host it runs no workspace again. Every session is recorded by the control plane, which. carries it; the terminal itself is a WebSocket at /api/host-shells/<id>/terminal. (internal/hostshell).
ApproveHostShell
Section titled “ApproveHostShell”POST /spin.v1.HostShellService/ApproveHostShell
Approves a shell another administrator asked for.
Request
| Field | Type | What it is |
|---|---|---|
id | string |
Response
| Field | Type | What it is |
|---|---|---|
shell | HostShell |
CloseHostShell
Section titled “CloseHostShell”POST /spin.v1.HostShellService/CloseHostShell
Ends a shell: one not yet approved is refused, any other is ended and its host retired.
Request
| Field | Type | What it is |
|---|---|---|
id | string |
Response
| Field | Type | What it is |
|---|---|---|
shell | HostShell |
GetHostShellRecording
Section titled “GetHostShellRecording”POST /spin.v1.HostShellService/GetHostShellRecording
What a shell’s sessions recorded, asciicast v2, each session’s in turn.
Request
| Field | Type | What it is |
|---|---|---|
id | string |
Response
| Field | Type | What it is |
|---|---|---|
sessions | list of string (byte) | Each session’s asciicast v2, in the order they were opened. |
truncated | boolean | Whether there was more than one answer carries: the rest is in the bucket, under host-shells/<id>/. |
ListHostShells
Section titled “ListHostShells”POST /spin.v1.HostShellService/ListHostShells
The installation’s host shells, newest first: all of them, or one host’s.
Request
| Field | Type | What it is |
|---|---|---|
hostId | string | One host’s; empty for every host’s. |
Response
| Field | Type | What it is |
|---|---|---|
shells | list of HostShell |
RequestHostShell
Section titled “RequestHostShell”POST /spin.v1.HostShellService/RequestHostShell
Asks for a shell on a host. Where the installation has a second administrator approve (host_shell_needs_approval), it waits for one; otherwise the host is emptied at once.
Request
| Field | Type | What it is |
|---|---|---|
hostId | string | |
reason | string | Why: said to whoever approves it, and kept. |
minutes | integer (int32) | How long it is open once it opens, up to the installation’s host_shell_max_minutes. |
incident | boolean | Opens on the host as it is, its workspaces running: for a host that has to be looked at busy. |
Response
| Field | Type | What it is |
|---|---|---|
shell | HostShell |
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.

