@stateset/sandbox-cli 3.3.1 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/CHANGELOG.md +140 -0
  2. package/README.md +467 -41
  3. package/dist/client.d.ts +131 -1
  4. package/dist/client.d.ts.map +1 -1
  5. package/dist/client.js +21 -0
  6. package/dist/client.js.map +1 -1
  7. package/dist/commands/billing.js +36 -2
  8. package/dist/commands/billing.js.map +1 -1
  9. package/dist/commands/config.js +8 -1
  10. package/dist/commands/config.js.map +1 -1
  11. package/dist/commands/run.d.ts.map +1 -1
  12. package/dist/commands/run.js +48 -15
  13. package/dist/commands/run.js.map +1 -1
  14. package/dist/commands/sandbox.d.ts.map +1 -1
  15. package/dist/commands/sandbox.js +222 -17
  16. package/dist/commands/sandbox.js.map +1 -1
  17. package/dist/commands/swarm.d.ts +18 -0
  18. package/dist/commands/swarm.d.ts.map +1 -0
  19. package/dist/commands/swarm.js +379 -0
  20. package/dist/commands/swarm.js.map +1 -0
  21. package/dist/commands/terminal.d.ts +3 -1
  22. package/dist/commands/terminal.d.ts.map +1 -1
  23. package/dist/commands/terminal.js +58 -1
  24. package/dist/commands/terminal.js.map +1 -1
  25. package/dist/commands/workbench.d.ts +138 -0
  26. package/dist/commands/workbench.d.ts.map +1 -0
  27. package/dist/commands/workbench.js +531 -0
  28. package/dist/commands/workbench.js.map +1 -0
  29. package/dist/index.js +5 -1
  30. package/dist/index.js.map +1 -1
  31. package/dist/utils/ephemeral-storage.d.ts +12 -0
  32. package/dist/utils/ephemeral-storage.d.ts.map +1 -0
  33. package/dist/utils/ephemeral-storage.js +39 -0
  34. package/dist/utils/ephemeral-storage.js.map +1 -0
  35. package/dist/utils/swarm-dispatcher.d.ts +50 -0
  36. package/dist/utils/swarm-dispatcher.d.ts.map +1 -0
  37. package/dist/utils/swarm-dispatcher.js +137 -0
  38. package/dist/utils/swarm-dispatcher.js.map +1 -0
  39. package/dist/utils/swarm-plan.d.ts +69 -0
  40. package/dist/utils/swarm-plan.d.ts.map +1 -0
  41. package/dist/utils/swarm-plan.js +321 -0
  42. package/dist/utils/swarm-plan.js.map +1 -0
  43. package/dist/utils/template-create.d.ts +36 -0
  44. package/dist/utils/template-create.d.ts.map +1 -0
  45. package/dist/utils/template-create.js +118 -0
  46. package/dist/utils/template-create.js.map +1 -0
  47. package/dist/workbench/actions.d.ts +1 -1
  48. package/dist/workbench/actions.d.ts.map +1 -1
  49. package/dist/workbench/actions.js +1 -0
  50. package/dist/workbench/actions.js.map +1 -1
  51. package/dist/workbench/agents.d.ts +96 -0
  52. package/dist/workbench/agents.d.ts.map +1 -0
  53. package/dist/workbench/agents.js +370 -0
  54. package/dist/workbench/agents.js.map +1 -0
  55. package/dist/workbench/commands.d.ts.map +1 -1
  56. package/dist/workbench/commands.js +7 -1
  57. package/dist/workbench/commands.js.map +1 -1
  58. package/dist/workbench/model.d.ts +5 -1
  59. package/dist/workbench/model.d.ts.map +1 -1
  60. package/dist/workbench/model.js +15 -2
  61. package/dist/workbench/model.js.map +1 -1
  62. package/dist/workbench/terminal.d.ts +1 -1
  63. package/dist/workbench/terminal.d.ts.map +1 -1
  64. package/dist/workbench/terminal.js +108 -78
  65. package/dist/workbench/terminal.js.map +1 -1
  66. package/package.json +15 -7
package/README.md CHANGED
@@ -1,16 +1,29 @@
1
1
  # @stateset/sandbox-cli
2
2
 
3
- Command-line interface for managing [StateSet Sandbox](https://github.com/stateset/stateset-sandbox) environments — create sandboxes, manage checkpoints, upload artifacts, orchestrate agent sessions, and more.
4
-
5
- ## Installation
3
+ Create, drive and script StateSet sandboxes and agent sessions from the terminal.
6
4
 
7
5
  ```bash
8
6
  npm install -g @stateset/sandbox-cli
9
7
  ```
10
8
 
11
- Requires Node.js 20.19+ (20.x line) or 22.12+.
9
+ Your first sandbox, running Python:
12
10
 
13
- ## Quick Start
11
+ ```bash
12
+ export STATESET_API_KEY=sk_live_your_api_key
13
+ stateset sandbox create --timeout 600 # prints the Sandbox ID
14
+ stateset sandbox exec <sandbox-id> -- python3 -c 'print(6 * 7)'
15
+ stateset sandbox stop <sandbox-id>
16
+ ```
17
+
18
+ Or in one shot, which creates the sandbox, runs the command and stops it: `stateset run -- python3 -c 'print(6 * 7)'`.
19
+
20
+ **[Docs](https://sandbox.stateset.app/docs)** · **[Pricing](https://sandbox.stateset.app/pricing)** · **[Integrations](https://github.com/stateset/stateset-sandbox/tree/master/integrations)** (LangChain, CrewAI, OpenAI, AI SDK and more)
21
+
22
+ ## Installation
23
+
24
+ Requires Node.js 20.19+ (20.x line) or 22.12+. An API key comes from the
25
+ [dashboard](https://sandbox.stateset.app/dashboard); instead of `STATESET_API_KEY`
26
+ you can store it once:
14
27
 
15
28
  ```bash
16
29
  # Interactive setup — prompts for API key, URL, and defaults
@@ -19,41 +32,7 @@ stateset config setup
19
32
  # Or configure manually
20
33
  stateset config set-key sk_live_your_api_key
21
34
  stateset config set-url https://api.sandbox.stateset.app
22
-
23
- # Create a sandbox and run a command
24
- stateset sandbox create --timeout 600
25
- stateset sandbox exec <sandbox-id> -- echo hello world
26
- ```
27
-
28
- For CLI agents and scripts, use `stateset --json sandbox exec <sandbox-id> --
29
- <command>`. Confirmed command failures return the remote exit code in both JSON
30
- and the shell status. Unknown outcomes return a nonzero shell status, even if a
31
- transport supplied a nominal zero. Inspect the execution receipt before
32
- repeating uncertain work. Command and REPL execution use the SDK's conservative
33
- retry policy; the CLI does not add another execution retry loop.
34
-
35
- CLI/TUI sandbox creation uses a separate 210-second client wait by default so
36
- cold node provisioning can finish without changing ordinary read deadlines.
37
- `sandbox create` and `run` accept `--startup-timeout <seconds>` (1–600).
38
- For example, `stateset --json run --timeout 300 --startup-timeout 210 -- python3
39
- -c 'print(sum(x*x for x in range(1,11)))'` runs a one-shot interpreter task.
40
- `--timeout` still controls sandbox lifetime, including startup; increasing the
41
- client wait does not extend that lifetime. An explicitly configured client
42
- transport deadline remains in effect unless a startup override is supplied.
43
-
44
- Sandbox stop, fork, promote, pause, resume and lifetime extension, plus workspace
45
- write, mkdir, rm, mv and cp, also use the SDK retry policy without another CLI
46
- retry loop. After a lost response, inspect sandbox state, new sandbox listings
47
- or workspace files before repeating: the first operation may already have applied.
48
- Failure messages give inspection guidance and preserve authentication exit codes
49
- and request IDs. Stop requires a positive acknowledgement; it reports that
50
- acknowledgement rather than observed backend termination. Pause/resume validate
51
- the returned sandbox ID and distinguish transitional from completed states before
52
- printing human or JSON output. Read-only commands retain their existing retries.
53
-
54
- `stateset repl exec <sandbox-id> <session-id> '<code>' --json` also returns a
55
- nonzero shell status for failed or timed-out cells. A lost execution or session
56
- creation response must be inspected before resubmission.
35
+ ```
57
36
 
58
37
  ## Configuration
59
38
 
@@ -112,7 +91,7 @@ Startup equivalents are `--runtime-image`, `--inference`, `--inference-secret`
112
91
  and `--inference-limit`. The default gateway cap is 20000 output tokens/hour;
113
92
  in-flight calls can overshoot. Local Docker retains its existing `--image`
114
93
  setting and rejects hosted gateway options.
115
- Use `/` to search sandbox IDs, statuses or creating Herdr panes, Enter for
94
+ Use `/` to search sandbox IDs, statuses, agent names or creating Herdr panes, Enter for
116
95
  details, and `?` for keyboard help. PageUp/PageDown and Home/End navigate the
117
96
  filtered list; details and help wrap and scroll inside narrow panes.
118
97
  Press `a` for session activity across all sandboxes. Start with
@@ -121,6 +100,61 @@ search also accepts pasted IDs.
121
100
  The list shows allocations and a live expiry countdown. Press `o` for status
122
101
  counts and running allocation totals, or `t` to sort by ID, expiry, status or
123
102
  newest. Start with `--sort expiry` to prioritize upcoming deadlines.
103
+
104
+ To see what each sandbox is for, name the directories that hold your agent
105
+ records: `stateset tui --agents ./fleets --agents ~/desk`, or set
106
+ `STATESET_AGENT_DIRS` to a PATH-style list (`:` between entries, `;` on
107
+ Windows). Each directory and its immediate subdirectories are checked for
108
+ `fleet-state.json` (written by `examples/claude-agent/fleet.mjs`) and
109
+ `workbench.json` (`{ "benches": [{ "name", "sandbox_id", "terminal_id",
110
+ "error"?, "stopped"? }] }`). Only these local files are read, on every refresh:
111
+ each is stat'ed and parsed again only when it has changed, and nothing is
112
+ requested from the API for them.
113
+
114
+ Workbenches started with [`stateset workbench up`](#stateset-workbench) need
115
+ no flag. When the dashboard is started inside a git repository, the directory
116
+ where that repository's workbenches are recorded (`.git/stateset-workbench`,
117
+ shared by its worktrees) is scanned as well, from the moment it exists, in
118
+ addition to the `--agents` and `STATESET_AGENT_DIRS` directories. Every
119
+ `<name>.json` in it that is a workbench record adds one agent per sandbox:
120
+ named by its label (`feat-1`), grouped under the workbench's name, with the
121
+ phase `interactive` (ready), `creating`, `failed` (with the error) or
122
+ `stopped` (after `workbench down`, or when `down` found that the sandbox was
123
+ never created). A failed member stays `failed` after `down`. These records are
124
+ read under the same rules as the others: parsed only when changed, never when
125
+ larger than 8 MiB, and at most 200 files. Anything else in that directory is
126
+ ignored without a note. The workbenches of another repository are not found
127
+ this way; start the dashboard in that repository. A `workbench.json` in an
128
+ `--agents` directory may hold either format.
129
+
130
+ - The list gains `AGENT` and `PHASE` columns once a listed sandbox has a
131
+ record. They share the ID column's room, so IDs are shortened and long names
132
+ cut; panes under 46 columns keep the ID alone. `+N` counts further agents in
133
+ the same sandbox. Search matches agent, phase and fleet names.
134
+ - Enter adds the fleet or workbench name, task name, the first four lines of
135
+ the objective, phase, branch, pull request URL, cost, any error, and the
136
+ record's path to the sandbox details.
137
+ - `v` (also in the F2 menu) lists agents instead of sandboxes: every fleet
138
+ member and bench, grouped by fleet or workbench, with phase, branch and pull
139
+ request, and the sandbox's status or `not listed` when it is gone. `v` or
140
+ Esc returns.
141
+ - `*` marks likely duplicates and the title shows `dup:N`: two agents both
142
+ still working whose names are equal, or one contained in the other, after
143
+ lower-casing and dropping punctuation, spaces and common words (`the`, `a`,
144
+ `of`, `to`, ...). "Fix the Login-Redirect!" matches "fix_login redirect"
145
+ and "login redirect". Containment is plain, so a very short name such as
146
+ "ui" also matches "build"; treat the mark as a prompt to look. Details and
147
+ the agents view name the other agent of each pair. "Still working" comes
148
+ from the record alone: fleet phases `planned`, `prepared`, `dispatched` and
149
+ `dispatch_unknown`, benches without `stopped` or `error`, and workbench
150
+ members that are `interactive` or `creating`; finished agents are never
151
+ flagged. A stale record of an agent that died without
152
+ updating its file can therefore still be flagged; the agents view shows
153
+ whether its sandbox is still listed.
154
+ - A `fleet-state.json` or `workbench.json` that is unreadable, malformed or
155
+ not in a known format is skipped, and one dimmed line above the selection
156
+ summary counts the skipped files and names the first two. Control characters and terminal escape sequences are
157
+ removed from every value read from these files before it is drawn.
124
158
  Press F2 or `:` for a searchable action menu with availability explanations.
125
159
  It also works from sandbox details and keeps its original target selected.
126
160
  Press `c` for connection diagnostics and full refresh errors. Delayed reads
@@ -423,6 +457,10 @@ Manage sandbox environments.
423
457
  ```bash
424
458
  stateset sandbox create [options] # Create a new sandbox
425
459
  stateset sandbox list # List all sandboxes
460
+ stateset sandbox summary # Counts by state, running resources, today's spend
461
+ # (--json prints the API's body unchanged)
462
+ stateset sandbox health <id> # Resource use vs limits, warnings, restarts, why it ended, history
463
+ # (--json prints the API's body unchanged)
426
464
  stateset sandbox get <id> # Get sandbox details
427
465
  stateset sandbox exec <id> <command> # Execute a command
428
466
  stateset sandbox stop <id> # Stop a sandbox
@@ -441,6 +479,120 @@ stateset sandbox ls-files <id> # List directory contents
441
479
  | `-m, --memory <memory>` | Memory limit | `--memory 1Gi` |
442
480
  | `-i, --isolation <level>` | Isolation level | `--isolation gvisor` |
443
481
  | `-e, --env <KEY=VALUE>` | Environment variables (repeatable) | `-e FOO=bar -e BAZ=qux` |
482
+ | `--ephemeral-storage <size>` | Ephemeral storage (the writable layer, `/tmp`, a non-persistent `/workspace`) as whole Gi from `1Gi` to `50Gi` | `--ephemeral-storage 10Gi` |
483
+ | `--strict` | Fail instead of creating a sandbox with less ephemeral storage than asked for | `--strict` |
484
+ | `--template <id>` | Built-in template to create from, with its files and setup commands if it has any | `--template python-data-science` |
485
+ | `--startup-timeout <seconds>` | How long to wait for the create to answer (1-600, default 210; a template with setup gets 300 more unless this is set) | `--startup-timeout 600` |
486
+ | `--json` | Print the created sandbox as JSON | `--json` |
487
+
488
+ **Ephemeral storage.** `--ephemeral-storage <size>` is sent as `ephemeral_storage`.
489
+ Anything but whole Gi from `1Gi` to `50Gi` is refused before a request is sent.
490
+ The API grants the size up to the lower of the platform's limit (20Gi unless the
491
+ deployment sets another) and the plan's, and says what it granted:
492
+
493
+ ```bash
494
+ stateset sandbox create --ephemeral-storage 10Gi
495
+ stateset sandbox create --ephemeral-storage 30Gi --strict
496
+ stateset --json sandbox create --ephemeral-storage 30Gi | jq '.ephemeralStorageGrant'
497
+ ```
498
+
499
+ - The output has a line `Ephemeral storage:` with the granted size. `--json` (and
500
+ `--format yaml`) has the API's `ephemeral_storage_grant` under
501
+ `ephemeralStorageGrant`: `{ "requested": "10Gi", "granted": "10Gi" }`, with
502
+ `reason` (`platform_limit` or `plan_limit`) and `limit` when less was granted;
503
+ `--format csv` has it as JSON in one cell. Without a size asked for there is no
504
+ such line and no such key.
505
+ - **When less was granted than asked for, the sandbox is created all the same** and
506
+ the command exits 0, with a warning on stderr in every output format:
507
+ `Ephemeral storage: 20Gi granted, 30Gi requested (platform limit 20Gi). Use
508
+ --strict to fail instead.` (`plan limit` when it is the plan's).
509
+ - `--strict` is sent as `strict: true`. The API then refuses such a create with a
510
+ 400 and creates nothing; the CLI prints the API's message, for example
511
+ `ephemeral_storage 30Gi cannot be granted: the platform's limit is 20Gi. Ask
512
+ for 20Gi or less, or leave out strict to be given 20Gi.`, and exits 1.
513
+ - A template can declare a size of its own. It is granted and reported the same
514
+ way, and `--strict` holds for it too.
515
+
516
+ **Templates.** `--template <id>` creates the sandbox from any built-in template;
517
+ `stateset template list` shows the ids and `stateset template describe <id>` what
518
+ each one sets. `stateset run` takes the same flag.
519
+
520
+ ```bash
521
+ stateset sandbox create --template claude-code
522
+ stateset sandbox create --template claude-code --timeout 900 --cpus 1 -e FOO=bar
523
+ stateset --json sandbox create --template claude-code | jq -r '.id, .template'
524
+ stateset run --template claude-code -- claude --version
525
+ stateset sandbox create --template python-data-science # writes files, runs pip install
526
+ stateset run --template node-basic -- node index.js
527
+ ```
528
+
529
+ - The id is sent as typed in the `template` field of `POST /sandbox/create`.
530
+ - The template supplies the image and the defaults for CPUs, memory, timeout and
531
+ env. `--cpus`, `--memory` and `--timeout` replace the template's values, `-e`
532
+ entries are merged over its env, and `run --image` replaces its image.
533
+ - **Templates with setup.** Eight built-in templates write files or run setup
534
+ commands (the `Files` and `Setup Commands` sections of `template describe`):
535
+ `python-basic`, `node-basic`, `go-basic`, `rust-basic`, `node-express-api`,
536
+ `python-data-science`, `python-llm` and `devops-tools`. `POST /sandbox/create`
537
+ refuses them with a 400 that names `POST /sandbox/create-from-template`, and
538
+ the CLI then sends the same options to that route. `GET /templates` does not
539
+ say which kind a template is, so the CLI learns it from that 400, which creates
540
+ nothing; any other error is reported as it is, and neither request is sent a
541
+ second time by the CLI.
542
+ - Setup runs inside the create request. The spinner says so (`Creating sandbox
543
+ and running the setup of template <id> ...; waiting up to 510s...`): the API
544
+ allows one setup command 300 seconds, so the default 210 second startup wait
545
+ becomes 510. A `--startup-timeout` you give is used as the whole wait.
546
+ - The template route has no field for `--isolation`, `--desktop-os` (other than
547
+ `linux`), `--credential` or `--ephemeral-storage`. With a template that has
548
+ setup they are refused by name before that route is called, and no sandbox is
549
+ created. `--timeout`, `--cpus`, `--memory`, `-e`, `--durable`,
550
+ `--resource-class`, `--strict`, the egress and budget flags and `run --image`
551
+ are sent. The ephemeral storage that route grants (the size the template
552
+ declares) is printed like any other.
553
+ - **A setup step that fails does not undo the create.** The API keeps the
554
+ sandbox, running and billed, and lists the failed steps. `sandbox create`
555
+ prints the sandbox, then on stderr each step in the API's words (`Setup command
556
+ exited 1: pip install ...`, `Template files were not written: ...`) and that the
557
+ sandbox was kept, and exits 1; `--json` carries the steps as `warnings`.
558
+ `run` does not run the command: it stops the sandbox (or keeps it with
559
+ `--keep`), says which, and exits 1.
560
+ - If the template route times out, loses its connection or answers 5xx, the CLI
561
+ does not send it again: the sandbox may exist with its setup still running, so
562
+ look at `stateset sandbox list` before creating another.
563
+ - Without `--timeout`, a create with `--template` sends no timeout, so the
564
+ template's applies (3600 seconds for `claude-code`) and not the profile's default
565
+ timeout. Without `--template` the profile default is sent as before.
566
+ - A refusal is shown in the API's words. An unknown id is `Template "<id>" not
567
+ found`.
568
+ - The create response does not name the template, so the `Template:` line and the
569
+ `template` key of `--json` repeat the id that was sent. `run --json` carries the
570
+ same `template` key. Both are absent when no template was asked for.
571
+
572
+ ### `stateset terminal` and `stateset ssh`
573
+
574
+ A terminal is a real shell (or any command) on a pseudo-terminal in the
575
+ sandbox. It keeps running when you detach or lose the connection. See
576
+ [docs/TERMINAL_SESSIONS.md](../docs/TERMINAL_SESSIONS.md).
577
+
578
+ ```bash
579
+ stateset ssh <id> # start a shell and attach
580
+ stateset ssh <id> -c "npm test" # run one command and exit
581
+ stateset ssh <id> --line-mode # old behaviour: each line is its own command
582
+
583
+ stateset terminal create <id> [command...] # start a terminal and attach (alias: stateset term)
584
+ stateset terminal create <id> -d --name build # start it detached and print its id
585
+ stateset terminal ls <id>
586
+ stateset terminal attach <id> <terminal-id> # --from-start replays all retained output
587
+ stateset terminal screen <id> <terminal-id> # print what it is displaying; --scrollback <n>, --json
588
+ stateset terminal search <id> <terminal-id> <text> # --case-sensitive, --limit <n>, --json
589
+ stateset terminal record <id> <terminal-id> -o session.cast # asciicast v2; --idle-time-limit <seconds>
590
+ stateset terminal kill <id> <terminal-id>
591
+ ```
592
+
593
+ While attached, `Ctrl-]` detaches and leaves the terminal running. `screen`,
594
+ `search` and `record` need no attachment and work on a terminal someone else
595
+ (or an agent) is using.
444
596
 
445
597
  ### `stateset checkpoint`
446
598
 
@@ -601,6 +753,210 @@ omit command contents and environment values.
601
753
  | `--cpus <cpus>` | CPU allocation (default: 2) |
602
754
  | `--memory <memory>` | Memory allocation (default: 4Gi) |
603
755
 
756
+ ### `stateset swarm`
757
+
758
+ Create, see, watch and cancel swarms: one goal split into tasks with dependencies, as the
759
+ service keeps it (`/api/v1/swarms`, "Swarms" in [docs/API_REFERENCE.md](../docs/API_REFERENCE.md)).
760
+ The service stores the plan and what a coordinator reports about each task; it starts
761
+ and stops no sandbox, and neither do these commands: `create` stores a plan and runs
762
+ none of its tasks.
763
+
764
+ ```bash
765
+ stateset swarm create --plan plan.json # Check the plan file, then store it as a swarm
766
+ stateset swarm create --plan plan.json --name "Swarm API" # Under this name
767
+ stateset swarm create --plan plan.json --json # The stored swarm with its tasks, as the API answers
768
+ stateset --dry-run swarm create --plan plan.json # Check the plan; send nothing
769
+ stateset swarm list # Newest first: id, name, status, created
770
+ stateset swarm list --status running --limit 50
771
+ stateset swarm list --json # { "swarms": [...], "next_cursor": null }
772
+ stateset swarm list --dispatcher ~/swarm-home # And one line: what that swarm dispatcher is doing, and why it waits
773
+ stateset swarm get <id> # Header line, then one row per task
774
+ stateset swarm get <id> --json # The swarm with its tasks, as the API answers
775
+ stateset swarm watch <id> # `get`, drawn again every 5 seconds until the swarm has ended
776
+ stateset swarm watch <id> --interval 30 # Look every 30 seconds
777
+ stateset swarm watch <id> --dispatcher ~/swarm-home # With the dispatcher's line under the table, read at every look
778
+ stateset swarm cancel <id> # Cancel the swarm and its unfinished tasks
779
+ stateset swarm report <id> # Per task outcome, attempts and cost, then the totals (--json: the report as the API answers)
780
+ stateset --dry-run swarm cancel <id> # Say what would be sent; send nothing
781
+ ```
782
+
783
+ | Flag | Description |
784
+ |------|-------------|
785
+ | `--plan <file>` | `create`: the plan file, JSON (required) |
786
+ | `--name <name>` | `create`: the swarm's name (default: the plan's `name`, else the file's name without `.json`) |
787
+ | `--status <status>` | `list`: only `planned`, `running`, `completed`, `failed` or `cancelled` swarms |
788
+ | `--limit <n>` | `list`: the most swarms to show (default: 25). Above 100 the CLI reads further pages |
789
+ | `-i, --interval <seconds>` | `watch`: seconds between two looks, a positive integer (default: 5) |
790
+ | `--dispatcher <home-dir>` | `list`, `get`, `watch`: also say in one line what the swarm dispatcher with this home directory is doing, and why it takes nothing if it waits. No default, and no environment variable |
791
+ | `--json` | `create`, `list`, `get`, `cancel`: print JSON instead of a table or a line; the global `--json` and `--format json` do the same |
792
+
793
+ `swarm create` reads a plan file, checks it and stores it as a swarm (`POST /swarms`). A
794
+ plan file is what [`examples/claude-agent/swarm-plan.mjs`](../examples/claude-agent/swarm-plan.mjs)
795
+ writes, or the same written by hand:
796
+
797
+ ```json
798
+ {
799
+ "goal": "Give the controller a place to keep a swarm.",
800
+ "repository": { "path": "/home/me/app", "base": "4f2c1d9" },
801
+ "defaults": { "timeout_seconds": 3600 },
802
+ "sandbox": { "template": "claude-code", "memory": "4Gi", "cpus": "2" },
803
+ "tasks": [
804
+ { "id": "schema", "name": "Schema", "objective": "Add the migration." },
805
+ { "id": "routes", "name": "Routes", "objective": "Add the routes.", "depends_on": ["schema"] }
806
+ ]
807
+ }
808
+ ```
809
+
810
+ The plan is checked against the API's limits before anything is sent:
811
+
812
+ | Part of the plan | What it must be |
813
+ |------------------|-----------------|
814
+ | The file | At most 4 MB of JSON: an object with its list of tasks in `tasks` |
815
+ | The swarm's name | 1 to 128 characters, on one line and without control characters |
816
+ | `goal` | A string of 1 to 16000 characters, without a NUL character |
817
+ | `repository`, `defaults` | Each a JSON object of at most 16384 characters as JSON, without a NUL character, or left out |
818
+ | `tasks` | 1 to 50 tasks, each an object |
819
+ | A task's `id` | Kebab-case (lowercase letters and digits joined by single hyphens), at most 64 characters, and the id of no other task |
820
+ | A task's `name` | As the swarm's name |
821
+ | A task's `objective` | As `goal` |
822
+ | A task's `depends_on` | A list of ids of other tasks of the plan, or left out; the dependencies form no cycle |
823
+
824
+ The lengths of the name, the goal, a task's name and an objective are counted without
825
+ the spaces around them. A plan with problems is refused with exit status 1 and nothing is
826
+ sent, under `--dry-run` too. Stderr names the file, then has one line per problem, which
827
+ names the task it is about (at most 20 problems; a last line says how many more there
828
+ are):
829
+
830
+ ```text
831
+ Plan file "plan.json" has 2 problems:
832
+ - Task 1: id "Bad_Id" is not kebab-case (lowercase letters and digits joined by single hyphens, at most 64 characters).
833
+ - Task "routes": depends_on names "nowhere", which is not the id of a task in this plan.
834
+ ```
835
+
836
+ A file that does not exist, cannot be read, is over 4 MB or is not JSON is refused the
837
+ same way, in one line.
838
+
839
+ What is sent is the body of `POST /swarms`: the name, the goal, `repository` and
840
+ `defaults` as the plan has them, and of every task its `id` as `key`, its `name`, its
841
+ `objective` and its `depends_on`, each dependency once. `sandbox`, `union`, `max_local`,
842
+ a task's `files` and anything else the API has no field for are left out: the service
843
+ stores a plan, not how to run it. The swarm's name is `--name`, else the plan's own
844
+ `name`, else the name of the file without `.json` (`plans/run-7.json` is stored as
845
+ `run-7`).
846
+
847
+ ```text
848
+ ✔ Swarm "run-7" created: 0b9f6c1e-2f0a-4a51-9d3e-6a1f5a0c7e11
849
+ Follow it with: stateset swarm watch 0b9f6c1e-2f0a-4a51-9d3e-6a1f5a0c7e11
850
+ No sandbox was started: the service keeps the plan; a coordinator runs the tasks and reports them.
851
+ ```
852
+
853
+ With `--json` the stored swarm is printed as the API answers it, with its id and its
854
+ tasks (`ready` when a task depends on nothing, `waiting` otherwise), and nothing else.
855
+ `stateset --dry-run swarm create --plan <file>` checks the plan, prints the name, the
856
+ number of tasks and the file, and sends nothing. `create` starts no sandbox and runs no
857
+ task: the swarm is `planned` until a coordinator reports a task, which the CLI does not
858
+ do, and it counts among the organization's unfinished swarms until it has ended or is
859
+ cancelled. `stateset swarm watch <id>` follows it from there. Creating is not
860
+ idempotent: the request is sent once, and running the command again stores a second
861
+ swarm.
862
+
863
+ `swarm list` prints `No swarms found` for an empty answer. When there are more swarms
864
+ than `--limit`, the table is followed by a line saying so, and `--json` carries the
865
+ API's `next_cursor` (`null` when the list is complete). A swarm in a list has no tasks.
866
+
867
+ `swarm get` prints the name, the status and the goal on one line, then a table of the
868
+ tasks: key, phase, branch, cost and blocked by.
869
+
870
+ ```text
871
+ Swarm API (running): Give the controller a place to keep a swarm.
872
+ ╔════════╤══════════╤══════════════╤════════╤════════════╗
873
+ ║ Key │ Phase │ Branch │ Cost │ Blocked by ║
874
+ ╟────────┼──────────┼──────────────┼────────┼────────────╢
875
+ ║ schema │ accepted │ swarm/schema │ $0.95 │ - ║
876
+ ╟────────┼──────────┼──────────────┼────────┼────────────╢
877
+ ║ routes │ failed │ swarm/routes │ $12.34 │ - ║
878
+ ╟────────┼──────────┼──────────────┼────────┼────────────╢
879
+ ║ docs │ blocked │ - │ $0.00 │ routes ║
880
+ ╚════════╧══════════╧══════════════╧════════╧════════════╝
881
+ ```
882
+
883
+ The API stores a task's cost in cents (`cost_cents`); the table prints dollars, and
884
+ `--json` keeps the cents. The header shows the first 240 characters of the goal on one
885
+ line, with control characters replaced by `?`; `--json` has the goal whole.
886
+
887
+ `swarm watch` follows one swarm: it prints what `swarm get` prints, looks again every
888
+ `--interval` seconds, and ends on the first look that finds the swarm `completed`,
889
+ `failed` or `cancelled`, which may be the first one. That look is printed too, followed
890
+ by one line. Only a failed swarm is an error:
891
+
892
+ | The swarm | Last line | Exit status |
893
+ |-----------|-----------|-------------|
894
+ | `completed` | `Swarm "<name>" completed` | 0 |
895
+ | `cancelled` | `Swarm "<name>" was cancelled` | 0 |
896
+ | `failed` | On stderr: `Swarm "<name>" failed: <keys of the failed tasks>` | 1 |
897
+
898
+ In a terminal the screen is cleared before each look is drawn, and a line under the
899
+ table says how often the swarm is looked at, that Ctrl+C stops the watch, and when the
900
+ swarm was last read. When the output is not a terminal (a pipe, a CI log), nothing is
901
+ cleared, that line is left out, and the swarm is printed again only when what is printed
902
+ has changed: the log holds one table per change, not one per look. `watch` only reads,
903
+ and it has no `--json`: a script reads `swarm get <id> --json`. An error on any look,
904
+ the first or a later one, ends the watch as it ends `swarm get`.
905
+
906
+ `--dispatcher <home-dir>` adds one line about a swarm dispatcher, the local process that
907
+ runs swarms from a backlog
908
+ ([docs/guides/SWARM_DISPATCHER_GUIDE.md](../docs/guides/SWARM_DISPATCHER_GUIDE.md)). A
909
+ dispatcher reports nothing to the service, so no swarm says why one has stopped taking
910
+ items. What it does is in `status.json` in its home directory, which it rewrites after
911
+ every change and at every look. The CLI reads that file, and no other, on this machine:
912
+ the directory has to be readable here, and the process the file names is looked for
913
+ among this machine's. The line is one of four, with `<home>` the directory made absolute:
914
+
915
+ | The status file | The line |
916
+ |-----------------|----------|
917
+ | A dispatcher is running, its process is alive, and it says why it takes nothing | `Dispatcher <home>: waiting since <since> (<limit>): <reason>` |
918
+ | A dispatcher is running, its process is alive, and it waits for nothing | `Dispatcher <home>: <state>.`, e.g. `working` |
919
+ | No dispatcher is running, or the process the file names is gone | `Dispatcher <home>: not running (status.json says "<state>", written <updated_at>).` |
920
+ | The file is missing, cannot be read, is not JSON or is not a dispatcher's status | `Dispatcher <home>: no status could be read (<why>).`, e.g. `no status.json in that directory` |
921
+
922
+ ```text
923
+ Dispatcher /home/me/swarm-home: waiting since 2026-11-13T02:40:00.000Z (max-unmerged): 2 items in done/ have shared branches that are not merged (swarm/0001-api, swarm/0002-docs), and --max-unmerged is 2: no item is taken until 1 of them is merged, or its branch or its directory in done/ is removed.
924
+ ```
925
+
926
+ `<reason>` is the dispatcher's own sentence, printed whole: it says what releases the
927
+ limit, a time or the branches to merge by name. `<limit>` is the dispatcher's name for
928
+ what holds it (`daily-budget`, `max-items-per-day`, `max-unmerged`, `model`, `paused`,
929
+ `empty-backlog`); `since <since>` and the brackets are left out for a file that has
930
+ none. Text from the file is printed on one line, with control characters replaced by
931
+ `?`. `list` prints the line last, `get` after the task table, and `watch` under the table
932
+ at every look, reading the file anew: when the output is not a terminal, a reason that
933
+ changed or cleared is a change, and the swarm is printed once more with the new line. A
934
+ status that cannot be read changes neither the swarms that are printed nor the exit
935
+ status. With `--json`, or the global `--json` or `--format json`, the output is what it
936
+ is without the option: the line is left out, and `status.json` is the data to read. The
937
+ dashboard's Swarms page does not show the line, because it reads swarms from the
938
+ service, which is not sent the dispatcher's status.
939
+
940
+ `swarm cancel` marks the swarm and its unfinished tasks `cancelled` in the service and
941
+ prints the cancelled swarm with `--json`. It stops no sandbox: a coordinator still
942
+ running the swarm goes on until it is stopped where it runs. Cancelling a swarm that is
943
+ already cancelled succeeds. It does not ask for confirmation.
944
+
945
+ Errors are one line on stderr with exit status 1 (for a plan with problems, one more per
946
+ problem), and the request is not repeated:
947
+
948
+ | Answer | Line |
949
+ |--------|------|
950
+ | A plan with problems on `create`: nothing is sent | `Plan file "<file>" has <n> problems:`, then one line per problem |
951
+ | `429` on `create` (the organization holds its limit of unfinished swarms) | The API's message, e.g. `Maximum unfinished swarms per organization (20) exceeded`, then how to get under it: `stateset swarm cancel <id>` or waiting for a swarm to end; `stateset swarm list --status running` and `--status planned` show the unfinished ones |
952
+ | `400` on `create` (the service refuses a plan the check let through) | The API's message, which names the field |
953
+ | `404` on `get`, `watch` or `cancel` | `Swarm "<id>" not found` |
954
+ | `409` on `cancel` (the swarm is completed or failed) | The API's message, e.g. `Swarm is already completed; there is nothing to cancel.` |
955
+ | `404` on `list` or `create` | `This API has no swarm routes (a deployment without a database, or an older controller).` |
956
+
957
+ Any other error (a `--status` or an id the API refuses, an expired login) is reported
958
+ as for the other commands.
959
+
604
960
  ### `stateset tunnel`
605
961
 
606
962
  Expose sandbox services via tunnels.
@@ -670,6 +1026,52 @@ requires a positive acknowledgement and reports acceptance, which does not
670
1026
  establish that every existing forwarded connection has ended. `--public` remains
671
1027
  a compatibility flag; the current controller still requires token authentication.
672
1028
 
1029
+ ### `stateset workbench`
1030
+
1031
+ Several sandboxes, each with this repository at `/workspace/repo` and Claude
1032
+ Code running in a terminal session there. Run it from inside a git repository, or
1033
+ name one with `--repo <path>` (accepted by all four subcommands).
1034
+
1035
+ ```bash
1036
+ stateset workbench up feat 3 # 3 claude-code sandboxes, HEAD uploaded, Claude Code started
1037
+ stateset workbench up fix 2 --base v1.4 --hours 4 --shell # from tag v1.4, 4-hour lifetime, a shell instead
1038
+ stateset workbench open feat # attach: one Herdr tab per sandbox, or print the commands
1039
+ stateset workbench pull feat -o patches # patches/feat-1.patch ... (changes since the base commit)
1040
+ stateset workbench down feat # stop the sandboxes this workbench created
1041
+ ```
1042
+
1043
+ **Up options:** `--repo <path>` (the repository to upload; default the current
1044
+ directory), `--base <rev>` (the commit the sandboxes start from; default `HEAD`),
1045
+ `--hours <n>` (sandbox lifetime, 1 to 24; replaces `--timeout`), `--shell` (start a
1046
+ shell in each terminal instead of Claude Code; nothing is installed),
1047
+ `--template <template>` (default `claude-code`), `--timeout <seconds>`
1048
+ (default 7200), `--cpus`, `--memory`, `--inference-secret <name>` (the secret holding
1049
+ the Anthropic credentials Claude Code uses), `--claude-code-version <x.y.z>` (installed
1050
+ only when the image has no `claude`). Every subcommand accepts `--json`.
1051
+
1052
+ - **up** uploads the committed `HEAD`, or `--base` (uncommitted changes are not
1053
+ sent; it warns), as a `git archive`, checked by hash in the sandbox and made a
1054
+ one-commit repository holding every file of that commit, including committed
1055
+ files that `.gitignore` matches. A sandbox that cannot be prepared is reported
1056
+ with the reason and the others still start; the command then exits 1. A workbench
1057
+ that is up cannot be started again until `down`; nor can one whose creates were
1058
+ never confirmed (an interrupted `up`), until `down` has looked for their sandboxes.
1059
+ - **open** inside Herdr (`HERDR_ENV=1`) opens one tab per sandbox, each running
1060
+ `stateset terminal attach`; elsewhere it prints those commands. Ctrl-] detaches
1061
+ and leaves Claude Code running.
1062
+ - **pull** captures commits, uncommitted edits and new files that `.gitignore`
1063
+ does not exclude, without touching the agent's git index or writing anything
1064
+ under the sandbox repository's `.git`. Each download is
1065
+ checked against the size and hash the sandbox reported. Apply a patch on the
1066
+ base commit with `git apply <file>`. A sandbox with no changes writes no file.
1067
+ - **down** stops only sandboxes recorded as created by this workbench, including
1068
+ one whose create response was lost (found by the session ID it was given).
1069
+
1070
+ State lives in `.git/stateset-workbench/<name>.json`, so it is never committed and is
1071
+ shared by the repository's worktrees. `stateset tui` started in the repository reads
1072
+ these files and shows each sandbox's label and phase in its `AGENT` and `PHASE`
1073
+ columns and its agents view (`v`), without `--agents`.
1074
+
673
1075
  ### `stateset pool`
674
1076
 
675
1077
  Monitor the warm pod pool.
@@ -737,9 +1139,33 @@ Most commands support `--json` for machine-readable output, useful for scripting
737
1139
  ```bash
738
1140
  stateset sandbox list --json | jq '.[0].id'
739
1141
  stateset pool stats --json
1142
+ stateset swarm get <id> --json | jq '.tasks[] | {key, phase, cost_cents}'
740
1143
  stateset grade --json
741
1144
  ```
742
1145
 
1146
+ For CLI agents and scripts:
1147
+
1148
+ - `stateset --json sandbox exec <sandbox-id> -- <command>` and
1149
+ `stateset repl exec <sandbox-id> <session-id> '<code>' --json` return the
1150
+ remote exit code in both the JSON and the shell status. Failed or timed-out
1151
+ cells, and unknown outcomes (even with a nominal zero from a transport), give
1152
+ a nonzero status: inspect the execution receipt before repeating the work.
1153
+ - Sandbox creation waits 210 seconds by default so cold nodes can be provisioned;
1154
+ `sandbox create` and `run` take `--startup-timeout <seconds>` (1–600), e.g.
1155
+ `stateset --json run --timeout 300 --startup-timeout 210 -- python3 -c 'print(sum(x*x for x in range(1,11)))'`.
1156
+ `--timeout` is the sandbox lifetime (startup included) and a longer client wait
1157
+ does not extend it; a configured client transport deadline stays in effect
1158
+ unless a startup override is given.
1159
+ - Exec, REPL, sandbox stop, fork, promote, pause, resume and extend, and the
1160
+ workspace write, mkdir, rm, mv and cp commands use the SDK's conservative retry
1161
+ policy with no CLI retry loop on top. After a lost response (including a lost
1162
+ REPL session creation), inspect sandbox state, listings or workspace files
1163
+ before repeating: the first request may have applied. Errors keep
1164
+ authentication exit codes and request IDs. Stop reports the API's
1165
+ acknowledgement, not observed termination; pause/resume check the returned
1166
+ sandbox ID and tell transitional from completed states. Read-only commands
1167
+ keep their retries.
1168
+
743
1169
  ## Development
744
1170
 
745
1171
  For prepared resident AI workers, `sandboxctl delegate --stdin` keeps a