# ExecService

**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.ExecService: 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. -->

ExecService runs commands and moves files in a running workspace, as its root, for a caller who. is no terminal: a program or an agent holding a key with workspace:exec. The control plane logs. in over the same session a terminal's goes over (a host's stream from the guest's vsock, met at. the control plane rather than at the relay) with a certificate of its own for five minutes, and. every call is recorded with who made it and on which credential (audit: workspace_exec).

## Exec

`POST /spin.v1.ExecService/Exec`

Runs command in the workspace's login shell and answers once it has exited, or once timeout has passed: stdin is all of it, given at once, and stdout and stderr are kept up to a bound each.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `command` | string | command is a line for the workspace's shell, as `ssh &lt;workspace> &lt;command>` takes one. |
| `stdin` | string (byte) |  |
| `timeout` | `Duration` | timeout bounds the command, past which it is ended and answered as timed out; unset is a minute, and more than ten is refused. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `exitCode` | integer (int32) | exit_code is the command's exit status; -1 when it ended on a signal or was ended for its timeout. |
| `stdout` | string (byte) |  |
| `stderr` | string (byte) |  |
| `truncated` | boolean | truncated says stdout or stderr ran past the bound kept of each, and the rest is not here. |
| `timedOut` | boolean | timed_out says the command was ended for its timeout. |

## ReadFile

`POST /spin.v1.ExecService/ReadFile`

Reads a file of the workspace's, whole, up to a bound.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `path` | string | path is absolute, or relative to root's home. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `content` | string (byte) |  |

## WriteFile

`POST /spin.v1.ExecService/WriteFile`

Writes a file of the workspace's, whole, making the directories it is in.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `path` | string | path is absolute, or relative to root's home. |
| `content` | string (byte) |  |

**Response**

No fields: `{}`.
