# Agents and automation

**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).

> Give an agent or a CI job a key of its own and a whole machine to work in, and review and undo its work with snapshots, diffs and clones.

A workspace is a whole machine made for a person to work in, which is also what makes it a place
for code you don't fully trust, and an agent writes plenty of that. This page shows how to give an
agent a workspace, how to limit what it can reach, and how to review and undo what it did. What
follows is built and tested; it's also the part of Spinbox that has seen the least day-to-day use
so far.

## In four calls

```bash
spin workspace create --name task-1 --wait -o json
spin exec task-1 -- make test
spin snapshot diff task-1 <after-id> --from <before-id> -o json
spin workspace delete task-1
```

spin snapshot diff task-1 <after-id> --from <before-id> -o json:

```json
{
  "changes": [
    {
      "path": "/etc/greeting",
      "pathBytes": "",
      "kind": "FILE_CHANGE_KIND_ADDED",
      "to": {
        "type": "FILE_TYPE_REGULAR",
        "mode": 420,
        "uid": 0,
        "gid": 0,
        "size": "6",
        "symlinkTarget": "",
        "symlinkTargetBytes": "",
        "sha256": "5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
        "modifiedAt": "2026-10-21T18:04:00Z"
      }
    },
    {
      "path": "/etc/hosts",
      "pathBytes": "",
      "kind": "FILE_CHANGE_KIND_MODIFIED",
      "from": {
        "type": "FILE_TYPE_REGULAR",
        "mode": 420,
        "uid": 0,
        "gid": 0,
        "size": "20",
        "symlinkTarget": "",
        "symlinkTargetBytes": "",
        "sha256": "081ef9d5367595d16e30b4b4549d9f43537320508b4ce0788963e10e4f808857",
        "modifiedAt": "2026-10-21T17:58:00Z"
      },
      "to": {
        "type": "FILE_TYPE_REGULAR",
        "mode": 420,
        "uid": 0,
        "gid": 0,
        "size": "29",
        "symlinkTarget": "",
        "symlinkTargetBytes": "",
        "sha256": "2c155a6a94b4ccf8996a7c0a185525d3a290ce344d76083b1d768e6409582f6e",
        "modifiedAt": "2026-10-21T18:04:00Z"
      }
    },
    {
      "path": "/etc/issue",
      "pathBytes": "",
      "kind": "FILE_CHANGE_KIND_REMOVED",
      "from": {
        "type": "FILE_TYPE_REGULAR",
        "mode": 420,
        "uid": 0,
        "gid": 0,
        "size": "26",
        "symlinkTarget": "",
        "symlinkTargetBytes": "",
        "sha256": "",
        "modifiedAt": "2026-10-21T17:58:00Z"
      }
    }
  ],
  "truncated": false
}
```

Every command prints JSON with `-o json`: the whole answer, each file's type, mode, size and hash
on both sides. A model reading this site starts at
[`/llms.txt`](https://docs.spinbox.dev/llms.txt.md), and every page has a Markdown twin. The control plane's API is in
[the API reference](https://docs.spinbox.dev/reference/api.md).

## A key for the agent

Create an API key with only the scopes the agent needs:

```bash
spin api-key create "review-bot" --scope workspace:read --scope workspace:write --expires 30d
```

Every scope, and what it allows, is in [`spin api-key`](https://docs.spinbox.dev/reference/cli/api-key.md).

A key can never approve a login or administer the installation. It lasts at most a year. The
secret is shown once.

Two scopes are apart from the rest. `workspace:exec` [runs commands and reads and writes files in
your workspaces through the API](https://docs.spinbox.dev/reference/status.md#access), as root: a key that holds it is made with your passkey, in the
dashboard, and every call it makes is in the audit log. `keys:delegate` lets a key make keys of
its own, for the agents it starts: each holds no more than it does - its scopes, team, projects,
end, and how many workspaces and cores all of them have on runners at once (`--max-workspaces`,
`--max-cores`; a stopped workspace counts for neither) -
and goes when it is revoked. `spin mcp` [serves an agent the API on such a key](https://docs.spinbox.dev/reference/status.md#access):
see [its reference](https://docs.spinbox.dev/reference/cli/mcp.md).

Give it to the agent through the environment:

```bash
export SPIN_ENDPOINT=https://app.<domain>
export SPIN_TOKEN=<api-key>
spin -o json workspace list
```

The CLI needs no config file with these set. `-o json` makes every answer one JSON document.

## What the agent can reach

An agent that creates its own workspace usually names no network policy, so the workspace runs
under the installation's `default_network_tags`, and under `offline` if there are none. This is
where an administrator decides what an agent may reach: for example a policy that allows your
Git host and your package registry, and nothing else. See [Network and
egress](https://docs.spinbox.dev/concepts/network.md).

Afterwards, `spin workspace egress <workspace>` shows what it reached and what it was refused.

The key the agent talks to its provider with need not be on the disk at all: see [An agent
without keys](https://docs.spinbox.dev/use/agent-keys.md).

## Review, then keep or undo

The pattern for reviewing an agent's work before you accept it:

```bash
spin workspace create --name task-142 --from-snapshot <base-snapshot> --wait
spin snapshot create task-142 --description before --wait

# ... the agent works in task-142, with spin exec or over SSH ...

spin snapshot create task-142 --description after --wait
spin snapshot diff task-142 <after> --from <before> --under /srv/app
```

- Like the diff: keep the workspace, or take what it produced.
- Do not like it: stop the workspace and `spin workspace restore task-142 <before>`.
- Want to try again from the same point: create another workspace `--from-snapshot <before>`.

## Many attempts at once

Every workspace created from one snapshot is a clone of the same layers. Starting ten attempts
from the same state costs the disk of one, plus what each attempt writes. Each is its own
machine, with its own kernel, writable layer and network namespace, so attempts share none of
those.

## Running commands

```bash
spin exec task-142 -w /srv/app -- make test
echo $?
```

`spin exec` streams output, forwards standard input, and exits with the command's exit status,
so it composes with the agent's own tools. It needs no network path to the workspace.

## The API

Everything the CLI does is a ConnectRPC call to the control plane, over HTTPS with the same key
(`Authorization: Bearer <api-key>`). ConnectRPC speaks plain JSON over HTTP POST, so any language
can call it. Every service and what each call takes is in [the API reference](https://docs.spinbox.dev/reference/api.md);
`spin.v1.ExecService` is the one that runs a command and reads and writes files in a workspace,
for a key that holds `workspace:exec`.
