# HostShellService

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

> spin.v1.HostShellService: 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. -->

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/&lt;id>/terminal. (internal/hostshell).

## 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](https://docs.spinbox.dev/reference/api/types.md#hostshell) |  |

## 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](https://docs.spinbox.dev/reference/api/types.md#hostshell) |  |

## 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/&lt;id>/. |

## 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](https://docs.spinbox.dev/reference/api/types.md#hostshell) |  |

## 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](https://docs.spinbox.dev/reference/api/types.md#hostshell) |  |
