Agents and automation
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
Section titled “In four calls”spin workspace create --name task-1 --wait -o jsonspin exec task-1 -- make testspin snapshot diff task-1 <after-id> --from <before-id> -o jsonspin workspace delete task-1{ "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
Section titled “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 30dEvery scope, and what it allows, is in spin api-key.
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, 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:
see its reference.
Give it to the agent through the environment:
export SPIN_ENDPOINT=https://app.<domain>export SPIN_TOKEN=<api-key>spin -o json workspace listThe CLI needs no config file with these set. -o json makes every answer one JSON document.
What the agent can reach
Section titled “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
Section titled “Review, then keep or undo”The pattern for reviewing an agent’s work before you accept it:
spin workspace create --name task-142 --from-snapshot <base-snapshot> --waitspin 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 --waitspin 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
Section titled “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
Section titled “Running commands”spin exec task-142 -w /srv/app -- make testecho $?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
Section titled “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;
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.
Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.

