@stateset/sandbox-cli 1.0.5 → 3.3.1
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 +35 -0
- package/LICENSE +22 -0
- package/README.md +805 -0
- package/dist/client.d.ts +761 -10
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +684 -12
- package/dist/client.js.map +1 -1
- package/dist/commands/alias.d.ts +5 -0
- package/dist/commands/alias.d.ts.map +1 -0
- package/dist/commands/alias.js +131 -0
- package/dist/commands/alias.js.map +1 -0
- package/dist/commands/api-key.d.ts +3 -0
- package/dist/commands/api-key.d.ts.map +1 -0
- package/dist/commands/api-key.js +119 -0
- package/dist/commands/api-key.js.map +1 -0
- package/dist/commands/artifact.d.ts.map +1 -1
- package/dist/commands/artifact.js +105 -46
- package/dist/commands/artifact.js.map +1 -1
- package/dist/commands/audit.d.ts +3 -0
- package/dist/commands/audit.d.ts.map +1 -0
- package/dist/commands/audit.js +191 -0
- package/dist/commands/audit.js.map +1 -0
- package/dist/commands/auth.d.ts +3 -0
- package/dist/commands/auth.d.ts.map +1 -0
- package/dist/commands/auth.js +126 -0
- package/dist/commands/auth.js.map +1 -0
- package/dist/commands/benchmark.d.ts +3 -0
- package/dist/commands/benchmark.d.ts.map +1 -0
- package/dist/commands/benchmark.js +166 -0
- package/dist/commands/benchmark.js.map +1 -0
- package/dist/commands/billing.d.ts +3 -0
- package/dist/commands/billing.d.ts.map +1 -0
- package/dist/commands/billing.js +139 -0
- package/dist/commands/billing.js.map +1 -0
- package/dist/commands/checkpoint.d.ts.map +1 -1
- package/dist/commands/checkpoint.js +105 -48
- package/dist/commands/checkpoint.js.map +1 -1
- package/dist/commands/completion.d.ts +3 -0
- package/dist/commands/completion.d.ts.map +1 -0
- package/dist/commands/completion.js +134 -0
- package/dist/commands/completion.js.map +1 -0
- package/dist/commands/computer-use.d.ts +3 -0
- package/dist/commands/computer-use.d.ts.map +1 -0
- package/dist/commands/computer-use.js +124 -0
- package/dist/commands/computer-use.js.map +1 -0
- package/dist/commands/config.d.ts.map +1 -1
- package/dist/commands/config.js +2 -1
- package/dist/commands/config.js.map +1 -1
- package/dist/commands/context.d.ts +3 -0
- package/dist/commands/context.d.ts.map +1 -0
- package/dist/commands/context.js +98 -0
- package/dist/commands/context.js.map +1 -0
- package/dist/commands/cp.d.ts +3 -0
- package/dist/commands/cp.d.ts.map +1 -0
- package/dist/commands/cp.js +165 -0
- package/dist/commands/cp.js.map +1 -0
- package/dist/commands/deploy.d.ts +3 -0
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +68 -20
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/diff.d.ts +3 -0
- package/dist/commands/diff.d.ts.map +1 -0
- package/dist/commands/diff.js +186 -0
- package/dist/commands/diff.js.map +1 -0
- package/dist/commands/doctor.d.ts +30 -0
- package/dist/commands/doctor.d.ts.map +1 -1
- package/dist/commands/doctor.js +177 -207
- package/dist/commands/doctor.js.map +1 -1
- package/dist/commands/egress.d.ts +3 -0
- package/dist/commands/egress.d.ts.map +1 -0
- package/dist/commands/egress.js +155 -0
- package/dist/commands/egress.js.map +1 -0
- package/dist/commands/env.d.ts +3 -0
- package/dist/commands/env.d.ts.map +1 -0
- package/dist/commands/env.js +169 -0
- package/dist/commands/env.js.map +1 -0
- package/dist/commands/governance.d.ts +47 -0
- package/dist/commands/governance.d.ts.map +1 -0
- package/dist/commands/governance.js +345 -0
- package/dist/commands/governance.js.map +1 -0
- package/dist/commands/grade.d.ts +41 -0
- package/dist/commands/grade.d.ts.map +1 -1
- package/dist/commands/grade.js +255 -160
- package/dist/commands/grade.js.map +1 -1
- package/dist/commands/history.d.ts +4 -0
- package/dist/commands/history.d.ts.map +1 -0
- package/dist/commands/history.js +157 -0
- package/dist/commands/history.js.map +1 -0
- package/dist/commands/images.d.ts +8 -0
- package/dist/commands/images.d.ts.map +1 -0
- package/dist/commands/images.js +145 -0
- package/dist/commands/images.js.map +1 -0
- package/dist/commands/info.d.ts +3 -0
- package/dist/commands/info.d.ts.map +1 -0
- package/dist/commands/info.js +86 -0
- package/dist/commands/info.js.map +1 -0
- package/dist/commands/init.d.ts +3 -0
- package/dist/commands/init.d.ts.map +1 -0
- package/dist/commands/init.js +185 -0
- package/dist/commands/init.js.map +1 -0
- package/dist/commands/logs.d.ts +3 -0
- package/dist/commands/logs.d.ts.map +1 -0
- package/dist/commands/logs.js +129 -0
- package/dist/commands/logs.js.map +1 -0
- package/dist/commands/mcp.d.ts +3 -0
- package/dist/commands/mcp.d.ts.map +1 -0
- package/dist/commands/mcp.js +141 -0
- package/dist/commands/mcp.js.map +1 -0
- package/dist/commands/open.d.ts +3 -0
- package/dist/commands/open.d.ts.map +1 -0
- package/dist/commands/open.js +96 -0
- package/dist/commands/open.js.map +1 -0
- package/dist/commands/platform-status.d.ts +25 -5
- package/dist/commands/platform-status.d.ts.map +1 -1
- package/dist/commands/platform-status.js +199 -149
- package/dist/commands/platform-status.js.map +1 -1
- package/dist/commands/plugin.d.ts +5 -0
- package/dist/commands/plugin.d.ts.map +1 -0
- package/dist/commands/plugin.js +126 -0
- package/dist/commands/plugin.js.map +1 -0
- package/dist/commands/pool.d.ts.map +1 -1
- package/dist/commands/pool.js +52 -66
- package/dist/commands/pool.js.map +1 -1
- package/dist/commands/profile.d.ts +3 -0
- package/dist/commands/profile.d.ts.map +1 -0
- package/dist/commands/profile.js +107 -0
- package/dist/commands/profile.js.map +1 -0
- package/dist/commands/repl.d.ts +3 -0
- package/dist/commands/repl.d.ts.map +1 -0
- package/dist/commands/repl.js +390 -0
- package/dist/commands/repl.js.map +1 -0
- package/dist/commands/run.d.ts +3 -0
- package/dist/commands/run.d.ts.map +1 -0
- package/dist/commands/run.js +121 -0
- package/dist/commands/run.js.map +1 -0
- package/dist/commands/sandbox-processes.d.ts +27 -0
- package/dist/commands/sandbox-processes.d.ts.map +1 -0
- package/dist/commands/sandbox-processes.js +195 -0
- package/dist/commands/sandbox-processes.js.map +1 -0
- package/dist/commands/sandbox.d.ts.map +1 -1
- package/dist/commands/sandbox.js +506 -98
- package/dist/commands/sandbox.js.map +1 -1
- package/dist/commands/secret.d.ts +3 -0
- package/dist/commands/secret.d.ts.map +1 -0
- package/dist/commands/secret.js +128 -0
- package/dist/commands/secret.js.map +1 -0
- package/dist/commands/session.d.ts.map +1 -1
- package/dist/commands/session.js +285 -52
- package/dist/commands/session.js.map +1 -1
- package/dist/commands/snapshot.d.ts +3 -0
- package/dist/commands/snapshot.d.ts.map +1 -0
- package/dist/commands/snapshot.js +253 -0
- package/dist/commands/snapshot.js.map +1 -0
- package/dist/commands/ssh.d.ts +5 -0
- package/dist/commands/ssh.d.ts.map +1 -0
- package/dist/commands/ssh.js +154 -0
- package/dist/commands/ssh.js.map +1 -0
- package/dist/commands/template.d.ts +3 -0
- package/dist/commands/template.d.ts.map +1 -0
- package/dist/commands/template.js +102 -0
- package/dist/commands/template.js.map +1 -0
- package/dist/commands/terminal.d.ts +53 -0
- package/dist/commands/terminal.d.ts.map +1 -0
- package/dist/commands/terminal.js +381 -0
- package/dist/commands/terminal.js.map +1 -0
- package/dist/commands/top.d.ts +3 -0
- package/dist/commands/top.d.ts.map +1 -0
- package/dist/commands/top.js +116 -0
- package/dist/commands/top.js.map +1 -0
- package/dist/commands/tunnel.d.ts.map +1 -1
- package/dist/commands/tunnel.js +73 -26
- package/dist/commands/tunnel.js.map +1 -1
- package/dist/commands/update.d.ts +3 -0
- package/dist/commands/update.d.ts.map +1 -0
- package/dist/commands/update.js +51 -0
- package/dist/commands/update.js.map +1 -0
- package/dist/commands/wait.d.ts +3 -0
- package/dist/commands/wait.d.ts.map +1 -0
- package/dist/commands/wait.js +64 -0
- package/dist/commands/wait.js.map +1 -0
- package/dist/commands/webhook.d.ts +3 -0
- package/dist/commands/webhook.d.ts.map +1 -0
- package/dist/commands/webhook.js +169 -0
- package/dist/commands/webhook.js.map +1 -0
- package/dist/config.d.ts +14 -6
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +109 -16
- package/dist/config.js.map +1 -1
- package/dist/index.js +165 -11
- package/dist/index.js.map +1 -1
- package/dist/sandboxctl.d.ts +3 -0
- package/dist/sandboxctl.d.ts.map +1 -0
- package/dist/sandboxctl.js +37 -0
- package/dist/sandboxctl.js.map +1 -0
- package/dist/utils/context.d.ts +23 -0
- package/dist/utils/context.d.ts.map +1 -0
- package/dist/utils/context.js +48 -0
- package/dist/utils/context.js.map +1 -0
- package/dist/utils/credentials.d.ts +8 -0
- package/dist/utils/credentials.d.ts.map +1 -0
- package/dist/utils/credentials.js +120 -0
- package/dist/utils/credentials.js.map +1 -0
- package/dist/utils/dry-run.d.ts +4 -0
- package/dist/utils/dry-run.d.ts.map +1 -0
- package/dist/utils/dry-run.js +24 -0
- package/dist/utils/dry-run.js.map +1 -0
- package/dist/utils/egress-policy.d.ts +31 -0
- package/dist/utils/egress-policy.d.ts.map +1 -0
- package/dist/utils/egress-policy.js +83 -0
- package/dist/utils/egress-policy.js.map +1 -0
- package/dist/utils/errors.d.ts +53 -0
- package/dist/utils/errors.d.ts.map +1 -0
- package/dist/utils/errors.js +278 -0
- package/dist/utils/errors.js.map +1 -0
- package/dist/utils/file-content.d.ts +10 -0
- package/dist/utils/file-content.d.ts.map +1 -0
- package/dist/utils/file-content.js +14 -0
- package/dist/utils/file-content.js.map +1 -0
- package/dist/utils/grade-target.d.ts +12 -0
- package/dist/utils/grade-target.d.ts.map +1 -0
- package/dist/utils/grade-target.js +106 -0
- package/dist/utils/grade-target.js.map +1 -0
- package/dist/utils/health-report.d.ts +18 -0
- package/dist/utils/health-report.d.ts.map +1 -0
- package/dist/utils/health-report.js +43 -0
- package/dist/utils/health-report.js.map +1 -0
- package/dist/utils/output.d.ts +20 -0
- package/dist/utils/output.d.ts.map +1 -0
- package/dist/utils/output.js +123 -0
- package/dist/utils/output.js.map +1 -0
- package/dist/utils/plugins.d.ts +17 -0
- package/dist/utils/plugins.d.ts.map +1 -0
- package/dist/utils/plugins.js +57 -0
- package/dist/utils/plugins.js.map +1 -0
- package/dist/utils/resource-class.d.ts +12 -0
- package/dist/utils/resource-class.d.ts.map +1 -0
- package/dist/utils/resource-class.js +17 -0
- package/dist/utils/resource-class.js.map +1 -0
- package/dist/utils/shutdown.d.ts +14 -0
- package/dist/utils/shutdown.d.ts.map +1 -0
- package/dist/utils/shutdown.js +54 -0
- package/dist/utils/shutdown.js.map +1 -0
- package/dist/utils/tty.d.ts +44 -0
- package/dist/utils/tty.d.ts.map +1 -0
- package/dist/utils/tty.js +93 -0
- package/dist/utils/tty.js.map +1 -0
- package/dist/utils/warnings.d.ts +4 -0
- package/dist/utils/warnings.d.ts.map +1 -0
- package/dist/utils/warnings.js +22 -0
- package/dist/utils/warnings.js.map +1 -0
- package/dist/utils/watch.d.ts +7 -0
- package/dist/utils/watch.d.ts.map +1 -0
- package/dist/utils/watch.js +55 -0
- package/dist/utils/watch.js.map +1 -0
- package/dist/workbench/actions.d.ts +26 -0
- package/dist/workbench/actions.d.ts.map +1 -0
- package/dist/workbench/actions.js +38 -0
- package/dist/workbench/actions.js.map +1 -0
- package/dist/workbench/agent-chat.d.ts +71 -0
- package/dist/workbench/agent-chat.d.ts.map +1 -0
- package/dist/workbench/agent-chat.js +223 -0
- package/dist/workbench/agent-chat.js.map +1 -0
- package/dist/workbench/batch-uploads.d.ts +36 -0
- package/dist/workbench/batch-uploads.d.ts.map +1 -0
- package/dist/workbench/batch-uploads.js +154 -0
- package/dist/workbench/batch-uploads.js.map +1 -0
- package/dist/workbench/commands.d.ts +6 -0
- package/dist/workbench/commands.d.ts.map +1 -0
- package/dist/workbench/commands.js +511 -0
- package/dist/workbench/commands.js.map +1 -0
- package/dist/workbench/connection-failure.d.ts +9 -0
- package/dist/workbench/connection-failure.d.ts.map +1 -0
- package/dist/workbench/connection-failure.js +27 -0
- package/dist/workbench/connection-failure.js.map +1 -0
- package/dist/workbench/connection.d.ts +4 -0
- package/dist/workbench/connection.d.ts.map +1 -0
- package/dist/workbench/connection.js +28 -0
- package/dist/workbench/connection.js.map +1 -0
- package/dist/workbench/creation.d.ts +22 -0
- package/dist/workbench/creation.d.ts.map +1 -0
- package/dist/workbench/creation.js +102 -0
- package/dist/workbench/creation.js.map +1 -0
- package/dist/workbench/credits.d.ts +11 -0
- package/dist/workbench/credits.d.ts.map +1 -0
- package/dist/workbench/credits.js +132 -0
- package/dist/workbench/credits.js.map +1 -0
- package/dist/workbench/docker.d.ts +18 -0
- package/dist/workbench/docker.d.ts.map +1 -0
- package/dist/workbench/docker.js +207 -0
- package/dist/workbench/docker.js.map +1 -0
- package/dist/workbench/execution.d.ts +14 -0
- package/dist/workbench/execution.d.ts.map +1 -0
- package/dist/workbench/execution.js +24 -0
- package/dist/workbench/execution.js.map +1 -0
- package/dist/workbench/files.d.ts +51 -0
- package/dist/workbench/files.d.ts.map +1 -0
- package/dist/workbench/files.js +80 -0
- package/dist/workbench/files.js.map +1 -0
- package/dist/workbench/history.d.ts +34 -0
- package/dist/workbench/history.d.ts.map +1 -0
- package/dist/workbench/history.js +50 -0
- package/dist/workbench/history.js.map +1 -0
- package/dist/workbench/input-batch-commands.d.ts +6 -0
- package/dist/workbench/input-batch-commands.d.ts.map +1 -0
- package/dist/workbench/input-batch-commands.js +41 -0
- package/dist/workbench/input-batch-commands.js.map +1 -0
- package/dist/workbench/kitty-diacritics.d.ts +2 -0
- package/dist/workbench/kitty-diacritics.d.ts.map +1 -0
- package/dist/workbench/kitty-diacritics.js +22 -0
- package/dist/workbench/kitty-diacritics.js.map +1 -0
- package/dist/workbench/kitty-graphics.d.ts +59 -0
- package/dist/workbench/kitty-graphics.d.ts.map +1 -0
- package/dist/workbench/kitty-graphics.js +263 -0
- package/dist/workbench/kitty-graphics.js.map +1 -0
- package/dist/workbench/live-execution.d.ts +51 -0
- package/dist/workbench/live-execution.d.ts.map +1 -0
- package/dist/workbench/live-execution.js +222 -0
- package/dist/workbench/live-execution.js.map +1 -0
- package/dist/workbench/model.d.ts +106 -0
- package/dist/workbench/model.d.ts.map +1 -0
- package/dist/workbench/model.js +236 -0
- package/dist/workbench/model.js.map +1 -0
- package/dist/workbench/overview.d.ts +11 -0
- package/dist/workbench/overview.d.ts.map +1 -0
- package/dist/workbench/overview.js +92 -0
- package/dist/workbench/overview.js.map +1 -0
- package/dist/workbench/png.d.ts +10 -0
- package/dist/workbench/png.d.ts.map +1 -0
- package/dist/workbench/png.js +51 -0
- package/dist/workbench/png.js.map +1 -0
- package/dist/workbench/python-task.d.ts +21 -0
- package/dist/workbench/python-task.d.ts.map +1 -0
- package/dist/workbench/python-task.js +52 -0
- package/dist/workbench/python-task.js.map +1 -0
- package/dist/workbench/registry-commands.d.ts +8 -0
- package/dist/workbench/registry-commands.d.ts.map +1 -0
- package/dist/workbench/registry-commands.js +93 -0
- package/dist/workbench/registry-commands.js.map +1 -0
- package/dist/workbench/registry.d.ts +76 -0
- package/dist/workbench/registry.d.ts.map +1 -0
- package/dist/workbench/registry.js +353 -0
- package/dist/workbench/registry.js.map +1 -0
- package/dist/workbench/renderer.d.ts +6 -0
- package/dist/workbench/renderer.d.ts.map +1 -0
- package/dist/workbench/renderer.js +18 -0
- package/dist/workbench/renderer.js.map +1 -0
- package/dist/workbench/results.d.ts +15 -0
- package/dist/workbench/results.d.ts.map +1 -0
- package/dist/workbench/results.js +29 -0
- package/dist/workbench/results.js.map +1 -0
- package/dist/workbench/task-archive.d.ts +23 -0
- package/dist/workbench/task-archive.d.ts.map +1 -0
- package/dist/workbench/task-archive.js +56 -0
- package/dist/workbench/task-archive.js.map +1 -0
- package/dist/workbench/task-board.d.ts +26 -0
- package/dist/workbench/task-board.d.ts.map +1 -0
- package/dist/workbench/task-board.js +43 -0
- package/dist/workbench/task-board.js.map +1 -0
- package/dist/workbench/task-monitor.d.ts +35 -0
- package/dist/workbench/task-monitor.d.ts.map +1 -0
- package/dist/workbench/task-monitor.js +176 -0
- package/dist/workbench/task-monitor.js.map +1 -0
- package/dist/workbench/tasks.d.ts +93 -0
- package/dist/workbench/tasks.d.ts.map +1 -0
- package/dist/workbench/tasks.js +195 -0
- package/dist/workbench/tasks.js.map +1 -0
- package/dist/workbench/terminal.d.ts +82 -0
- package/dist/workbench/terminal.d.ts.map +1 -0
- package/dist/workbench/terminal.js +2577 -0
- package/dist/workbench/terminal.js.map +1 -0
- package/dist/workbench/text.d.ts +10 -0
- package/dist/workbench/text.d.ts.map +1 -0
- package/dist/workbench/text.js +72 -0
- package/dist/workbench/text.js.map +1 -0
- package/dist/workbench/uploads.d.ts +12 -0
- package/dist/workbench/uploads.d.ts.map +1 -0
- package/dist/workbench/uploads.js +16 -0
- package/dist/workbench/uploads.js.map +1 -0
- package/dist/workbench/worker-launch.d.ts +10 -0
- package/dist/workbench/worker-launch.d.ts.map +1 -0
- package/dist/workbench/worker-launch.js +30 -0
- package/dist/workbench/worker-launch.js.map +1 -0
- package/dist/workbench/worker-monitor.d.ts +33 -0
- package/dist/workbench/worker-monitor.d.ts.map +1 -0
- package/dist/workbench/worker-monitor.js +142 -0
- package/dist/workbench/worker-monitor.js.map +1 -0
- package/dist/workbench/worker-output.d.ts +8 -0
- package/dist/workbench/worker-output.d.ts.map +1 -0
- package/dist/workbench/worker-output.js +32 -0
- package/dist/workbench/worker-output.js.map +1 -0
- package/dist/workbench/worker-result.d.ts +29 -0
- package/dist/workbench/worker-result.d.ts.map +1 -0
- package/dist/workbench/worker-result.js +85 -0
- package/dist/workbench/worker-result.js.map +1 -0
- package/dist/workbench/workers.d.ts +49 -0
- package/dist/workbench/workers.d.ts.map +1 -0
- package/dist/workbench/workers.js +53 -0
- package/dist/workbench/workers.js.map +1 -0
- package/package.json +38 -17
- package/dist/__tests__/client.test.d.ts +0 -2
- package/dist/__tests__/client.test.d.ts.map +0 -1
- package/dist/__tests__/client.test.js +0 -198
- package/dist/__tests__/client.test.js.map +0 -1
- package/dist/__tests__/config.test.d.ts +0 -2
- package/dist/__tests__/config.test.d.ts.map +0 -1
- package/dist/__tests__/config.test.js +0 -74
- package/dist/__tests__/config.test.js.map +0 -1
- package/dist/__tests__/utils-cli.test.d.ts +0 -2
- package/dist/__tests__/utils-cli.test.d.ts.map +0 -1
- package/dist/__tests__/utils-cli.test.js +0 -35
- package/dist/__tests__/utils-cli.test.js.map +0 -1
package/README.md
ADDED
|
@@ -0,0 +1,805 @@
|
|
|
1
|
+
# @stateset/sandbox-cli
|
|
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
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @stateset/sandbox-cli
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Requires Node.js 20.19+ (20.x line) or 22.12+.
|
|
12
|
+
|
|
13
|
+
## Quick Start
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
# Interactive setup — prompts for API key, URL, and defaults
|
|
17
|
+
stateset config setup
|
|
18
|
+
|
|
19
|
+
# Or configure manually
|
|
20
|
+
stateset config set-key sk_live_your_api_key
|
|
21
|
+
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.
|
|
57
|
+
|
|
58
|
+
## Configuration
|
|
59
|
+
|
|
60
|
+
The CLI stores configuration locally via [conf](https://github.com/sindresorhus/conf). Environment variables take precedence over stored values.
|
|
61
|
+
|
|
62
|
+
| Setting | Env Variable | Default |
|
|
63
|
+
|---------|-------------|---------|
|
|
64
|
+
| API Key | `STATESET_API_KEY` | — |
|
|
65
|
+
| API URL | `STATESET_API_URL` (or `STATESET_BASE_URL`, as used by the SDKs) | `https://api.sandbox.stateset.app` |
|
|
66
|
+
| Default Timeout | `STATESET_DEFAULT_TIMEOUT_SECONDS` | `300` |
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
stateset config show # Display current configuration
|
|
70
|
+
stateset config path # Show config file location
|
|
71
|
+
stateset config clear # Wipe all stored config
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Commands
|
|
75
|
+
|
|
76
|
+
### Audit history and exports
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
stateset --json audit list --sandbox <sandbox-id>
|
|
80
|
+
stateset --json audit summary <sandbox-id>
|
|
81
|
+
stateset audit export --sandbox <sandbox-id> --output audit-history.json
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Audit reads report `storage` and `durable_read`. When `durable_read` is false,
|
|
85
|
+
history is limited to the responding controller replica; export refuses that
|
|
86
|
+
partial history. Older servers without these fields produce an export warning.
|
|
87
|
+
Exports use a new private file, advance through distinct pages, and reject
|
|
88
|
+
inconsistent history or more than 10,000 events. Choose a sandbox filter and a
|
|
89
|
+
new filename when needed. A successful database read does not guarantee that
|
|
90
|
+
every audit write committed.
|
|
91
|
+
|
|
92
|
+
### Shared terminal dashboard and agent commands
|
|
93
|
+
|
|
94
|
+
Run `stateset tui` (or `sandboxctl tui`) in a Herdr pane. Agents can use
|
|
95
|
+
`sandboxctl create`, `status`, `show`, `exec`, `pause`, `resume`, `extend` and
|
|
96
|
+
`stop`, which return JSON. Use `--backend docker --image <cached-image>` for
|
|
97
|
+
local containers without API credentials, or the default API backend with your
|
|
98
|
+
existing profile. From this checkout, use `./sandboxctl` without a rebuild.
|
|
99
|
+
|
|
100
|
+
For Ghostty, `bash scripts/ghostty-sandbox.sh` opens a persistent shell and TUI
|
|
101
|
+
workspace using a dedicated terminal profile. See the
|
|
102
|
+
[Ghostty workspace shortcuts](../docs/SANDBOX_WORKBENCH.md#ghostty-workspace).
|
|
103
|
+
Press `n` to edit CPU, memory, lifetime and hosted resource class directly in
|
|
104
|
+
the TUI. Startup flags fill the form; Tab moves fields, Enter reviews and `y`
|
|
105
|
+
creates the sandbox. Escape returns to editing or back to the list.
|
|
106
|
+
On the hosted backend the form also selects a runtime image and inference
|
|
107
|
+
gateway (`none`, `anthropic` or `openai`), an org secret name and output-token
|
|
108
|
+
cap per clock hour. Left/Right changes the gateway; Tab reaches text fields.
|
|
109
|
+
The gateway uses the default provider secret when the name is blank. Set up
|
|
110
|
+
a funded provider account and its organization secret before enabling it.
|
|
111
|
+
Startup equivalents are `--runtime-image`, `--inference`, `--inference-secret`
|
|
112
|
+
and `--inference-limit`. The default gateway cap is 20000 output tokens/hour;
|
|
113
|
+
in-flight calls can overshoot. Local Docker retains its existing `--image`
|
|
114
|
+
setting and rejects hosted gateway options.
|
|
115
|
+
Use `/` to search sandbox IDs, statuses or creating Herdr panes, Enter for
|
|
116
|
+
details, and `?` for keyboard help. PageUp/PageDown and Home/End navigate the
|
|
117
|
+
filtered list; details and help wrap and scroll inside narrow panes.
|
|
118
|
+
Press `a` for session activity across all sandboxes. Start with
|
|
119
|
+
`stateset tui --read-only --filter paused` for a focused monitoring pane;
|
|
120
|
+
search also accepts pasted IDs.
|
|
121
|
+
The list shows allocations and a live expiry countdown. Press `o` for status
|
|
122
|
+
counts and running allocation totals, or `t` to sort by ID, expiry, status or
|
|
123
|
+
newest. Start with `--sort expiry` to prioritize upcoming deadlines.
|
|
124
|
+
Press F2 or `:` for a searchable action menu with availability explanations.
|
|
125
|
+
It also works from sandbox details and keeps its original target selected.
|
|
126
|
+
Press `c` for connection diagnostics and full refresh errors. Delayed reads
|
|
127
|
+
mark old snapshots stale and block changes until a refresh succeeds.
|
|
128
|
+
Press `g` to launch a prepared agent command as a supervised worker and `w` to
|
|
129
|
+
monitor workers from this TUI, the API or MCP. In the launcher, Tab selects the
|
|
130
|
+
command, recovery name and runtime (default 300 seconds); Enter reviews all
|
|
131
|
+
settings before `y` starts one worker. Enter in the worker list reads logs; `v`
|
|
132
|
+
opens the result with outcome, exit details and bounded stdout/stderr; `d`
|
|
133
|
+
reviews stopping a worker. Agents use `sandboxctl spawn <id> --name child --
|
|
134
|
+
<argv...>`, `ps`, `logs`, `result <id> <process-id>` and `kill` for the same process IDs as the TUI.
|
|
135
|
+
Result refreshes retain the selected process and keep stale output visible after
|
|
136
|
+
read failures. Older servers show status and logs with an unverified outcome.
|
|
137
|
+
Worker log and result views validate stream identity and any process or sandbox
|
|
138
|
+
identity supplied by the server. Malformed base64 and output over 1 MiB decoded per
|
|
139
|
+
stream fail explicitly; accepted output is limited to the latest 16 KiB of decoded
|
|
140
|
+
bytes per stream. A failed TUI log refresh retains the last complete stdout/stderr
|
|
141
|
+
pair as stale. JSON `logs` reports `truncated` separately from `rotated` and
|
|
142
|
+
preserves the server's continuation offsets. Older chunks without process or
|
|
143
|
+
sandbox metadata rely on the pinned request; missing metadata does not verify identity.
|
|
144
|
+
Switching worker views discards obsolete responses and queues at most one refresh
|
|
145
|
+
for the latest requested view. The footer shows when that refresh is waiting.
|
|
146
|
+
Leaving or quitting cancels an obsolete worker-list read. Log and result reads
|
|
147
|
+
that cannot be cancelled must settle before another read starts; their late
|
|
148
|
+
output and errors cannot update a view you have left. Pending API reads recheck
|
|
149
|
+
the selected view before dispatch, and manual refresh respects the shared
|
|
150
|
+
rate-limit pause. None of these observation controls stop or restart workers.
|
|
151
|
+
Press `h` for saved execution history and receipts after a lost response.
|
|
152
|
+
Press `l` to delegate a task with an objective, parent ID, prepared command,
|
|
153
|
+
runtime and expected artifact paths. Enter reviews it; `y` dispatches once.
|
|
154
|
+
Press `m` for the task board across all sandboxes. Enter inspects a saved task;
|
|
155
|
+
`v` opens its worker result, `f` opens artifacts and `g` prepares a child task.
|
|
156
|
+
On the board, `/` finds literal words across task names, objectives, sandbox,
|
|
157
|
+
process and parent IDs. Enter applies; Escape cancels editing and restores the
|
|
158
|
+
previous query and selected task. `t` cycles all, active, attention, finished
|
|
159
|
+
and unobserved tasks. Saved history never counts as active; finished means an
|
|
160
|
+
observed zero process exit, not validated task quality. `p` focuses the selected
|
|
161
|
+
task's parent and its known descendants using saved links; `a` clears filters.
|
|
162
|
+
Home/End and PageUp/PageDown navigate the visible tasks. Filters stay within the
|
|
163
|
+
task board and do not change the sandbox search or a pinned task detail.
|
|
164
|
+
The board continues checking exited workers whose exit code is missing and
|
|
165
|
+
observations whose history could not be saved. Once resolved, unselected terminal
|
|
166
|
+
workers leave the polling rotation. Task detail refreshes only its pinned worker;
|
|
167
|
+
return to the board to monitor the fleet. Reads retain the existing retry delays
|
|
168
|
+
and shared rate-limit pause, and never repeat a worker launch.
|
|
169
|
+
|
|
170
|
+
Agents can read the same local journal with bounded JSON output:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
./sandboxctl tasks --parent-task team-1 --sandbox <sandbox-id> --query 'review checkout' --limit 25
|
|
174
|
+
./sandboxctl tasks --family team-1 --query 'review' --limit 25
|
|
175
|
+
# Continue with the returned next_cursor and the same filters:
|
|
176
|
+
./sandboxctl tasks --family team-1 --query 'review' --limit 25 --cursor '<next_cursor>'
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
`total` counts all current matches before pagination. Pages default to 100
|
|
180
|
+
receipts (maximum 1000); `next_cursor: null` ends traversal. `--parent-task`
|
|
181
|
+
selects direct children; `--family` includes the anchor and all known descendants,
|
|
182
|
+
as in TUI family focus, even across sandboxes and through intermediate tasks
|
|
183
|
+
excluded by other filters. Filters combine with AND. Search matches literal,
|
|
184
|
+
case-insensitive words in metadata. Empty or malformed exact IDs are rejected.
|
|
185
|
+
The SDK, CLI, TUI and MCP share search and family traversal. CLI/MCP cursors
|
|
186
|
+
are interchangeable with the same journal and filters. Ordering is newest first,
|
|
187
|
+
with a stable task-ID tie-breaker. Newer inserts do not shift later pages;
|
|
188
|
+
pagination is not a snapshot, so totals and matching metadata may change.
|
|
189
|
+
Restart from the first page to discover new arrivals. These filters read saved
|
|
190
|
+
metadata and do not contact workers or launch tasks.
|
|
191
|
+
|
|
192
|
+
Open an agent's saved work directly in a terminal pane:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
./sandboxctl tui --task <saved-task-id> --read-only
|
|
196
|
+
./sandboxctl tui --task-family team-1
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Choose one startup focus. The task detail pins the exact saved ID; a missing
|
|
200
|
+
receipt never opens an unrelated task. Family focus includes known descendants
|
|
201
|
+
across sandboxes. Both use the configured local journal and work independently
|
|
202
|
+
of the sandbox list filter. Receipts render before remote reads finish; expired
|
|
203
|
+
or unavailable workers still show their saved metadata and archived bundles.
|
|
204
|
+
Startup focus never launches a worker. Quit leaves existing workers running.
|
|
205
|
+
|
|
206
|
+
Shared task discovery uses the server registry, available on controllers with
|
|
207
|
+
migration 067 and the registry release:
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
./sandboxctl --dry-run registry register <saved-task-uuid>
|
|
211
|
+
./sandboxctl registry register <saved-task-uuid>
|
|
212
|
+
./sandboxctl registry list --limit 25
|
|
213
|
+
./sandboxctl registry get <task-uuid>
|
|
214
|
+
./sandboxctl registry grant <task-uuid> <organization-user-uuid> --role viewer
|
|
215
|
+
./sandboxctl registry grants <task-uuid>
|
|
216
|
+
./sandboxctl registry revoke <task-uuid> <organization-user-uuid>
|
|
217
|
+
./sandboxctl tui --registry
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
Registration publishes curated metadata from the private journal without starting
|
|
221
|
+
a worker or sharing command arguments/environment. Server parents must already
|
|
222
|
+
be registered task UUIDs; local `team-*` family labels cannot authorize children.
|
|
223
|
+
`list` also accepts `--root-task`, `--parent-task` and `--cursor`; keep filters
|
|
224
|
+
unchanged while traversing pages. Shared readers need no copy of the journal.
|
|
225
|
+
The root owner grants viewer/operator access to the whole family and future
|
|
226
|
+
descendants; sandbox execution permissions are checked separately.
|
|
227
|
+
|
|
228
|
+
In the TUI, search for **registry** in F2, or press `u` from a saved task. Enter
|
|
229
|
+
opens metadata, `n`/`b` page, `f` focuses a family and `a` clears that filter.
|
|
230
|
+
From details, `p` reviews registration from a private receipt, `g` reviews a
|
|
231
|
+
grant and `d` reviews revoking the selected principal. Enter reviews the form;
|
|
232
|
+
`y` confirms and Escape cancels. `--read-only` disables all three changes.
|
|
233
|
+
Unknown write outcomes require a fresh `get`/`grants` read before another
|
|
234
|
+
review; writes are never automatically resent. Registry status does not prove a
|
|
235
|
+
worker is running. Older controllers show an explicit unavailable message.
|
|
236
|
+
|
|
237
|
+
For multi-file inputs, press `i` in workspace files or search **inputs** in F2.
|
|
238
|
+
Prepare a JSON array of `{path, source}` entries; sources resolve relative to
|
|
239
|
+
the manifest. `input-batch plan <sandbox-id> <manifest.json>` saves a private
|
|
240
|
+
receipt without remote calls. Review its mapping, then run
|
|
241
|
+
`input-batch upload <batch-id> --sha256 <manifest-sha256>` (global `--dry-run`
|
|
242
|
+
previews that upload). `input-batch inspect` verifies attempted files read-only.
|
|
243
|
+
The TUI uses `c` to review, `y` to confirm and `v` to inspect; paste a saved batch
|
|
244
|
+
UUID and manifest hash to reopen it. Read-only mode blocks planning and upload.
|
|
245
|
+
|
|
246
|
+
Limits are 32 files, 5 MiB/file and 20 MiB total. Logical paths map to independent
|
|
247
|
+
private remote files; a directory tree is not extracted. Keep the returned
|
|
248
|
+
actual paths for your worker. Recovery checks all earlier attempts and uploads
|
|
249
|
+
only never-attempted files. Unverified attempts block continuation. Share the
|
|
250
|
+
private `STATESET_INPUT_BATCH_DIR` across parent entry points, separating accounts.
|
|
251
|
+
See the [batch workflow](../docs/SANDBOX_WORKBENCH.md#multi-file-input-batches).
|
|
252
|
+
|
|
253
|
+
Attach that batch with `delegate <sandbox-id> --input-batch <uuid>
|
|
254
|
+
--input-sha256 <manifest-hash> --objective 'Analyze inputs' -- <prepared argv>`.
|
|
255
|
+
Global `--dry-run` previews the attachment offline. In the TUI, `g` in a verified
|
|
256
|
+
batch opens delegation with both fields filled in. Each CLI `team-launch`
|
|
257
|
+
member may set `input_batch: {batch_id, manifest_sha256}` as well.
|
|
258
|
+
|
|
259
|
+
`{{input:logical/path}}` resolves to a reviewed remote input in exact argv.
|
|
260
|
+
The parent checks the pinned files immediately before dispatch; changed or
|
|
261
|
+
unavailable bytes leave a `not_started` receipt and start no worker. Children
|
|
262
|
+
receive `input_batch` and `input_binding_sha256` in `STATESET_TASK_FILE`, with
|
|
263
|
+
no local source paths. A current integrity check at consumption time remains
|
|
264
|
+
the prepared worker's responsibility.
|
|
265
|
+
The launch also pins the reviewed hash as `STATESET_TASK_INPUT_BINDING_SHA256`.
|
|
266
|
+
The [standalone worker wrapper](../examples/verified-worker/README.md) checks
|
|
267
|
+
that pin and the actual bytes before invoking any prepared command.
|
|
268
|
+
|
|
269
|
+
For OpenAI CLI workers, the [Codex adapter](../examples/codex-agent/README.md)
|
|
270
|
+
reads the same task contract and writes structured results plus curated run
|
|
271
|
+
evidence. Prepare Codex and its authentication inside the sandbox first; the
|
|
272
|
+
adapter preserves its configured model and does not copy the host login.
|
|
273
|
+
Unavailable task polling backs off from 10 to 120 seconds; `r` retries the selected
|
|
274
|
+
task. A server rate limit pauses remote reads across the TUI, including manual
|
|
275
|
+
refresh, while local receipts and archived results remain available.
|
|
276
|
+
Agents use `sandboxctl delegate <id> --objective "Review changes" --parent-task
|
|
277
|
+
team-1 --artifact result.json -- agent --task-file '{task_file}'`, followed by
|
|
278
|
+
`tasks` and `task <task-id>`. The worker must already be installed and configured.
|
|
279
|
+
For a parent that needs a bounded completion check:
|
|
280
|
+
|
|
281
|
+
```bash
|
|
282
|
+
./sandboxctl task <task-id> --wait --wait-timeout 60 --poll-interval 2
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
The watcher makes sequential identity-checked reads and returns JSON with
|
|
286
|
+
`state`, `polls`, the last `observation` when available, and
|
|
287
|
+
`task_quality: not_evaluated`. States are `terminal`, `timeout`, `aborted`, and
|
|
288
|
+
`unavailable`. Exit codes are 0 for an observed zero exit, 1 for a failed or
|
|
289
|
+
unavailable outcome, 124 for the watch deadline, and 130/143 on SIGINT/SIGTERM.
|
|
290
|
+
Timeout or cancellation stops watching and leaves the child running. Retry
|
|
291
|
+
`task --wait` with the same saved ID; never repeat `delegate` for recovery.
|
|
292
|
+
The watch deadline also bounds stalled HTTP reads. HTTP 429 pauses reads for
|
|
293
|
+
Retry-After (30 seconds by default, bounded to 1 second–24 hours) within the
|
|
294
|
+
watch deadline. Other read failures return unavailable immediately. A terminal
|
|
295
|
+
process exit does not validate artifact contents.
|
|
296
|
+
|
|
297
|
+
Launch a bounded team from a JSON array of prepared task inputs:
|
|
298
|
+
|
|
299
|
+
```bash
|
|
300
|
+
./sandboxctl --dry-run team-launch members.json --concurrency 3
|
|
301
|
+
./sandboxctl team-launch members.json --name 'Checkout reviewers' --concurrency 3
|
|
302
|
+
./sandboxctl team <team-id>
|
|
303
|
+
./sandboxctl team <team-id> --local
|
|
304
|
+
./sandboxctl tui --task-family team-<team-id>
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
Each member supplies `sandbox_id`, `objective`, `command` (an argv array), and
|
|
308
|
+
optional `name`, `timeout_seconds`, `stdin` and `artifact_paths`. Omit
|
|
309
|
+
`parent_task_id`; the team generates a shared family. The runtime must already
|
|
310
|
+
be prepared in each sandbox. Teams support 1–16 tasks and 1–4 simultaneous
|
|
311
|
+
starts; concurrency limits dispatch, not the number of workers left running.
|
|
312
|
+
The CLI prints a `prepared` recovery anchor to stderr after saving every member
|
|
313
|
+
identity and before starting workers. Stdout contains the final JSON receipt.
|
|
314
|
+
`accepted` means starts were acknowledged; task correctness needs separate checks.
|
|
315
|
+
An uncertain start halts undispatched members while already dispatched members
|
|
316
|
+
remain independent. Recover with `team <team-id>`; never repeat `team-launch`.
|
|
317
|
+
`--local` reads historical receipts without contacting sandboxes. Set the same
|
|
318
|
+
absolute `STATESET_AGENT_TEAM_DIR` across parents; its default is
|
|
319
|
+
`.stateset-agent-teams` in the current directory. Family links are private
|
|
320
|
+
journal metadata and do not grant server access to another account's tasks.
|
|
321
|
+
|
|
322
|
+
For another parent to discover and monitor the team using only API access, use
|
|
323
|
+
the opt-in server registry:
|
|
324
|
+
|
|
325
|
+
```bash
|
|
326
|
+
./sandboxctl team-launch members.json --registered --concurrency 3
|
|
327
|
+
./sandboxctl registry observe <root-task-uuid> --timeout 30
|
|
328
|
+
./sandboxctl tui --registry-root <root-task-uuid> --read-only
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
The returned `team_id` is the server root UUID. Registration must finish before
|
|
332
|
+
any worker starts; save the prepared recovery anchor and inspect `team <id>`
|
|
333
|
+
after an uncertain response. Do not relaunch. A metadata coordinator anchors the
|
|
334
|
+
family and intentionally has no worker. The observer checks process identity
|
|
335
|
+
and command hashes and distinguishes missing, ambiguous, mismatched and
|
|
336
|
+
unavailable processes. It does not judge task correctness. In TUI registry
|
|
337
|
+
detail, press `v` to read live workers; registry-only startup needs no local task
|
|
338
|
+
receipts. Process access is authorized separately from registry family access.
|
|
339
|
+
`registry observe` supports `--limit` (1–100) and `--cursor`; follow returned
|
|
340
|
+
cursors and check `family_complete` before treating a page as the whole family.
|
|
341
|
+
|
|
342
|
+
Set `STATESET_AGENT_TASK_DIR` to the same absolute private journal directory in
|
|
343
|
+
the TUI, CLI and MCP server to share receipts; the default is
|
|
344
|
+
`.stateset-agent-tasks` under each process's working directory. Use a separate
|
|
345
|
+
journal for each account. Receipts survive parent restarts; sandbox files still
|
|
346
|
+
expire with their sandbox. An uncertain launch is inspected without replay.
|
|
347
|
+
Verified status changes are saved in the journal. After expiry or a live-read
|
|
348
|
+
failure, the board labels saved status as historical and keeps its timestamp
|
|
349
|
+
in task detail. Failed process exits show `FAILED | exit <code>`; exit zero
|
|
350
|
+
still requires artifact inspection. A failed history write is visible separately.
|
|
351
|
+
On the task board, `b` opens the result archive for the current family/search
|
|
352
|
+
and observed-state selection (up to 16 visible tasks). It lists saved bundle
|
|
353
|
+
metadata separately for each agent, including complete, partial, unavailable
|
|
354
|
+
and missing collections. Enter verifies the newest available bundle and its
|
|
355
|
+
files before showing artifacts. Esc returns through the preview, bundle list
|
|
356
|
+
and archive while preserving the selected agent. `r` refreshes local metadata.
|
|
357
|
+
Archive reads work during a stalled API poll, after sandbox expiry, and in
|
|
358
|
+
read-only mode. Metadata completeness does not establish file integrity or task
|
|
359
|
+
correctness; opening the bundle performs the integrity check. Collect artifacts
|
|
360
|
+
before sandbox expiry to make them available here.
|
|
361
|
+
|
|
362
|
+
In task detail, `c` reviews collecting declared artifacts into a new private
|
|
363
|
+
parent-side bundle, and `b` lists saved bundles. Enter verifies a bundle and
|
|
364
|
+
previews its text or binary metadata. These reads work after remote expiry;
|
|
365
|
+
collection must happen while the terminal worker and its files remain reachable.
|
|
366
|
+
Read-only TUI mode permits collection because it makes no remote mutations.
|
|
367
|
+
|
|
368
|
+
Agents use `sandboxctl collect <task-id>` (or `--dry-run collect` for its plan),
|
|
369
|
+
`bundles <task-id>` and `task-bundle <directory> --sha256 <saved-manifest-hash>`.
|
|
370
|
+
The last command verifies entirely offline without API credentials; add
|
|
371
|
+
`--artifact result.json` to return a verified artifact as base64.
|
|
372
|
+
Set `STATESET_AGENT_RESULT_DIR` to a shared absolute private root; the default
|
|
373
|
+
is `.stateset-agent-results` under the current working directory. Collection
|
|
374
|
+
is bounded to 5 MiB per file and 20 MiB total. A partial collection returns its
|
|
375
|
+
manifest with CLI exit 1. File integrity and task correctness are separate.
|
|
376
|
+
Agents use `sandboxctl history <id>` and `receipt <id> <execution-id>` to
|
|
377
|
+
retrieve status and output without rerunning the command.
|
|
378
|
+
Press `i` for a Python task with editable source, task name and runtime. Each
|
|
379
|
+
reviewed run gets its own workspace directory, source hash and saved source.
|
|
380
|
+
Press `f` to browse files, preview artifacts and review a local download with
|
|
381
|
+
its full path. Python runs in a fresh process; workspace files persist until expiry.
|
|
382
|
+
|
|
383
|
+
In workspace files, `u` opens a local input upload. Enter reviews the full
|
|
384
|
+
sandbox ID, generated destination, size and SHA-256; `y` uploads one file into
|
|
385
|
+
a new `/workspace/input-<uuid>` directory and verifies its remote bytes.
|
|
386
|
+
Text and binary files up to 5 MiB are supported. Local source symlinks, special
|
|
387
|
+
files and changes after review are refused. The terminal path editor accepts
|
|
388
|
+
ASCII paths; CLI uploads also accept Unicode paths. Read-only mode blocks uploads.
|
|
389
|
+
|
|
390
|
+
```bash
|
|
391
|
+
./sandboxctl --dry-run upload <sandbox-id> ./orders.csv
|
|
392
|
+
./sandboxctl upload <sandbox-id> ./orders.csv
|
|
393
|
+
# Save the returned remote_path, size and sha256 with the parent task.
|
|
394
|
+
./sandboxctl verify-input <sandbox-id> <remote-path> --size <bytes> --sha256 <hash>
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
An existing destination or uncertain directory creation prevents the file write.
|
|
398
|
+
No upload request is automatically repeated. If a response is lost, the error
|
|
399
|
+
retains the input plan and failing stage; `verify-input` or TUI `v` checks remote
|
|
400
|
+
bytes without uploading again. A failed verification does not prove the remote
|
|
401
|
+
file is absent. Inspect it before preparing another upload. Files expire with
|
|
402
|
+
their sandbox; the local source is not copied into the parent task journal.
|
|
403
|
+
|
|
404
|
+
Press `x` on a running sandbox to type or paste a shell command, review with
|
|
405
|
+
Enter and run with `y`. Read live stdout/stderr and exit status in a scrollable
|
|
406
|
+
result screen. `z` reviews cancellation, `r` recovers a saved receipt after a
|
|
407
|
+
disconnect, and `x` edits another command after completion. Commands run with `sh -lc` inside
|
|
408
|
+
the selected sandbox and are never automatically retried.
|
|
409
|
+
Press `b` to choose prepaid USD credits and continue to owner-authorized Stripe
|
|
410
|
+
Checkout in your browser. Agents can use `sandboxctl credits 25` for a JSON
|
|
411
|
+
billing link, or `stateset billing credits 25 --open` to open it directly.
|
|
412
|
+
Press `s` to review subscription plans or reactivate through owner billing.
|
|
413
|
+
Agents can use `sandboxctl subscribe --open` or `stateset billing subscribe --open`.
|
|
414
|
+
The browser handles plan selection and confirmation of recurring and usage charges.
|
|
415
|
+
|
|
416
|
+
See the [sandbox workbench guide](../docs/SANDBOX_WORKBENCH.md) for keyboard
|
|
417
|
+
controls, examples, resource limits and the local Docker isolation boundary.
|
|
418
|
+
|
|
419
|
+
### `stateset sandbox`
|
|
420
|
+
|
|
421
|
+
Manage sandbox environments.
|
|
422
|
+
|
|
423
|
+
```bash
|
|
424
|
+
stateset sandbox create [options] # Create a new sandbox
|
|
425
|
+
stateset sandbox list # List all sandboxes
|
|
426
|
+
stateset sandbox get <id> # Get sandbox details
|
|
427
|
+
stateset sandbox exec <id> <command> # Execute a command
|
|
428
|
+
stateset sandbox stop <id> # Stop a sandbox
|
|
429
|
+
stateset sandbox extend <id> # Extend sandbox lifetime
|
|
430
|
+
stateset sandbox write <id> <path> <content> # Write a file
|
|
431
|
+
stateset sandbox read <id> <path> # Read a file
|
|
432
|
+
stateset sandbox ls-files <id> # List directory contents
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
**Create options:**
|
|
436
|
+
|
|
437
|
+
| Flag | Description | Example |
|
|
438
|
+
|------|-------------|---------|
|
|
439
|
+
| `-t, --timeout <seconds>` | Sandbox timeout | `--timeout 600` |
|
|
440
|
+
| `-c, --cpus <cpus>` | CPU limit | `--cpus 1` |
|
|
441
|
+
| `-m, --memory <memory>` | Memory limit | `--memory 1Gi` |
|
|
442
|
+
| `-i, --isolation <level>` | Isolation level | `--isolation gvisor` |
|
|
443
|
+
| `-e, --env <KEY=VALUE>` | Environment variables (repeatable) | `-e FOO=bar -e BAZ=qux` |
|
|
444
|
+
|
|
445
|
+
### `stateset checkpoint`
|
|
446
|
+
|
|
447
|
+
Create, restore, and compare sandbox checkpoints.
|
|
448
|
+
|
|
449
|
+
```bash
|
|
450
|
+
stateset checkpoint create <sandbox-id> <name> # Create checkpoint
|
|
451
|
+
stateset checkpoint list # List checkpoints
|
|
452
|
+
stateset checkpoint get <id> # Get details
|
|
453
|
+
stateset checkpoint restore <sandbox-id> <cp-id> # Restore checkpoint
|
|
454
|
+
stateset checkpoint clone <id> <new-name> # Clone a checkpoint
|
|
455
|
+
stateset checkpoint diff <id-1> <id-2> # Compare two checkpoints
|
|
456
|
+
stateset checkpoint rm <id> # Delete checkpoint
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
Checkpoint create, restore, clone and delete accept global `--json` or a local
|
|
460
|
+
`--json` flag. Standard output contains one receipt; warnings remain on standard
|
|
461
|
+
error and in the receipt when supplied. An explicit global `--format` takes
|
|
462
|
+
precedence. For example:
|
|
463
|
+
|
|
464
|
+
```bash
|
|
465
|
+
stateset --json checkpoint create <sandbox-id> before-task --no-env
|
|
466
|
+
stateset checkpoint restore <sandbox-id> <checkpoint-id> --json
|
|
467
|
+
stateset checkpoint clone <checkpoint-id> task-copy --json
|
|
468
|
+
stateset checkpoint rm <checkpoint-id> --force --json
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
These four mutations do not add a CLI retry loop around the SDK operation.
|
|
472
|
+
After a lost response, inspect `checkpoint list` or `checkpoint get <id>` before
|
|
473
|
+
repeating capture, cloning or deletion. Inspect the target sandbox's files and
|
|
474
|
+
environment before repeating a restore. The SDK transport retains its retry
|
|
475
|
+
policy; this does not guarantee exactly-once server execution. Restore/delete
|
|
476
|
+
require a positive acknowledgement, which does not independently verify restored
|
|
477
|
+
contents or backend cleanup. Create/clone reject incomplete receipt identity or
|
|
478
|
+
summary fields before reporting success; create checks the source sandbox, and
|
|
479
|
+
clone requires a new checkpoint ID. Read-only retries and dry-run previews are
|
|
480
|
+
preserved. Deletion still requires confirmation unless `--force` is provided.
|
|
481
|
+
|
|
482
|
+
**Create options:** `--description`, `--include <paths>`, `--exclude <paths>`, `--no-env`
|
|
483
|
+
**Restore options:** `--no-files`, `--no-env`, `--no-overwrite`
|
|
484
|
+
|
|
485
|
+
### `stateset artifact`
|
|
486
|
+
|
|
487
|
+
Upload, download, and manage sandbox artifacts.
|
|
488
|
+
|
|
489
|
+
```bash
|
|
490
|
+
stateset artifact upload <sandbox-id> <path> # Upload artifact
|
|
491
|
+
stateset artifact list # List artifacts
|
|
492
|
+
stateset artifact get <id> # Get details
|
|
493
|
+
stateset artifact url <id> # Get download URL
|
|
494
|
+
stateset artifact download <sandbox-id> <id> <path> # Download artifact
|
|
495
|
+
stateset artifact rm <id> # Delete artifact
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
**Upload options:** `--type <content-type>`, `--expires <seconds>`, `--metadata <key=value>`
|
|
499
|
+
|
|
500
|
+
Upload, download, delete and URL commands accept global `--json` or a local
|
|
501
|
+
`--json` flag. Receipts retain server metadata, and URL receipts include the
|
|
502
|
+
expiry. An explicit global `--format` takes precedence. For example:
|
|
503
|
+
|
|
504
|
+
```bash
|
|
505
|
+
stateset --json artifact upload <sandbox-id> /workspace/result.json
|
|
506
|
+
stateset artifact download <sandbox-id> <artifact-id> /workspace/input.json --json
|
|
507
|
+
stateset artifact url <artifact-id> --expires 300 --json
|
|
508
|
+
stateset artifact rm <artifact-id> --force --json
|
|
509
|
+
stateset --dry-run artifact download <sandbox-id> <artifact-id> /workspace/input.json
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
Upload/download/delete do not add a CLI retry loop around the SDK operation.
|
|
513
|
+
After an uncertain upload, inspect `artifact list --sandbox <sandbox-id>`;
|
|
514
|
+
after an uncertain download, inspect the destination file before repeating.
|
|
515
|
+
Inspect `artifact get <id>` after uncertain deletion. The SDK transport retains
|
|
516
|
+
its own retry policy, so this does not guarantee exactly-once execution. Download
|
|
517
|
+
and delete require positive acknowledgements; upload checks receipt identity,
|
|
518
|
+
source path, size and checksum fields before reporting success. Dry runs submit
|
|
519
|
+
no mutations, and deletion requires confirmation unless `--force` is supplied.
|
|
520
|
+
Metadata entries require a nonempty key and `=`; values may be empty or contain
|
|
521
|
+
additional equals signs.
|
|
522
|
+
|
|
523
|
+
Controller-managed downloads check the recorded size and SHA-256 checksum before
|
|
524
|
+
writing any bytes into the target sandbox. Invalid metadata, truncated objects
|
|
525
|
+
and altered content fail without issuing a sandbox write. Recorded sizes over
|
|
526
|
+
`ARTIFACT_MAX_BYTES` (default 100 MiB) are rejected before fetching the object.
|
|
527
|
+
Legacy records with invalid size or SHA-256 metadata must be repaired or the
|
|
528
|
+
artifact uploaded again. These checks verify fetched bytes against stored
|
|
529
|
+
metadata; a successful acknowledgement does not independently verify the final
|
|
530
|
+
sandbox file or make a write atomic.
|
|
531
|
+
|
|
532
|
+
Artifact expiry is checked before fetching a sandbox download and again before
|
|
533
|
+
its write is dispatched. Expired artifacts cannot receive new download URLs;
|
|
534
|
+
metadata inspection and deletion remain available. S3/GCS URLs are capped at the
|
|
535
|
+
artifact deadline, and `expires_in` reports the usable whole seconds remaining
|
|
536
|
+
after signing and provider time rounding. Requests with less than one usable
|
|
537
|
+
second remaining are rejected. For expiring artifacts on Azure/local storage,
|
|
538
|
+
use `artifact download`: the current shared SAS/file URL implementations cannot
|
|
539
|
+
bind a new URL to that artifact's deadline, so direct URL creation is refused.
|
|
540
|
+
Non-expiring artifacts retain their existing provider-specific URL behavior.
|
|
541
|
+
|
|
542
|
+
These access checks do not revoke previously issued URLs or downloaded copies.
|
|
543
|
+
A sandbox write already in flight may finish after the expiry deadline. Artifact
|
|
544
|
+
lists filter expired entries; expiry enforcement does not depend on the cleanup
|
|
545
|
+
job having deleted the stored object.
|
|
546
|
+
|
|
547
|
+
Artifact deletion and tunnel closure verify permissions against their source
|
|
548
|
+
sandbox using a strict lookup. A lookup failure or incomplete/mismatched source
|
|
549
|
+
response returns `503 SERVICE_UNAVAILABLE` with reason `source_lookup_failed`;
|
|
550
|
+
the resource is not deleted and no deletion webhook is emitted. Retry after the
|
|
551
|
+
lookup service recovers. A source confirmed absent retains the existing
|
|
552
|
+
organization-level resource policy; this check does not add creator ownership
|
|
553
|
+
for resources that outlive their sandbox.
|
|
554
|
+
|
|
555
|
+
### `stateset session`
|
|
556
|
+
|
|
557
|
+
Orchestrate long-running agent sessions with budget controls.
|
|
558
|
+
|
|
559
|
+
```bash
|
|
560
|
+
stateset session create [options] # Create agent session
|
|
561
|
+
stateset session list # List sessions
|
|
562
|
+
stateset session get <id> # Get session details
|
|
563
|
+
stateset session start <id> # Start session
|
|
564
|
+
stateset session pause <id> # Pause session
|
|
565
|
+
stateset session resume <id> # Resume session
|
|
566
|
+
stateset session stop <id> # Stop gracefully
|
|
567
|
+
stateset session cancel <id> # Cancel immediately
|
|
568
|
+
stateset session exec <id> <command...> # Execute an argument vector in session
|
|
569
|
+
stateset --json session run --stop-on-exit -- node /workspace/task.js
|
|
570
|
+
stateset session exec <id> --json -- node /workspace/task.js
|
|
571
|
+
stateset --dry-run session run -- node /workspace/task.js
|
|
572
|
+
stateset session events <id> # List session events
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
`session exec` and `session run <command...>` preserve confirmed remote exit codes
|
|
576
|
+
from 0 through 255. Missing or uncertain execution results return status 1;
|
|
577
|
+
inspect session events before submitting the command again. JSON mode retains the
|
|
578
|
+
execution receipt, including output and outcome metadata, without interleaving raw
|
|
579
|
+
command output. `session run` returns its complete session/execution envelope.
|
|
580
|
+
|
|
581
|
+
Session creation, start, pause, resume, stop, cancellation and execution have no
|
|
582
|
+
additional CLI retry loop around their SDK operation. The SDK retains its transport
|
|
583
|
+
policy, so this does not guarantee exactly-once execution. Inspect `session list`,
|
|
584
|
+
`session get <id>` and `session events <id>` after an uncertain response. A stop or
|
|
585
|
+
cancellation acknowledgement confirms acceptance, not observed termination.
|
|
586
|
+
|
|
587
|
+
Global `--dry-run` previews session run/connect/create/start/pause/resume/stop/
|
|
588
|
+
cancel/exec/heartbeat/keepalive without initializing the API client, changing local
|
|
589
|
+
context or starting heartbeat timers. Run/exec previews show argument counts and
|
|
590
|
+
omit command contents and environment values.
|
|
591
|
+
|
|
592
|
+
**Create options:**
|
|
593
|
+
|
|
594
|
+
| Flag | Description |
|
|
595
|
+
|------|-------------|
|
|
596
|
+
| `-n, --name <name>` | Session name |
|
|
597
|
+
| `-d, --description <desc>` | Description |
|
|
598
|
+
| `--cost-cap <cents>` | Cost cap in cents (e.g., 500 = $5) |
|
|
599
|
+
| `--iteration-limit <n>` | Max iterations |
|
|
600
|
+
| `--duration-limit <seconds>` | Max duration |
|
|
601
|
+
| `--cpus <cpus>` | CPU allocation (default: 2) |
|
|
602
|
+
| `--memory <memory>` | Memory allocation (default: 4Gi) |
|
|
603
|
+
|
|
604
|
+
### `stateset tunnel`
|
|
605
|
+
|
|
606
|
+
Expose sandbox services via tunnels.
|
|
607
|
+
|
|
608
|
+
```bash
|
|
609
|
+
stateset tunnel open <sandbox-id> # Create tunnel (default port 8080)
|
|
610
|
+
stateset tunnel list <sandbox-id> # List active tunnels
|
|
611
|
+
stateset tunnel close <tunnel-id> # Close tunnel
|
|
612
|
+
```
|
|
613
|
+
|
|
614
|
+
**Open options:** `-p, --port <port>`, `--protocol <http|https>`, `--expires-in <seconds>`, `--idempotency-key <key>`
|
|
615
|
+
|
|
616
|
+
Tunnel open/list/close accept global `--json` or a local `--json` flag. Open
|
|
617
|
+
receipts retain the tunnel ID, target sandbox, port, protocol, expiry, URL and
|
|
618
|
+
any token supplied by the server. List JSON retains its `{ "tunnels": [...] }`
|
|
619
|
+
envelope; close JSON retains the server acknowledgement. An explicit global
|
|
620
|
+
`--format` takes precedence.
|
|
621
|
+
|
|
622
|
+
```bash
|
|
623
|
+
stateset --dry-run tunnel open <sandbox-id> --port 8080 --expires-in 600
|
|
624
|
+
stateset --json tunnel open <sandbox-id> --port 8080 --expires-in 600
|
|
625
|
+
stateset --json tunnel list <sandbox-id>
|
|
626
|
+
stateset tunnel close <tunnel-id> --json
|
|
627
|
+
```
|
|
628
|
+
|
|
629
|
+
Open/close do not add a CLI retry loop around SDK operations. After an uncertain
|
|
630
|
+
response, inspect `tunnel list <sandbox-id>` before repeating; the original
|
|
631
|
+
operation may already have applied. The SDK retains its transport retry policy,
|
|
632
|
+
so this does not guarantee exactly-once server execution. Both mutation commands
|
|
633
|
+
honor dry runs before client initialization and spinner startup. Invalid port,
|
|
634
|
+
protocol or TTL values are rejected locally; TTL accepts 60 through 86400 seconds,
|
|
635
|
+
and the deployment can cap it further.
|
|
636
|
+
|
|
637
|
+
The updated API honors the SDK's tunnel-creation retry key when server-side
|
|
638
|
+
idempotency is enabled. It replays only a still-active matching tunnel receipt
|
|
639
|
+
after checking current permissions. Closed, expired or unavailable records are
|
|
640
|
+
refused without creating a replacement. With both tunnel and idempotency storage
|
|
641
|
+
in DB mode, records and retry reservations work across controller replicas and
|
|
642
|
+
survive creator restarts. Memory mode remains local to a replica. Shared records
|
|
643
|
+
do not transfer in-flight connections. Without an explicit key, a separate CLI
|
|
644
|
+
invocation uses a new key.
|
|
645
|
+
|
|
646
|
+
For recovery across CLI invocations, save an opaque key with the agent's task
|
|
647
|
+
before opening its tunnel, then pass it on the initial request and every retry:
|
|
648
|
+
|
|
649
|
+
```bash
|
|
650
|
+
stateset --json tunnel open <sandbox-id> --port 8080 --expires-in 600 --idempotency-key task-17-http
|
|
651
|
+
```
|
|
652
|
+
|
|
653
|
+
Keep the same credentials, API URL, sandbox, port, protocol, TTL and `--public`
|
|
654
|
+
setting. A retry through another client must preserve the JSON body, including
|
|
655
|
+
the CLI's explicit `protocol` and `public` fields. Keys accept 1 through 256
|
|
656
|
+
printable ASCII characters without whitespace; invalid keys are refused locally,
|
|
657
|
+
and dry runs preview the supplied key. The key is sent in the `Idempotency-Key`
|
|
658
|
+
header and is excluded from the JSON request body.
|
|
659
|
+
Use a different key for an intentionally separate operation. Inspect the tunnel
|
|
660
|
+
list after uncertain outcomes; a key added only after the initial request cannot
|
|
661
|
+
recover that earlier request. Protection requires a server with tunnel idempotency
|
|
662
|
+
enabled and lasts for its reservation window (currently 24 hours). Stale or
|
|
663
|
+
unavailable receipts return an error without selecting another key automatically.
|
|
664
|
+
|
|
665
|
+
Creation checks receipt identity and the selected sandbox/port/protocol, an HTTP(S)
|
|
666
|
+
URL and a future expiry before reporting success. Provided tokens must be nonempty,
|
|
667
|
+
printable ASCII without whitespace; legacy receipts may omit the token. These
|
|
668
|
+
checks do not probe forwarding or independently verify authentication. Close
|
|
669
|
+
requires a positive acknowledgement and reports acceptance, which does not
|
|
670
|
+
establish that every existing forwarded connection has ended. `--public` remains
|
|
671
|
+
a compatibility flag; the current controller still requires token authentication.
|
|
672
|
+
|
|
673
|
+
### `stateset pool`
|
|
674
|
+
|
|
675
|
+
Monitor the warm pod pool.
|
|
676
|
+
|
|
677
|
+
```bash
|
|
678
|
+
stateset pool stats # Get pool statistics
|
|
679
|
+
stateset pool watch # Watch stats in real-time
|
|
680
|
+
stateset pool watch --interval 2 # Custom refresh interval
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
### `stateset deploy`
|
|
684
|
+
|
|
685
|
+
Deploy to Kubernetes via cloud provider overlays.
|
|
686
|
+
|
|
687
|
+
```bash
|
|
688
|
+
stateset deploy aws # Deploy AWS overlay
|
|
689
|
+
stateset deploy gcp --dry-run # Dry-run GCP overlay
|
|
690
|
+
stateset deploy azure --preflight --wait # Full deploy with checks
|
|
691
|
+
```
|
|
692
|
+
|
|
693
|
+
**Options:** `--kubeconfig`, `--context`, `--namespace`, `--dry-run`, `--preflight`, `--wait`, `--smoke`, `--post-check`
|
|
694
|
+
|
|
695
|
+
### `stateset doctor`
|
|
696
|
+
|
|
697
|
+
Diagnose CLI configuration and API connectivity.
|
|
698
|
+
|
|
699
|
+
```bash
|
|
700
|
+
stateset doctor # Basic health check
|
|
701
|
+
stateset doctor --full # Deep diagnostics
|
|
702
|
+
stateset doctor --cluster # Include Kubernetes checks
|
|
703
|
+
stateset doctor --api # Check dashboard endpoints
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
### `stateset health`
|
|
707
|
+
|
|
708
|
+
Platform-wide health snapshot.
|
|
709
|
+
|
|
710
|
+
```bash
|
|
711
|
+
stateset health # Quick platform status
|
|
712
|
+
stateset health --grade # Include readiness grade
|
|
713
|
+
stateset health --cluster # Include Kubernetes checks
|
|
714
|
+
```
|
|
715
|
+
|
|
716
|
+
### `stateset grade`
|
|
717
|
+
|
|
718
|
+
Compute platform readiness grade (A+ through F).
|
|
719
|
+
|
|
720
|
+
```bash
|
|
721
|
+
stateset grade # Compute grade
|
|
722
|
+
stateset grade --minimum A- # Fail if below A-
|
|
723
|
+
stateset grade --cluster --json # Full check, JSON output
|
|
724
|
+
```
|
|
725
|
+
|
|
726
|
+
A+ also requires a fresh signed evidence bundle with a separately trusted
|
|
727
|
+
Ed25519 public key. Its API URL, Kubernetes context/namespace and immutable
|
|
728
|
+
controller/runtime images must match the selected live target. Use
|
|
729
|
+
`--evidence-report`, `--evidence-public-key`, `--context` and `--namespace` to
|
|
730
|
+
select those inputs. See [execution readiness](../docs/EXECUTION_READINESS.md)
|
|
731
|
+
for the full certification requirements.
|
|
732
|
+
|
|
733
|
+
## JSON Output
|
|
734
|
+
|
|
735
|
+
Most commands support `--json` for machine-readable output, useful for scripting:
|
|
736
|
+
|
|
737
|
+
```bash
|
|
738
|
+
stateset sandbox list --json | jq '.[0].id'
|
|
739
|
+
stateset pool stats --json
|
|
740
|
+
stateset grade --json
|
|
741
|
+
```
|
|
742
|
+
|
|
743
|
+
## Development
|
|
744
|
+
|
|
745
|
+
For prepared resident AI workers, `sandboxctl delegate --stdin` keeps a
|
|
746
|
+
conversation open under the normal task deadline. `task-chat <task-id>` reads
|
|
747
|
+
its model, thread, progress and curated messages; `task-message <task-id>
|
|
748
|
+
'message'` starts or natively steers a turn. `task-interrupt <task-id>` interrupts
|
|
749
|
+
the pinned turn while preserving the worker. Save the returned request ID and
|
|
750
|
+
SHA-256; use `task-message-receipt <task-id> <request-id> --sha256 <hash>` after
|
|
751
|
+
uncertain delivery, rather than repeating the message.
|
|
752
|
+
|
|
753
|
+
In `sandboxctl tui --task <task-id>`, **s** opens the conversation, **i** composes,
|
|
754
|
+
**Enter** sends, and **x** reviews an interrupt. Reopening the saved task reconnects
|
|
755
|
+
without launching another worker. `--read-only` disables these writes. See the
|
|
756
|
+
[resident Codex worker](../examples/codex-agent/README.md#persistent-conversations-and-live-steering)
|
|
757
|
+
for preparation, bounded lifetime and acknowledgement semantics.
|
|
758
|
+
**c** opens control receipts; **Enter** verifies the selected UUID and hash.
|
|
759
|
+
**d** restores a verified rejected draft into an empty composer for review;
|
|
760
|
+
worker/provider rejections require this explicit action. Review the previous
|
|
761
|
+
attempt for effects before sending a new message. Unknown delivery cannot be
|
|
762
|
+
restored. **Delete** reviews forgetting only the selected draft's local text;
|
|
763
|
+
**y** confirms and **Escape** cancels. Saved intents and pending receipt checks
|
|
764
|
+
remain available. Read-only mode blocks restoration and disposal.
|
|
765
|
+
Pending messages and interrupts are checked fairly, at most two per automatic
|
|
766
|
+
refresh, even after the worker's recent-request list rolls over. The footer
|
|
767
|
+
shows pending receipts and active checks. **r** during a read queues one
|
|
768
|
+
follow-up refresh, including after switching to another conversation. A missing
|
|
769
|
+
receipt remains pending; checking it never resends a control.
|
|
770
|
+
|
|
771
|
+
From the conversation, **b** opens saved result bundles without contacting the
|
|
772
|
+
sandbox, including when the worker or sandbox is unavailable. **Enter** verifies
|
|
773
|
+
the bundle and opens its artifacts; **Escape** returns through the bundle list
|
|
774
|
+
to the same conversation. **f** opens the task's files while the sandbox remains
|
|
775
|
+
available. Leaving either browser preserves the in-memory message draft. Both
|
|
776
|
+
browsers work in read-only mode. To retain declared artifacts, return to task
|
|
777
|
+
detail and use **c** after the worker stops and before sandbox expiry.
|
|
778
|
+
While composing, **Ctrl+B** opens saved bundles and **Ctrl+F** opens task files
|
|
779
|
+
without clearing or sending the draft; return and press **i** to resume editing.
|
|
780
|
+
**Escape** in the composer still cancels and clears the draft.
|
|
781
|
+
|
|
782
|
+
Press **z** in the conversation to review finishing an idle session, then **y**
|
|
783
|
+
to send one finish control or **Escape** to cancel. The worker must advertise
|
|
784
|
+
`finish_session: "idle-only-v1"`; older workers and active turns are refused.
|
|
785
|
+
Read-only mode blocks finish. The control makes no model call and leaves the
|
|
786
|
+
sandbox available. Wait for terminal worker exit before collecting with **c**
|
|
787
|
+
in task detail. Acceptance acknowledges the request, not exit or task quality.
|
|
788
|
+
|
|
789
|
+
CLI agents use `sandboxctl task-finish <task-id>` (or `--dry-run` to review),
|
|
790
|
+
then `task-message-receipt <task-id> <request-id> --sha256 <hash>` to recover a
|
|
791
|
+
lost acknowledgement. Never resend automatically. Observe terminal status with
|
|
792
|
+
`task <task-id> --wait`, then `collect <task-id>` before sandbox expiry.
|
|
793
|
+
|
|
794
|
+
```bash
|
|
795
|
+
cd cli
|
|
796
|
+
npm install
|
|
797
|
+
npm run dev -- sandbox list # Run locally via tsx
|
|
798
|
+
npm run build # Compile TypeScript
|
|
799
|
+
npm test # Run tests
|
|
800
|
+
npm run typecheck # Type-check without emitting
|
|
801
|
+
```
|
|
802
|
+
|
|
803
|
+
## License
|
|
804
|
+
|
|
805
|
+
MIT
|