stateweave Docs
Your sandbox

Sandboxes

A sandbox is the apps your agent works in and what they hold. A new one is blank. You fill it in edit mode, then switch it to test mode, which keeps what it holds as a version: every run starts from fresh copies of it.

What a blank sandbox holds

Only what makes each app's API usable: the account, its owner, an OAuth client or app, and the owner's token. It also has the configuration a real new account comes with and its API cannot create. There is no business content: no messages, mail, events, files, records, tickets or customers.

The owner is the only person in every app, with the handle owner. You name them when you make the sandbox (by default Sandbox Owner, owner@example.com). Names and domains come from the sandbox's name, and client secrets are drawn for each sandbox.

AppA blank sandbox has
SlackThe workspace, named after the sandbox. The owner as its primary owner. One app with its bot. #general and #random, with no messages.
GmailThe owner's mailbox, empty. An OAuth client.
Google CalendarThe owner's account and calendars, with no events. An OAuth client and an API key.
Google SheetsThe owner's account, with no spreadsheets. An OAuth client.
Google DriveThe owner's account, with no files. An OAuth client.
SalesforceThe org, named after the sandbox. The owner as its only user. A connected app. No records.
ShopifyThe store, named after the sandbox. The owner as its account owner. One location and an app. No products, customers or orders.
ZendeskThe account, named after the sandbox. The owner as its admin. An OAuth client. The configuration a new account comes with: its ticket form, ticket fields, views, macros and triggers. No tickets and no end users.
WhatsAppA business, an app and a WhatsApp Business account with one test number and the hello_world template. The owner, and a system user with its token. No test recipients, customers or messages.
Microsoft TeamsThe tenant, named after the sandbox, with its onmicrosoft.com domain. The owner as its only person, owning the team a new tenant comes with (named after the sandbox) and its General channel. A public client for Graph, and a bot installed in the team. No chats or messages.
StripeThe account, named after the sandbox, with the owner's email address. The owner's secret key, a restricted key for agents and a publishable key. No customers, products, payments or webhook endpoints.
HubSpotThe account, with a portal id of its own. The owner as its only user, a super admin. A Service Key and the owner's MCP connector token. No records, lists or custom objects.
GitHubThe owner's personal account, with the login owner and the owner's name and email address. A classic personal access token (ghp_…) with scopes such as repo, workflow and admin:org. No organization, team, repository, other person or webhook.

The Starter sandbox

Every workspace is given one sandbox when it is made: Starter, a blank sandbox with every app StateWeave has when the workspace is made, in edit mode. Your plan doesn't count it among its new sandboxes, so it is the one to try things in, and the one your coding agent uses when it sets your agent up. sw sandbox ls marks it. Open only the apps a run needs (sw run p-… --apps slack,zendesk), so the others don't start. It is a sandbox like any other: fill it, rename it or delete it. A deleted Starter is not made again, and a copy of it counts like any new sandbox.

Make a sandbox

sw sandbox new "Acme Robotics" --apps slack,zendesk \
  --owner-name "Ada Lovelace" --owner-email ada@acme.example
import stateweave

client = stateweave.Client()
sb = client.create_sandbox("Acme Robotics", ["slack", "zendesk"],
                           owner_name="Ada Lovelace", owner_email="ada@acme.example")
print(sb["id"], sb["mode"])  # p-7d21c4 edit
curl -s -X POST "$STATEWEAVE_URL/api/v1/sandboxes" \
  -H "Authorization: Bearer $STATEWEAVE_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Acme Robotics", "apps": ["slack", "zendesk"],
       "owner": {"name": "Ada Lovelace", "email": "ada@acme.example"}}'
swPythonRESTDescription
NAMEnamenameRequired. What to call the sandbox, up to 80 characters.
--appsappsappsRequired. Any of slack, gmail, google_calendar, google_sheets, google_drive, salesforce, shopify, zendesk, whatsapp, microsoft_teams, stripe, hubspot, github.
--owner-nameowner_nameowner.nameThe owner's name.
--owner-emailowner_emailowner.emailThe owner's email address.
--time-zonetime_zonetime_zoneAn IANA name such as Europe/London. Default UTC.

sw sandbox new prints the new sandbox's id, which starts with p-. The REST call answers 201 with the sandbox: "kind": "sandbox", "mode": "edit", no versions yet, and its owner.

Shell
sw sandbox ls
sw sandbox show p-7d21c4
Output
p-3b9e01  edit  v0  2026-11-13  github,gmail,google_calendar,google_drive,google_sheets,hubspot,microsoft_teams,salesforce,shopify,slack,stripe,whatsapp,zendesk  Starter  (starter: not counted against the plan)
p-7d21c4  edit  v0  2026-11-13  slack,zendesk  Acme Robotics

p-7d21c4  Acme Robotics  (ready)
  slack    stopped  1 people, 2 channels, 0 messages, 0 threads, 0 DMs
  zendesk  stopped  0 tickets, 0 comments, 1 agents, 0 end users, 1 organizations, 1 groups
  mode edit, 0 version(s), owner ada@acme.example

Edit mode

A new sandbox starts in edit mode. Whatever is done to its apps becomes what the sandbox holds: calls through their APIs, StateWeave's actions, a company generated from a prompt while it is blank, and what you do in their web clients in your workspace. Fill a sandbox covers each way.

In your workspace, a sandbox's Fill tab gathers them: the prompt (while it is blank), how to connect from a script, StateWeave's actions, and each running app's addresses and tokens under Addresses and tokens. Start sandbox starts its apps there, to look at and use them in their web clients; its API, tests and runs don't need it.

What changed since the last version

sw sandbox changes p-7d21c4
print(client.sandbox_changes("p-7d21c4"))
curl -s "$STATEWEAVE_URL/api/v1/sandboxes/p-7d21c4/changes" -H "Authorization: Bearer $STATEWEAVE_API_KEY"
Response
{"mode": "edit", "changes": {"slack": {"added": 1, "changed": 0, "removed": 0}, "zendesk": {"added": 3, "changed": 0, "removed": 0}}, "versions": []}

Per app, the records added, changed and removed in edit mode that are not in a version yet. Apps with no change are left out. In test mode changes is always empty.

Test mode and versions

Switching to test mode keeps what the sandbox holds as a version, when anything changed since the last one. Its own apps stop.

sw sandbox mode p-7d21c4 test
sb = client.set_mode("p-7d21c4", "test")
print(sb["versions"][-1])   # {"n": 1, "at": …, "changes": {"slack": {"added": 1, …}, …}}
curl -s -X POST "$STATEWEAVE_URL/api/v1/sandboxes/p-7d21c4/mode" \
  -H "Authorization: Bearer $STATEWEAVE_API_KEY" -H "Content-Type: application/json" -d '{"mode": "test"}'
Output
p-7d21c4 is in test mode; version 1
  • Tests and runs start from the latest version. Each run, twin run and task being proven gets fresh copies of the apps, restored to it. Before the first version, they start from what the sandbox was made with: the blank apps, or the generated company.
  • A reset goes back to the version. Resetting a twin run puts its apps back to the latest version, not to the blank sandbox.
  • Nothing a run does reaches the sandbox. Each run has its own copies.
  • Looking is not kept. In test mode, opening the sandbox's apps in your workspace starts them from the latest version, in a run of their own. Nothing you do there is kept.
  • Changed apps need a re-check. When a new version changes an app, that app's tests are marked stale: what they check may have changed. Run sw task recheck before running them again.

To change the sandbox again, switch it back to edit mode: its apps start from the latest version, and the next switch to test mode makes the next version. Switching without a change makes no version. Changes made in edit mode are in no test or run until they are in a version.

Each version has its number n, when it was kept (at), and per app the records added, changed and removed. sw sandbox show prints the mode and how many versions there are; client.sandbox(id)["versions"] lists them.

Rename or copy a sandbox

A sandbox's ⋯ menu in your workspace has Rename, Duplicate and Delete sandbox, and, for a generated company, Download its spec (scenario.yaml). Renaming changes only its name: its id, versions, tests and runs stay as they are.

A copy is a new sandbox, with its own id, holding what this one's apps hold now, as its one starting point, in the same mode:

  • From test mode, the copy is in test mode, and its version 1 is the original's latest version.
  • From edit mode, the copy is in edit mode, holding everything edit mode has done so far, in a version or not. That is its version 1, and its apps start, as after a switch to edit mode.
  • A blank sandbox makes a blank copy, which can still be filled from a prompt.

The copy has none of the original's earlier versions, tests or runs, and from then on each goes its own way. Ids of records are the same in both, so a task written for one can be pointed at the other by changing stateweave_sandbox. Use a copy to change data without touching the sandbox your tests run on.

sw sandbox rename p-7d21c4 "Acme support"
sw sandbox copy p-7d21c4 --name "Acme support, refunds"     # prints the copy's id
client.rename_sandbox("p-7d21c4", "Acme support")
copy = client.copy_sandbox("p-7d21c4", "Acme support, refunds")
print(copy["id"], copy["mode"], copy["versions"])
curl -s -X PATCH "$STATEWEAVE_URL/api/v1/sandboxes/p-7d21c4" \
  -H "Authorization: Bearer $STATEWEAVE_API_KEY" -H "Content-Type: application/json" -d '{"name": "Acme support"}'
curl -s -X POST "$STATEWEAVE_URL/api/v1/sandboxes/p-7d21c4/copy" \
  -H "Authorization: Bearer $STATEWEAVE_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Acme support, refunds"}'

Without a name, the copy is called <name> copy.

Delete a sandbox

Delete sandbox stops its apps and removes its data, versions, tests and runs for good. It is only in that menu, and not while the sandbox is generating: sw, the Python SDK and the REST API cannot delete a sandbox.

What is refused, and why

RequestRefused whenStatusWhy
Generate into itThe sandbox is not blank, or it is generating. 409 Generating replaces the apps' data. Make a new sandbox to generate one.
ConnectTest mode.409Open a twin run of it, or switch it to edit mode.
An actionTest mode.409Actions change the sandbox. Switch it to edit mode first.
RenameIt is generating.409Generating sets its name (see Fill a sandbox). Rename it when that ends.
CopyIt is generating, or failed.409 There is nothing whole to copy yet.
Switch modeIt is writing tests, re-checking them, or runs of its tests are going.409They read the data as it is. Finish or cancel them first.
Switch modeIt is generating, or generating failed. 409The sandbox is not ready.

A refusal answers JSON with error and message; sw prints the message and exits with 1.