@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.
- package/CHANGELOG.md +140 -0
- package/README.md +467 -41
- package/dist/client.d.ts +131 -1
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +21 -0
- package/dist/client.js.map +1 -1
- package/dist/commands/billing.js +36 -2
- package/dist/commands/billing.js.map +1 -1
- package/dist/commands/config.js +8 -1
- package/dist/commands/config.js.map +1 -1
- package/dist/commands/run.d.ts.map +1 -1
- package/dist/commands/run.js +48 -15
- package/dist/commands/run.js.map +1 -1
- package/dist/commands/sandbox.d.ts.map +1 -1
- package/dist/commands/sandbox.js +222 -17
- package/dist/commands/sandbox.js.map +1 -1
- package/dist/commands/swarm.d.ts +18 -0
- package/dist/commands/swarm.d.ts.map +1 -0
- package/dist/commands/swarm.js +379 -0
- package/dist/commands/swarm.js.map +1 -0
- package/dist/commands/terminal.d.ts +3 -1
- package/dist/commands/terminal.d.ts.map +1 -1
- package/dist/commands/terminal.js +58 -1
- package/dist/commands/terminal.js.map +1 -1
- package/dist/commands/workbench.d.ts +138 -0
- package/dist/commands/workbench.d.ts.map +1 -0
- package/dist/commands/workbench.js +531 -0
- package/dist/commands/workbench.js.map +1 -0
- package/dist/index.js +5 -1
- package/dist/index.js.map +1 -1
- package/dist/utils/ephemeral-storage.d.ts +12 -0
- package/dist/utils/ephemeral-storage.d.ts.map +1 -0
- package/dist/utils/ephemeral-storage.js +39 -0
- package/dist/utils/ephemeral-storage.js.map +1 -0
- package/dist/utils/swarm-dispatcher.d.ts +50 -0
- package/dist/utils/swarm-dispatcher.d.ts.map +1 -0
- package/dist/utils/swarm-dispatcher.js +137 -0
- package/dist/utils/swarm-dispatcher.js.map +1 -0
- package/dist/utils/swarm-plan.d.ts +69 -0
- package/dist/utils/swarm-plan.d.ts.map +1 -0
- package/dist/utils/swarm-plan.js +321 -0
- package/dist/utils/swarm-plan.js.map +1 -0
- package/dist/utils/template-create.d.ts +36 -0
- package/dist/utils/template-create.d.ts.map +1 -0
- package/dist/utils/template-create.js +118 -0
- package/dist/utils/template-create.js.map +1 -0
- package/dist/workbench/actions.d.ts +1 -1
- package/dist/workbench/actions.d.ts.map +1 -1
- package/dist/workbench/actions.js +1 -0
- package/dist/workbench/actions.js.map +1 -1
- package/dist/workbench/agents.d.ts +96 -0
- package/dist/workbench/agents.d.ts.map +1 -0
- package/dist/workbench/agents.js +370 -0
- package/dist/workbench/agents.js.map +1 -0
- package/dist/workbench/commands.d.ts.map +1 -1
- package/dist/workbench/commands.js +7 -1
- package/dist/workbench/commands.js.map +1 -1
- package/dist/workbench/model.d.ts +5 -1
- package/dist/workbench/model.d.ts.map +1 -1
- package/dist/workbench/model.js +15 -2
- package/dist/workbench/model.js.map +1 -1
- package/dist/workbench/terminal.d.ts +1 -1
- package/dist/workbench/terminal.d.ts.map +1 -1
- package/dist/workbench/terminal.js +108 -78
- package/dist/workbench/terminal.js.map +1 -1
- package/package.json +15 -7
package/README.md
CHANGED
|
@@ -1,16 +1,29 @@
|
|
|
1
1
|
# @stateset/sandbox-cli
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
9
|
+
Your first sandbox, running Python:
|
|
12
10
|
|
|
13
|
-
|
|
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
|