# Quickstart

Make a blank sandbox, put one message in it through Slack's own API, write a task, and run your agent against fresh copies until it passes. About fifteen minutes.

**Using Claude Code, Codex or Cursor?** After step 3, run `sw setup` and ask your coding agent to "Set up StateWeave for my agent": it knows every step on this page. See [From your coding agent](/content/docs/coding-agents/index.html).

## 1. Install the client

The `stateweave-sdk` package installs the `sw` command and the `stateweave` Python module. It needs Python 3.10 or later and has no dependencies beyond the standard library.

ShellCopy

```
pip install stateweave-sdk
sw --version
```

## 2. Create an API key

Open your workspace (see [Get access](/content/docs/index.html#get-access)) and click the key icon at the bottom of the left rail: **Connect your agent**. Its first line is your workspace's address. Name a key (for example after the machine it will live on) and click **Create key**. The key starts with `sw_` and is shown once, so copy it now.

## 3. Sign in

ShellCopy

```
sw login --url https://acme.app.stateweave.net
```

`sw login` asks for the key without echoing it, checks it with your workspace, then keeps the address and key in `~/.config/stateweave/config.json`, readable only by you. In CI, set `STATEWEAVE_URL` and `STATEWEAVE_API_KEY` instead.

## 4. Make a blank sandbox

In your workspace, click **+** beside Sandboxes, name it, pick Slack, and click **Make sandbox**. Or from a shell:

ShellCopy

```
sw sandbox new "Acme support" --apps slack
```

OutputCopy

```
p-7d21c4
```

The sandbox starts in **edit mode**, holding only Slack's workspace, its owner and the owner's token. What you do in it now becomes its data. Your workspace's [Starter](/content/docs/sandboxes/index.html#the-starter-sandbox) sandbox would do too: it holds every app StateWeave had when your workspace was made, blank, and doesn't count against your plan.

## 5. Fill it through Slack's API

`connect` starts the sandbox's apps and gives each one's address and the owner's token. Write with the client you already use: here, Slack's own `slack_sdk` (`pip install slack_sdk`).

fill.pyCopy

```
import stateweave
from slack_sdk import WebClient

twins = stateweave.Client().connect("p-7d21c4")
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")
print(general["id"])
```

OutputCopy

```
C0A1B2C3D4E
```

Note the channel's id: every copy of this sandbox will have the same one, so your checks can name it. See [Fill a sandbox](/content/docs/fill/index.html) for other apps, other people's tokens and filling from a prompt.

## 6. Keep it as a version

ShellCopy

```
sw sandbox mode p-7d21c4 test
```

OutputCopy

```
p-7d21c4 is in test mode; version 1
```

From now on, every run starts from fresh copies of version 1. Nothing a run does reaches the sandbox.

## 7. Write a task

A task is a folder: what your agent is asked, and checks that decide whether it did it, through Slack's own API and the requests your agent sent.

LayoutCopy

```
kickoff/
├── instruction.md
├── task.toml
└── tests/checks.json
```

instruction.mdCopy

```
Post exactly 'Kickoff at 10' in #general.
```

task.tomlCopy

```
[task]
description = "Announce the kickoff"

[metadata]
stateweave_sandbox = "p-7d21c4"
stateweave_kind = "action"
```

tests/checks.jsonCopy

```
[
  {"name": "posted once", "calls": {"app": "slack", "http_method": "POST", "path": "/api/chat.postMessage"},
   "expect": [{"op": "count_eq", "value": 1}, {"path": "request.text", "op": "equals", "value": "Kickoff at 10"}]},
  {"name": "it is in #general", "app": "slack",
   "request": {"method": "GET", "path": "/api/conversations.history", "query": {"channel": "C0A1B2C3D4E"}},
   "expect": [{"path": "messages[*].text", "op": "contains", "value": "Kickoff at 10"}]}
]
```

Check that the task can tell a run that did nothing from one that worked. Nothing is kept:

ShellCopy

```
sw task import ./kickoff --check
```

OutputCopy

```
  ✓ Doing nothing fails
      with nothing done, judged failed:
      - failed: posted once: the records: wanted 1, found 0; request.text: nothing there to compare with 'Kickoff at 10'
      - failed: it is in #general: messages[*].text: no value contains 'Kickoff at 10' (found 'Standup moves to 9:30 from Monday', '<@U0B7K2M4Q1R> has joined the channel')
Proven; nothing kept (--check). Import it without --check to keep it.
```

See [Tasks](/content/docs/tasks/index.html) for every kind of check.

## 8. Run your agent and judge it

Open fresh copies of the sandbox, run your agent on them, then judge them with the task's own checks:

try_kickoff.pyCopy

```
import json
import stateweave

client = stateweave.Client()
prompt = open("kickoff/instruction.md").read()
checks = json.load(open("kickoff/tests/checks.json"))

with client.open_twins("p-7d21c4") as twins:
    my_agent(prompt, twins.apps)          # your agent: twins.apps holds each app's address and tokens
    result = twins.check(checks)
    print("passed" if result["passed"] else "failed")
    for r in result["results"]:
        print(" ", "ok " if r["ok"] else "no ", r["name"], "-", r["detail"])
```

The copies stop when the block ends. Fix your agent and run it again: each `open_twins` starts from version 1. See [Run your agent](/content/docs/run/index.html) for running a command, reading the calls your agent made and resetting the copies between attempts.

## 9. Upload it (optional)

Uploaded, the task is a test in your workspace: each run of it is graded, kept with every call, and comparable across versions of your agent.

ShellCopy

```
sw task import ./kickoff
sw run t-4f2a9c --agent my-agent@0.1 -- python my_agent.py
```

`sw run` starts a run, runs your command with the request and the apps in environment variables, grades it when the command exits, and prints the result with a link to the run's page. See [Upload a task](/content/docs/upload/index.html).
