Your sandbox

### Fill a sandbox

A sandbox in edit mode keeps whatever is done to its apps. Write the data through the apps' own APIs, from a script or your coding agent; use StateWeave's actions for what no API can do; or, while it is blank, have a made-up company generated from a prompt.

### Connect

Connecting starts the sandbox's apps and gives you, for each app, its address, its endpoints, the credentials of the person you act as (the owner, in a blank sandbox) and its MCP server. Where an app has an app or bot token, you get that too; refresh tokens stay out, and client secrets too, except inside WhatsApp's app access token (as Meta writes it) and Microsoft Teams' bot credential. Everything also comes as STATEWEAVE\_\* variables.

sw

sandbox connect p-7d21c4

\# JSON

sw

sandbox connect p-7d21c4

--env

\# export lines for a shell

eval

"$(sw sandbox connect p-7d21c4 --env)"

twins = client.

connect

(

"p-7d21c4"

) slack = twins\[

"apps"

\]\[

"slack"

\]

print

(slack\[

"endpoints"

\]\[

"web\_api"

\], slack\[

"credentials"

\]\[

"user:owner"

\])

curl

-s

-X

POST

"$STATEWEAVE\_URL/api/v1/sandboxes/p-7d21c4/connect"

\\

-H

"Authorization: Bearer $STATEWEAVE\_API\_KEY"

Response (shortened)

\{

"sandbox"

:

"p-7d21c4"

,

"mode"

:

"edit"

,

"persona"

:

"owner"

,

"apps"

: \{

"slack"

: \{

"base\_url"

:

"https://…"

,

"endpoints"

: \{

"web\_api"

:

"https://…/api/"

,

"mcp"

:

"https://…/mcp"

\},

"credentials"

: \{

"bot:Sandbox App"

:

"xoxb-…"

,

"app:Sandbox App"

:

"xapp-…"

,

"user:owner"

:

"xoxp-…"

\},

"mcp"

: \{

"url"

:

"https://…/mcp"

,

"headers"

: \{

"Authorization"

:

"Bearer xoxp-…"

\}\} \},

"zendesk"

: \{

"base\_url"

:

"https://…"

,

"endpoints"

: \{

"rest\_api"

:

"https://…/api/v2/"

, …\},

"credentials"

: \{

"user:owner"

:

"…"

\},

"mcp"

:

null

\} \},

"env"

: \{

"STATEWEAVE\_SLACK\_URL"

:

"https://…"

,

"STATEWEAVE\_SLACK\_MCP\_URL"

:

"https://…/mcp"

,

"STATEWEAVE\_SLACK\_BOT\_TOKEN"

:

"xoxb-…"

,

"STATEWEAVE\_SLACK\_APP\_TOKEN"

:

"xapp-…"

,

"STATEWEAVE\_SLACK\_USER\_TOKEN"

:

"xoxp-…"

,

"STATEWEAVE\_ZENDESK\_URL"

:

"https://…"

,

"STATEWEAVE\_ZENDESK\_USER\_TOKEN"

:

"…"

\} \}

The variables are named as for a twin run (see Open a twin run ): STATEWEAVE\_&lt;APP&gt;\_URL , STATEWEAVE\_&lt;APP&gt;\_MCP\_URL and one STATEWEAVE\_&lt;APP&gt;\_&lt;KIND&gt;\_TOKEN per credential. …\_USER\_TOKEN is that person's. Connecting is only for edit mode: in test mode it is refused, and a twin run is the way in.

### Write through the apps' own APIs

Write the data with the same clients your agent uses: post messages, create tickets, insert records. The sandbox keeps whatever the apps keep. Apps and credentials shows each app's endpoints and how to point its client at them.

Python

import

requests

from

slack\_sdk

import

WebClient slack = twins\[

"apps"

\]\[

"slack"

\] web =

WebClient

(token=slack\[

"credentials"

\]\[

"user:owner"

\], base\_url=slack\[

"endpoints"

\]\[

"web\_api"

\]) general =

next

(c

for

c

in

web.

conversations\_list

()\[

"channels"

\]

if

c\[

"name"

\] ==

"general"

) web.

chat\_postMessage

(channel=general\[

"id"

\], text=

"Standup moves to 9:30 from Monday"

) zendesk = twins\[

"apps"

\]\[

"zendesk"

\] requests.

post

(zendesk\[

"endpoints"

\]\[

"rest\_api"

\] \+

"tickets.json"

, headers=\{

"Authorization"

:

"Bearer "

\+ zendesk\[

"credentials"

\]\[

"user:owner"

\]\}, json=\{

"ticket"

: \{

"subject"

:

"Printer on fire"

,

"comment"

: \{

"body"

:

"Help"

\}\}\})

Write anything you could write to the real service: channels, messages, mail, events, records, tickets, orders. Apps and credentials lists each app's endpoints and Client libraries shows how to point each vendor's client at them.

### Act as other people

A blank sandbox has one person, its owner. To have messages, mail or tickets come from others, add them with an action where the app has one, and use the token it answers to act as them through the same API:

Python

import

stateweave

from

slack\_sdk

import

WebClient client = stateweave.

Client

() slack = client.

connect

(

"p-7d21c4"

)\[

"apps"

\]\[

"slack"

\] api = slack\[

"endpoints"

\]\[

"web\_api"

\] added = client.

act

(

"p-7d21c4"

,

"slack"

,

"add\_person"

, handle=

"grace"

, name=

"Grace Hopper"

, email=

"grace@acme.example"

) grace =

WebClient

(token=added\[

"results"

\]\[

1

\]\[

"token"

\], base\_url=api)

\# Grace's own user token

general =

next

(c

for

c

in

grace.

conversations\_list

()\[

"channels"

\]

if

c\[

"name"

\] ==

"general"

) grace.

chat\_postMessage

(channel=general\[

"id"

\], text=

"Can someone look at ticket 42?"

) owner =

next

(u\[

"id"

\]

for

u

in

grace.

users\_list

()\[

"members"

\]

if

u\[

"name"

\] ==

"owner"

) dm = grace.

conversations\_open

(users=owner)\[

"channel"

\]\[

"id"

\]

\# Grace's DM with the owner

grace.

chat\_postMessage

(channel=dm, text=

"Got a minute?"

)

A new Slack person joins \#general ; to post in another channel they join it first ( conversations.join ), as in Slack. For someone already there, the token action gives a token (Slack by handle, Google Calendar and Zendesk by email, Salesforce by username). In Zendesk and Salesforce, create the user through the API first, then ask for their token.

### What no API can do: StateWeave's actions

Some things in a real account never go through its API: someone joins the workspace, a customer writes on WhatsApp, Meta reviews a template. For those, StateWeave has actions of its own.

Not the apps' APIs. Actions are calls to your workspace, by API key, and they exist only for what happens outside the real APIs. They work only in edit mode. The agent you test never gets your API key, so it cannot reach them. Each action is recorded in the app like any other change, so it is part of the next version.

| App | Action | Params | What it does |
| --- | --- | --- | --- |
| Slack | add\_person | handle , name , email | Add a person to the workspace. Someone joins (no Web API method adds people): their user, DMs, \#general , a team\_join event, and a user token labelled user:&lt;handle&gt; to act as them. |
| Slack | token | handle | A token to act as a person: a user token in that person's name, to post, react and so on as them through the Web API. |
| Google Calendar | add\_person | email , name , time\_zone ? | Add a Google account: another person's account, with its primary calendar, and a token to act as them (their events, invitations they send). time\_zone defaults to UTC . |
| Google Calendar | token | email , scopes ? | A token to act as a person: an access token for an account in the sandbox. scopes is a list of short scope names, by default calendar . |
| Salesforce | token | username | A token to act as a user: a REST access token for a User of the org. Insert the User through the REST API first. The org's connected app only grants client credentials, as the owner. |
| Zendesk | token | email | A token to act as a user: an OAuth token (read write) for a user of the account, such as an end user you created through the API, to act as them. |
| WhatsApp | customer\_message | from , text , name ?, reply\_to ?, phone\_number ? | A customer writes: a text message from a customer's WhatsApp to the business number. It is stored, opens the 24-hour window and sends the messages webhook. from is the customer's number in digits, reply\_to the wamid they reply to. |
| WhatsApp | message\_status | message\_id , status | A message is delivered or read: the customer's phone reports on a message the business sent. status is delivered , read , played or failed . |
| WhatsApp | template\_review | template\_id , status , reason ? | Meta reviews a template: approve, reject or pause a message template ( APPROVED , REJECTED , PAUSED , …), as Meta's review would. |
| WhatsApp | test\_recipients | add ?, remove ?, phone\_number ? | Test number recipients: the numbers the test number may send to, as the App Dashboard edits them. Empty at first, at most 5. |
| Microsoft Teams | add\_person | email , name , job\_title ? | Add a person to the tenant. Someone joins the organization, as an admin adds them in the Microsoft 365 admin center (Graph's POST /users is not there): a user in no team or chat yet, and tokens labelled user:&lt;name&gt; (Graph) and mcp:&lt;name&gt; (MCP) to act as them. email is in a domain the tenant uses: its onmicrosoft.com one or the owner's. Then add them to a team with POST /teams/\{id\}/members , or start a chat with them with POST /chats . |
| Microsoft Teams | token | email | Tokens to act as a person: a Graph token and an MCP token in that person's name, with the scopes the sandbox's own tokens hold, to post, reply and so on as them. |

Gmail, Google Sheets, Google Drive, Shopify, Stripe, HubSpot and GitHub have no actions: fill them through their APIs. GitHub's API cannot add people or organizations, so in a blank sandbox the owner is GitHub's only person, with no organization. A company generated from a prompt has its GitHub organization, with its people and their teams.

A ? marks an optional param. phone\_number is the business number's id; leave it out when the sandbox has only one.

sw

sandbox actions p-7d21c4

sw

sandbox act p-7d21c4 slack add\_person

--handle

grace

--name

"Grace Hopper"

--email

grace@acme.example

sw

sandbox act p-7d21c4 whatsapp test\_recipients

--add

'\["15550101001"\]'

print

(client.

actions

(

"p-7d21c4"

))

\# \{app: \[\{"name", "title", "about", "params"\}\]\}

added = client.

act

(

"p-7d21c4"

,

"slack"

,

"add\_person"

, handle=

"grace"

, name=

"Grace Hopper"

, email=

"grace@acme.example"

) grace = added\[

"results"

\]\[

1

\]\[

"token"

\]

\# post as Grace through the Web API

curl

-s

"$STATEWEAVE\_URL/api/v1/sandboxes/p-7d21c4/actions"

-H

"Authorization: Bearer $STATEWEAVE\_API\_KEY"

curl

-s

-X

POST

"$STATEWEAVE\_URL/api/v1/sandboxes/p-7d21c4/apps/slack/actions/add\_person"

\\

-H

"Authorization: Bearer $STATEWEAVE\_API\_KEY"

-H

"Content-Type: application/json"

\\

-d

'\{"handle": "grace", "name": "Grace Hopper", "email": "grace@acme.example"\}'

An action answers \{"action", "app", "results"\} , results being the app's answer to each step. With sw sandbox act , each param is a --name value pair ( \_ may be written - ), and a list param takes a JSON list. A missing or unknown param is refused with 400 and every problem listed. When the app refuses a step, for example a sixth test recipient, the action answers 400 with the app's reason.

### From a prompt, while it is blank

Instead of filling it yourself, you can have StateWeave generate a made-up company into a sandbox: its people, customers, weeks of history and the data each app holds, from a description. This works only while the sandbox is blank: no version, nothing generated, and no change in edit mode since it was made. The generated data replaces the blank apps, so nothing is lost.

The sandbox shows the company's name while it generates and goes back to its own name when that ends. The owner you named is not one of the company's people, so no app has the handle owner any more: connections and runs act as one of the people in the company. persona in a connection's answer is their handle, and their token is labelled user:&lt;handle&gt; , such as user:maya.chen .

sw

sandbox generate p-7d21c4

--describe

"A 40-person robotics parts supplier. Support is behind after a bad batch of servo motors."

import

time client.

generate\_into

(

"p-7d21c4"

,

"A 40-person robotics parts supplier. Support is behind after a bad batch of "

"servo motors."

)

while

(sb := client.

sandbox

(

"p-7d21c4"

))\[

"status"

\] ==

"generating"

: time.

sleep

(

5

)

curl

-s

-X

POST

"$STATEWEAVE\_URL/api/v1/sandboxes/p-7d21c4/generate"

\\

-H

"Authorization: Bearer $STATEWEAVE\_API\_KEY"

-H

"Content-Type: application/json"

\\

-d

'\{"description": "A 40-person robotics parts supplier. …", "options": \{"people": 40\}\}'

It takes the same options as generating a new sandbox ( --company , --people , --weeks , --templates ) and runs in the background: the REST call answers 202 , and sw sandbox generate follows it until it is done.

### Write a good description

Say what the company does, how big it is, what is going on right now, and what your agent will be asked to do. The situation is what makes the data useful: a backlog after an outage, a launch next week, a quarter-end push. Every app's data follows from it, so the tickets, orders, deals and messages fit together.

### Options

sw sandbox generate and generate\_into() take the same options, except --apps : a blank sandbox already has its apps.

| sw | Python | Description |
| --- | --- | --- |
| --apps | apps | Required. Any of slack , gmail , google\_calendar , google\_sheets , google\_drive , salesforce , shopify , zendesk , whatsapp , microsoft\_teams , stripe , hubspot , github . |
| --describe | description | Required. The company and what the agent will be tested on. |
| --company | company | The company's name. Made up when not given. |
| --people | people | How many employees, 2 to 5,000 (your workspace may allow fewer). |
| --weeks | weeks | Weeks of history, 1 to 104. |
| --templates | content="templates" | Write the text from built-in templates instead of with Claude: much faster, plainer text. |

### While it generates

Generation runs in the background and takes several minutes with Claude writing the text, depending on the apps and the company's size: about seven for ten people, three apps and two weeks of history. It first designs the company and plans the story, then fills every app from that one plan, and checks the result. The sandbox's page shows each step as it goes.

| Status | Meaning |
| --- | --- |
| generating | still going |
| ready | every app is ready |
| partial | some apps are ready and some failed; error says why |
| failed | no app is ready |

To follow it from Python, read the sandbox until its status is no longer generating :

Python

import

time

while

(sandbox := client.

sandbox

(made\[

"id"

\]))\[

"status"

\] ==

"generating"

: time.

sleep

(

5

)

for

app, held

in

sandbox\[

"envs"

\].

items

():

print

(app, held\[

"counts"

\])

### A new sandbox with a company, in one step

From a shell or from Python. The new sandbox takes the company's name. ( env is the command's name from when sandboxes were called environments.)

sw

env new

--apps

slack,zendesk,shopify \\

--describe

"A 40-person online kitchenware store. Support is behind after a carrier lost a week of parcels, and the agent helps the support lead triage tickets and refunds."

import

stateweave client = stateweave.

Client

() made = client.

create\_environment

(

"A 40-person online kitchenware store. Support is behind after a carrier lost a week of parcels, "

"and the agent helps the support lead triage tickets and refunds."

, apps=\[

"slack"

,

"zendesk"

,

"shopify"

\], )

print

(made\[

"id"

\], made\[

"status"

\])

\# generating

sw env new prints the sandbox's id at once, then follows the generation step by step and prints what each app holds when it's done. Pass --no-wait to return right after the id.

### When it holds what you need

Switch the sandbox to test mode: what it holds becomes a version, and every run starts from fresh copies of it. See Test mode and versions .

[Open a twin run](https://stateweave.net/docs/api#open-a-twin-run)

[Apps and credentials](https://stateweave.net/docs/apps)

[Client libraries](https://stateweave.net/docs/libraries)

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

[Test mode and versions](https://stateweave.net/docs/sandboxes#test-mode-and-versions)