Agents and automation

Spinbox is built for code you do not fully trust, and an agent is the most common author of such code. 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.

In four calls

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

{
  "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, and every page has a Markdown twin. The control plane’s API is in the API reference.

A key for the agent

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

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.

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

Give it to the agent through the environment:

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.

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.

Review, then keep or undo

The pattern that makes an agent’s work safe to accept:

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, so no attempt sees another.

Running commands

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. The services are spin.v1.WorkspaceService, ShareService, SSHKeyService, TeamService, SettingsService and LogService.