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.

| App | A blank sandbox has |
| --- | --- |
| Slack | The workspace, named after the sandbox. The owner as its primary owner. One app with its bot. \#general and \#random , with no messages. |
| Gmail | The owner's mailbox, empty. An OAuth client. |
| Google Calendar | The owner's account and calendars, with no events. An OAuth client and an API key. |
| Google Sheets | The owner's account, with no spreadsheets. An OAuth client. |
| Google Drive | The owner's account, with no files. An OAuth client. |
| Salesforce | The org, named after the sandbox. The owner as its only user. A connected app. No records. |
| Shopify | The store, named after the sandbox. The owner as its account owner. One location and an app. No products, customers or orders. |
| Zendesk | The 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. |
| WhatsApp | A 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 Teams | The 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. |
| Stripe | The 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. |
| HubSpot | The 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. |
| GitHub | The 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"\}\}'

| sw | Python | REST | Description |
| --- | --- | --- | --- |
| NAME | name | name | Required. What to call the sandbox, up to 80 characters. |
| --apps | apps | apps | Required. Any of slack , gmail , google\_calendar , google\_sheets , google\_drive , salesforce , shopify , zendesk , whatsapp , microsoft\_teams , stripe , hubspot , github . |
| --owner-name | owner\_name | owner.name | The owner's name. |
| --owner-email | owner\_email | owner.email | The owner's email address. |
| --time-zone | time\_zone | time\_zone | An 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 &lt;name&gt; 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

| Request | Refused when | Status | Why |
| --- | --- | --- | --- |
| Generate into it | The sandbox is not blank, or it is generating. | 409 | Generating replaces the apps' data. Make a new sandbox to generate one. |
| Connect | Test mode. | 409 | Open a twin run of it, or switch it to edit mode. |
| An action | Test mode. | 409 | Actions change the sandbox. Switch it to edit mode first. |
| Rename | It is generating. | 409 | Generating sets its name (see Fill a sandbox ). Rename it when that ends. |
| Copy | It is generating, or failed. | 409 | There is nothing whole to copy yet. |
| Switch mode | It is writing tests, re-checking them, or runs of its tests are going. | 409 | They read the data as it is. Finish or cancel them first. |
| Switch mode | It is generating, or generating failed. | 409 | The sandbox is not ready. |

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

[Fill a sandbox](https://stateweave.net/docs/fill#from-a-prompt-while-it-is-blank)

[Fill a sandbox](https://stateweave.net/docs/fill)