Get started

### Core concepts

The words this documentation uses, what each one is, and how they fit together.

### Workspace

Your workspace is your own StateWeave, at its own address such as https://acme.app.stateweave.net . Everyone in it sees the same sandboxes, tests and runs; its owner invites the rest ( Work with teammates ). API keys are made there and open it by key, from sw , the Python SDK or the REST API.

### App

An app is a twin of a real service (Slack, Gmail, Google Calendar, Sheets and Drive, Salesforce, Shopify, Zendesk, WhatsApp, Microsoft Teams, Stripe, HubSpot, GitHub): the same API, the same request and response shapes, errors, paging and limits, at its own address. Your agent talks to it with the client it already uses. Some apps also serve the vendor's MCP server. See Apps and credentials .

### Sandbox

A sandbox is a set of apps and the data they hold. Its id starts with p- . A new one is blank: each app holds its account, its owner and the owner's token. You fill it yourself, or have StateWeave generate a made-up company into it from a prompt. Every workspace starts with one called Starter , which its plan doesn't count: it holds every app StateWeave has when the workspace is made. See Sandboxes and Fill a sandbox .

| Mode | What it means |
| --- | --- |
| Edit | Its apps are open for writing. Whatever is done in them, through their APIs, StateWeave's actions or their web clients, becomes the sandbox's data. |
| Test | Switching to test keeps what the apps hold as a version . Every run starts from fresh copies of the latest version, and nothing a run does reaches the sandbox. |

### Task

A task is what your agent is asked, plus how a run of it is judged: a folder with instruction.md , task.toml and checks ( tests/checks.json ). The layout is Harbor's, so the same folder works elsewhere. See Tasks .

A task is judged only through what you can see yourself: each app's public API after the agent worked (and, if a check asks, before it), the agent's answer, and the requests the agent sent. Nothing about how StateWeave stores the apps' data is part of a task.

| Kind | The agent | Judged by |
| --- | --- | --- |
| answer | finds something out and answers | its answer, in the shape the task's answer format shows |
| action | changes things in the apps | what the apps hold afterwards, and what it sent |

### Test

A test is a task you uploaded, kept in your workspace; uploading is the only way to add one. A test's id starts with t- ; sw calls tests tasks ( sw task ). A test is proven before it is kept: an agent that does nothing must fail it. See Upload a task .

When a new version changes a test's apps, the test is proven again on the new data before it runs again: it needs a re-check until then.

### Run

A run is your agent's attempt, on fresh copies of a sandbox's apps. Its id starts with r- .

A twin run has no test: fresh copies to develop against, judged by you (for example with a task's checks), reset between attempts, stopped when you are done or after an hour.

A test run is a run of a test: graded when your harness finishes it, and kept with every call on its page. It has 30 minutes unless you set another limit.

| Status | Meaning |
| --- | --- |
| queued | asked for on a run's page with Run again, waiting for a worker |
| starting | its apps are being started |
| running | its apps are up, your agent is working |
| passed | graded and passed |
| failed | graded and failed; reasons says why |
| timed\_out | not finished within its time limit |
| cancelled | given up by your harness or on its page; not graded |
| interrupted | the workspace restarted while it ran |
| error | the test's own judging failed, not your agent; not counted against it |
| ended | a twin run, stopped or out of time |

### Persona

Every run acts for someone, the persona: in a sandbox you filled, its owner unless a task names another person; in a generated company, one of its people. The run's credentials are theirs: the agent reads their inbox, posts as them in Slack and owns their records. Some apps also hand over the company's bot or app tokens, as a real deployment would have them. A run never hands over a colleague's mailbox or a refresh token, and no client secret except inside WhatsApp's app access token, which Meta writes as &lt;app id&gt;\|&lt;app secret&gt; , and Microsoft Teams' bot credential, &lt;app id&gt;:&lt;client secret&gt; , which a bot built on the Teams SDK signs in with.

### Faults

A test can inject faults the real services show now and then: an outage, a 401 for a valid token, a page cut off mid-response. Your agent then has to cope the way it would in production. A task names its faults in task.toml . See Faults .

### Agent label and worker

Each run carries the label of the agent that ran it, such as support-bot@0.4 , and optional meta (the model, the prompt version, a commit). The Runs board shows labels side by side, test by test. A worker ( sw worker ) is your harness waiting for runs someone queued with Run again on a run's page. See Run your agent .

### Plan and sandbox hours

A workspace's plan is measured in sandbox hours : a minute counts when something calls one of a sandbox's apps in it (its API, its MCP server or its web page), once for the sandbox however many of its apps were called. A run counts the same way, from the calls its agent made. Twins nobody calls go to sleep and count nothing. Free has 5 hours and 3 new sandboxes a month (the Starter is not one of them); Basic has 200 hours, then $0.50 an hour up to a monthly cap. The Plan page (the gauge at the bottom of the left rail) shows what is left. Basic and Custom are applied for on the Pricing page.

### Names at a glance

| Thing | Id | sw | Python | REST |
| --- | --- | --- | --- | --- |
| Sandbox | p-… | sw sandbox | sandboxes() | /api/v1/sandboxes |
| Test | t-… | sw task | tests() | /api/v1/tests |
| Run | r-… | sw run | start() , open\_twins() | /api/v1/runs |
| API key | k-… | sw login | Client(api\_key=…) | Authorization: Bearer sw\_… |

Sandboxes were called environments, and before that scenarios and projects. The old names still work in sw env , in Python ( environment= , project= ) and on the /api/v1/environments and /api/v1/projects paths. sw task ls , sw run , sw tests and sw start still take a sandbox's id as --env .

[Work with teammates](https://stateweave.net/docs/team)

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

[Sandboxes](https://stateweave.net/docs/sandboxes)

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

[Tasks](https://stateweave.net/docs/tasks)

[Upload a task](https://stateweave.net/docs/upload)

[Faults](https://stateweave.net/docs/faults)

[Run your agent](https://stateweave.net/docs/run)

[Pricing](https://stateweave.net/pricing)