@stateset/sandbox-cli 1.0.6 → 3.4.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 +123 -0
- package/LICENSE +22 -0
- package/README.md +940 -6
- package/dist/client.d.ts +789 -10
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +694 -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 +154 -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 +562 -108
- 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/swarm.d.ts +12 -0
- package/dist/commands/swarm.d.ts.map +1 -0
- package/dist/commands/swarm.js +288 -0
- package/dist/commands/swarm.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 +55 -0
- package/dist/commands/terminal.d.ts.map +1 -0
- package/dist/commands/terminal.js +438 -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/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/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 +169 -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/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 +116 -0
- package/dist/utils/template-create.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 +39 -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/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/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 +517 -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 +110 -0
- package/dist/workbench/model.d.ts.map +1 -0
- package/dist/workbench/model.js +249 -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 +2607 -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
CHANGED
|
@@ -8,7 +8,7 @@ Command-line interface for managing [StateSet Sandbox](https://github.com/states
|
|
|
8
8
|
npm install -g @stateset/sandbox-cli
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
Requires Node.js
|
|
11
|
+
Requires Node.js 20.19+ (20.x line) or 22.12+.
|
|
12
12
|
|
|
13
13
|
## Quick Start
|
|
14
14
|
|
|
@@ -18,13 +18,43 @@ stateset config setup
|
|
|
18
18
|
|
|
19
19
|
# Or configure manually
|
|
20
20
|
stateset config set-key sk_live_your_api_key
|
|
21
|
-
stateset config set-url https://api.stateset.
|
|
21
|
+
stateset config set-url https://api.sandbox.stateset.app
|
|
22
22
|
|
|
23
23
|
# Create a sandbox and run a command
|
|
24
24
|
stateset sandbox create --timeout 600
|
|
25
|
-
stateset sandbox exec <sandbox-id>
|
|
25
|
+
stateset sandbox exec <sandbox-id> -- echo hello world
|
|
26
26
|
```
|
|
27
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
|
+
|
|
28
58
|
## Configuration
|
|
29
59
|
|
|
30
60
|
The CLI stores configuration locally via [conf](https://github.com/sindresorhus/conf). Environment variables take precedence over stored values.
|
|
@@ -32,7 +62,7 @@ The CLI stores configuration locally via [conf](https://github.com/sindresorhus/
|
|
|
32
62
|
| Setting | Env Variable | Default |
|
|
33
63
|
|---------|-------------|---------|
|
|
34
64
|
| API Key | `STATESET_API_KEY` | — |
|
|
35
|
-
| API URL | `STATESET_API_URL` | `
|
|
65
|
+
| API URL | `STATESET_API_URL` (or `STATESET_BASE_URL`, as used by the SDKs) | `https://api.sandbox.stateset.app` |
|
|
36
66
|
| Default Timeout | `STATESET_DEFAULT_TIMEOUT_SECONDS` | `300` |
|
|
37
67
|
|
|
38
68
|
```bash
|
|
@@ -43,6 +73,404 @@ stateset config clear # Wipe all stored config
|
|
|
43
73
|
|
|
44
74
|
## Commands
|
|
45
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, agent names 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
|
+
|
|
125
|
+
To see what each sandbox is for, name the directories that hold your agent
|
|
126
|
+
records: `stateset tui --agents ./fleets --agents ~/desk`, or set
|
|
127
|
+
`STATESET_AGENT_DIRS` to a PATH-style list (`:` between entries, `;` on
|
|
128
|
+
Windows). Each directory and its immediate subdirectories are checked for
|
|
129
|
+
`fleet-state.json` (written by `examples/claude-agent/fleet.mjs`) and
|
|
130
|
+
`workbench.json` (`{ "benches": [{ "name", "sandbox_id", "terminal_id",
|
|
131
|
+
"error"?, "stopped"? }] }`). Only these local files are read, on every refresh:
|
|
132
|
+
each is stat'ed and parsed again only when it has changed, and nothing is
|
|
133
|
+
requested from the API for them.
|
|
134
|
+
|
|
135
|
+
Workbenches started with [`stateset workbench up`](#stateset-workbench) need
|
|
136
|
+
no flag. When the dashboard is started inside a git repository, the directory
|
|
137
|
+
where that repository's workbenches are recorded (`.git/stateset-workbench`,
|
|
138
|
+
shared by its worktrees) is scanned as well, from the moment it exists, in
|
|
139
|
+
addition to the `--agents` and `STATESET_AGENT_DIRS` directories. Every
|
|
140
|
+
`<name>.json` in it that is a workbench record adds one agent per sandbox:
|
|
141
|
+
named by its label (`feat-1`), grouped under the workbench's name, with the
|
|
142
|
+
phase `interactive` (ready), `creating`, `failed` (with the error) or
|
|
143
|
+
`stopped` (after `workbench down`, or when `down` found that the sandbox was
|
|
144
|
+
never created). A failed member stays `failed` after `down`. These records are
|
|
145
|
+
read under the same rules as the others: parsed only when changed, never when
|
|
146
|
+
larger than 8 MiB, and at most 200 files. Anything else in that directory is
|
|
147
|
+
ignored without a note. The workbenches of another repository are not found
|
|
148
|
+
this way; start the dashboard in that repository. A `workbench.json` in an
|
|
149
|
+
`--agents` directory may hold either format.
|
|
150
|
+
|
|
151
|
+
- The list gains `AGENT` and `PHASE` columns once a listed sandbox has a
|
|
152
|
+
record. They share the ID column's room, so IDs are shortened and long names
|
|
153
|
+
cut; panes under 46 columns keep the ID alone. `+N` counts further agents in
|
|
154
|
+
the same sandbox. Search matches agent, phase and fleet names.
|
|
155
|
+
- Enter adds the fleet or workbench name, task name, the first four lines of
|
|
156
|
+
the objective, phase, branch, pull request URL, cost, any error, and the
|
|
157
|
+
record's path to the sandbox details.
|
|
158
|
+
- `v` (also in the F2 menu) lists agents instead of sandboxes: every fleet
|
|
159
|
+
member and bench, grouped by fleet or workbench, with phase, branch and pull
|
|
160
|
+
request, and the sandbox's status or `not listed` when it is gone. `v` or
|
|
161
|
+
Esc returns.
|
|
162
|
+
- `*` marks likely duplicates and the title shows `dup:N`: two agents both
|
|
163
|
+
still working whose names are equal, or one contained in the other, after
|
|
164
|
+
lower-casing and dropping punctuation, spaces and common words (`the`, `a`,
|
|
165
|
+
`of`, `to`, ...). "Fix the Login-Redirect!" matches "fix_login redirect"
|
|
166
|
+
and "login redirect". Containment is plain, so a very short name such as
|
|
167
|
+
"ui" also matches "build"; treat the mark as a prompt to look. Details and
|
|
168
|
+
the agents view name the other agent of each pair. "Still working" comes
|
|
169
|
+
from the record alone: fleet phases `planned`, `prepared`, `dispatched` and
|
|
170
|
+
`dispatch_unknown`, benches without `stopped` or `error`, and workbench
|
|
171
|
+
members that are `interactive` or `creating`; finished agents are never
|
|
172
|
+
flagged. A stale record of an agent that died without
|
|
173
|
+
updating its file can therefore still be flagged; the agents view shows
|
|
174
|
+
whether its sandbox is still listed.
|
|
175
|
+
- A `fleet-state.json` or `workbench.json` that is unreadable, malformed or
|
|
176
|
+
not in a known format is skipped, and one dimmed line above the selection
|
|
177
|
+
summary counts the skipped files and names the first two. Control characters and terminal escape sequences are
|
|
178
|
+
removed from every value read from these files before it is drawn.
|
|
179
|
+
Press F2 or `:` for a searchable action menu with availability explanations.
|
|
180
|
+
It also works from sandbox details and keeps its original target selected.
|
|
181
|
+
Press `c` for connection diagnostics and full refresh errors. Delayed reads
|
|
182
|
+
mark old snapshots stale and block changes until a refresh succeeds.
|
|
183
|
+
Press `g` to launch a prepared agent command as a supervised worker and `w` to
|
|
184
|
+
monitor workers from this TUI, the API or MCP. In the launcher, Tab selects the
|
|
185
|
+
command, recovery name and runtime (default 300 seconds); Enter reviews all
|
|
186
|
+
settings before `y` starts one worker. Enter in the worker list reads logs; `v`
|
|
187
|
+
opens the result with outcome, exit details and bounded stdout/stderr; `d`
|
|
188
|
+
reviews stopping a worker. Agents use `sandboxctl spawn <id> --name child --
|
|
189
|
+
<argv...>`, `ps`, `logs`, `result <id> <process-id>` and `kill` for the same process IDs as the TUI.
|
|
190
|
+
Result refreshes retain the selected process and keep stale output visible after
|
|
191
|
+
read failures. Older servers show status and logs with an unverified outcome.
|
|
192
|
+
Worker log and result views validate stream identity and any process or sandbox
|
|
193
|
+
identity supplied by the server. Malformed base64 and output over 1 MiB decoded per
|
|
194
|
+
stream fail explicitly; accepted output is limited to the latest 16 KiB of decoded
|
|
195
|
+
bytes per stream. A failed TUI log refresh retains the last complete stdout/stderr
|
|
196
|
+
pair as stale. JSON `logs` reports `truncated` separately from `rotated` and
|
|
197
|
+
preserves the server's continuation offsets. Older chunks without process or
|
|
198
|
+
sandbox metadata rely on the pinned request; missing metadata does not verify identity.
|
|
199
|
+
Switching worker views discards obsolete responses and queues at most one refresh
|
|
200
|
+
for the latest requested view. The footer shows when that refresh is waiting.
|
|
201
|
+
Leaving or quitting cancels an obsolete worker-list read. Log and result reads
|
|
202
|
+
that cannot be cancelled must settle before another read starts; their late
|
|
203
|
+
output and errors cannot update a view you have left. Pending API reads recheck
|
|
204
|
+
the selected view before dispatch, and manual refresh respects the shared
|
|
205
|
+
rate-limit pause. None of these observation controls stop or restart workers.
|
|
206
|
+
Press `h` for saved execution history and receipts after a lost response.
|
|
207
|
+
Press `l` to delegate a task with an objective, parent ID, prepared command,
|
|
208
|
+
runtime and expected artifact paths. Enter reviews it; `y` dispatches once.
|
|
209
|
+
Press `m` for the task board across all sandboxes. Enter inspects a saved task;
|
|
210
|
+
`v` opens its worker result, `f` opens artifacts and `g` prepares a child task.
|
|
211
|
+
On the board, `/` finds literal words across task names, objectives, sandbox,
|
|
212
|
+
process and parent IDs. Enter applies; Escape cancels editing and restores the
|
|
213
|
+
previous query and selected task. `t` cycles all, active, attention, finished
|
|
214
|
+
and unobserved tasks. Saved history never counts as active; finished means an
|
|
215
|
+
observed zero process exit, not validated task quality. `p` focuses the selected
|
|
216
|
+
task's parent and its known descendants using saved links; `a` clears filters.
|
|
217
|
+
Home/End and PageUp/PageDown navigate the visible tasks. Filters stay within the
|
|
218
|
+
task board and do not change the sandbox search or a pinned task detail.
|
|
219
|
+
The board continues checking exited workers whose exit code is missing and
|
|
220
|
+
observations whose history could not be saved. Once resolved, unselected terminal
|
|
221
|
+
workers leave the polling rotation. Task detail refreshes only its pinned worker;
|
|
222
|
+
return to the board to monitor the fleet. Reads retain the existing retry delays
|
|
223
|
+
and shared rate-limit pause, and never repeat a worker launch.
|
|
224
|
+
|
|
225
|
+
Agents can read the same local journal with bounded JSON output:
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
./sandboxctl tasks --parent-task team-1 --sandbox <sandbox-id> --query 'review checkout' --limit 25
|
|
229
|
+
./sandboxctl tasks --family team-1 --query 'review' --limit 25
|
|
230
|
+
# Continue with the returned next_cursor and the same filters:
|
|
231
|
+
./sandboxctl tasks --family team-1 --query 'review' --limit 25 --cursor '<next_cursor>'
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
`total` counts all current matches before pagination. Pages default to 100
|
|
235
|
+
receipts (maximum 1000); `next_cursor: null` ends traversal. `--parent-task`
|
|
236
|
+
selects direct children; `--family` includes the anchor and all known descendants,
|
|
237
|
+
as in TUI family focus, even across sandboxes and through intermediate tasks
|
|
238
|
+
excluded by other filters. Filters combine with AND. Search matches literal,
|
|
239
|
+
case-insensitive words in metadata. Empty or malformed exact IDs are rejected.
|
|
240
|
+
The SDK, CLI, TUI and MCP share search and family traversal. CLI/MCP cursors
|
|
241
|
+
are interchangeable with the same journal and filters. Ordering is newest first,
|
|
242
|
+
with a stable task-ID tie-breaker. Newer inserts do not shift later pages;
|
|
243
|
+
pagination is not a snapshot, so totals and matching metadata may change.
|
|
244
|
+
Restart from the first page to discover new arrivals. These filters read saved
|
|
245
|
+
metadata and do not contact workers or launch tasks.
|
|
246
|
+
|
|
247
|
+
Open an agent's saved work directly in a terminal pane:
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
./sandboxctl tui --task <saved-task-id> --read-only
|
|
251
|
+
./sandboxctl tui --task-family team-1
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Choose one startup focus. The task detail pins the exact saved ID; a missing
|
|
255
|
+
receipt never opens an unrelated task. Family focus includes known descendants
|
|
256
|
+
across sandboxes. Both use the configured local journal and work independently
|
|
257
|
+
of the sandbox list filter. Receipts render before remote reads finish; expired
|
|
258
|
+
or unavailable workers still show their saved metadata and archived bundles.
|
|
259
|
+
Startup focus never launches a worker. Quit leaves existing workers running.
|
|
260
|
+
|
|
261
|
+
Shared task discovery uses the server registry, available on controllers with
|
|
262
|
+
migration 067 and the registry release:
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
./sandboxctl --dry-run registry register <saved-task-uuid>
|
|
266
|
+
./sandboxctl registry register <saved-task-uuid>
|
|
267
|
+
./sandboxctl registry list --limit 25
|
|
268
|
+
./sandboxctl registry get <task-uuid>
|
|
269
|
+
./sandboxctl registry grant <task-uuid> <organization-user-uuid> --role viewer
|
|
270
|
+
./sandboxctl registry grants <task-uuid>
|
|
271
|
+
./sandboxctl registry revoke <task-uuid> <organization-user-uuid>
|
|
272
|
+
./sandboxctl tui --registry
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
Registration publishes curated metadata from the private journal without starting
|
|
276
|
+
a worker or sharing command arguments/environment. Server parents must already
|
|
277
|
+
be registered task UUIDs; local `team-*` family labels cannot authorize children.
|
|
278
|
+
`list` also accepts `--root-task`, `--parent-task` and `--cursor`; keep filters
|
|
279
|
+
unchanged while traversing pages. Shared readers need no copy of the journal.
|
|
280
|
+
The root owner grants viewer/operator access to the whole family and future
|
|
281
|
+
descendants; sandbox execution permissions are checked separately.
|
|
282
|
+
|
|
283
|
+
In the TUI, search for **registry** in F2, or press `u` from a saved task. Enter
|
|
284
|
+
opens metadata, `n`/`b` page, `f` focuses a family and `a` clears that filter.
|
|
285
|
+
From details, `p` reviews registration from a private receipt, `g` reviews a
|
|
286
|
+
grant and `d` reviews revoking the selected principal. Enter reviews the form;
|
|
287
|
+
`y` confirms and Escape cancels. `--read-only` disables all three changes.
|
|
288
|
+
Unknown write outcomes require a fresh `get`/`grants` read before another
|
|
289
|
+
review; writes are never automatically resent. Registry status does not prove a
|
|
290
|
+
worker is running. Older controllers show an explicit unavailable message.
|
|
291
|
+
|
|
292
|
+
For multi-file inputs, press `i` in workspace files or search **inputs** in F2.
|
|
293
|
+
Prepare a JSON array of `{path, source}` entries; sources resolve relative to
|
|
294
|
+
the manifest. `input-batch plan <sandbox-id> <manifest.json>` saves a private
|
|
295
|
+
receipt without remote calls. Review its mapping, then run
|
|
296
|
+
`input-batch upload <batch-id> --sha256 <manifest-sha256>` (global `--dry-run`
|
|
297
|
+
previews that upload). `input-batch inspect` verifies attempted files read-only.
|
|
298
|
+
The TUI uses `c` to review, `y` to confirm and `v` to inspect; paste a saved batch
|
|
299
|
+
UUID and manifest hash to reopen it. Read-only mode blocks planning and upload.
|
|
300
|
+
|
|
301
|
+
Limits are 32 files, 5 MiB/file and 20 MiB total. Logical paths map to independent
|
|
302
|
+
private remote files; a directory tree is not extracted. Keep the returned
|
|
303
|
+
actual paths for your worker. Recovery checks all earlier attempts and uploads
|
|
304
|
+
only never-attempted files. Unverified attempts block continuation. Share the
|
|
305
|
+
private `STATESET_INPUT_BATCH_DIR` across parent entry points, separating accounts.
|
|
306
|
+
See the [batch workflow](../docs/SANDBOX_WORKBENCH.md#multi-file-input-batches).
|
|
307
|
+
|
|
308
|
+
Attach that batch with `delegate <sandbox-id> --input-batch <uuid>
|
|
309
|
+
--input-sha256 <manifest-hash> --objective 'Analyze inputs' -- <prepared argv>`.
|
|
310
|
+
Global `--dry-run` previews the attachment offline. In the TUI, `g` in a verified
|
|
311
|
+
batch opens delegation with both fields filled in. Each CLI `team-launch`
|
|
312
|
+
member may set `input_batch: {batch_id, manifest_sha256}` as well.
|
|
313
|
+
|
|
314
|
+
`{{input:logical/path}}` resolves to a reviewed remote input in exact argv.
|
|
315
|
+
The parent checks the pinned files immediately before dispatch; changed or
|
|
316
|
+
unavailable bytes leave a `not_started` receipt and start no worker. Children
|
|
317
|
+
receive `input_batch` and `input_binding_sha256` in `STATESET_TASK_FILE`, with
|
|
318
|
+
no local source paths. A current integrity check at consumption time remains
|
|
319
|
+
the prepared worker's responsibility.
|
|
320
|
+
The launch also pins the reviewed hash as `STATESET_TASK_INPUT_BINDING_SHA256`.
|
|
321
|
+
The [standalone worker wrapper](../examples/verified-worker/README.md) checks
|
|
322
|
+
that pin and the actual bytes before invoking any prepared command.
|
|
323
|
+
|
|
324
|
+
For OpenAI CLI workers, the [Codex adapter](../examples/codex-agent/README.md)
|
|
325
|
+
reads the same task contract and writes structured results plus curated run
|
|
326
|
+
evidence. Prepare Codex and its authentication inside the sandbox first; the
|
|
327
|
+
adapter preserves its configured model and does not copy the host login.
|
|
328
|
+
Unavailable task polling backs off from 10 to 120 seconds; `r` retries the selected
|
|
329
|
+
task. A server rate limit pauses remote reads across the TUI, including manual
|
|
330
|
+
refresh, while local receipts and archived results remain available.
|
|
331
|
+
Agents use `sandboxctl delegate <id> --objective "Review changes" --parent-task
|
|
332
|
+
team-1 --artifact result.json -- agent --task-file '{task_file}'`, followed by
|
|
333
|
+
`tasks` and `task <task-id>`. The worker must already be installed and configured.
|
|
334
|
+
For a parent that needs a bounded completion check:
|
|
335
|
+
|
|
336
|
+
```bash
|
|
337
|
+
./sandboxctl task <task-id> --wait --wait-timeout 60 --poll-interval 2
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
The watcher makes sequential identity-checked reads and returns JSON with
|
|
341
|
+
`state`, `polls`, the last `observation` when available, and
|
|
342
|
+
`task_quality: not_evaluated`. States are `terminal`, `timeout`, `aborted`, and
|
|
343
|
+
`unavailable`. Exit codes are 0 for an observed zero exit, 1 for a failed or
|
|
344
|
+
unavailable outcome, 124 for the watch deadline, and 130/143 on SIGINT/SIGTERM.
|
|
345
|
+
Timeout or cancellation stops watching and leaves the child running. Retry
|
|
346
|
+
`task --wait` with the same saved ID; never repeat `delegate` for recovery.
|
|
347
|
+
The watch deadline also bounds stalled HTTP reads. HTTP 429 pauses reads for
|
|
348
|
+
Retry-After (30 seconds by default, bounded to 1 second–24 hours) within the
|
|
349
|
+
watch deadline. Other read failures return unavailable immediately. A terminal
|
|
350
|
+
process exit does not validate artifact contents.
|
|
351
|
+
|
|
352
|
+
Launch a bounded team from a JSON array of prepared task inputs:
|
|
353
|
+
|
|
354
|
+
```bash
|
|
355
|
+
./sandboxctl --dry-run team-launch members.json --concurrency 3
|
|
356
|
+
./sandboxctl team-launch members.json --name 'Checkout reviewers' --concurrency 3
|
|
357
|
+
./sandboxctl team <team-id>
|
|
358
|
+
./sandboxctl team <team-id> --local
|
|
359
|
+
./sandboxctl tui --task-family team-<team-id>
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Each member supplies `sandbox_id`, `objective`, `command` (an argv array), and
|
|
363
|
+
optional `name`, `timeout_seconds`, `stdin` and `artifact_paths`. Omit
|
|
364
|
+
`parent_task_id`; the team generates a shared family. The runtime must already
|
|
365
|
+
be prepared in each sandbox. Teams support 1–16 tasks and 1–4 simultaneous
|
|
366
|
+
starts; concurrency limits dispatch, not the number of workers left running.
|
|
367
|
+
The CLI prints a `prepared` recovery anchor to stderr after saving every member
|
|
368
|
+
identity and before starting workers. Stdout contains the final JSON receipt.
|
|
369
|
+
`accepted` means starts were acknowledged; task correctness needs separate checks.
|
|
370
|
+
An uncertain start halts undispatched members while already dispatched members
|
|
371
|
+
remain independent. Recover with `team <team-id>`; never repeat `team-launch`.
|
|
372
|
+
`--local` reads historical receipts without contacting sandboxes. Set the same
|
|
373
|
+
absolute `STATESET_AGENT_TEAM_DIR` across parents; its default is
|
|
374
|
+
`.stateset-agent-teams` in the current directory. Family links are private
|
|
375
|
+
journal metadata and do not grant server access to another account's tasks.
|
|
376
|
+
|
|
377
|
+
For another parent to discover and monitor the team using only API access, use
|
|
378
|
+
the opt-in server registry:
|
|
379
|
+
|
|
380
|
+
```bash
|
|
381
|
+
./sandboxctl team-launch members.json --registered --concurrency 3
|
|
382
|
+
./sandboxctl registry observe <root-task-uuid> --timeout 30
|
|
383
|
+
./sandboxctl tui --registry-root <root-task-uuid> --read-only
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
The returned `team_id` is the server root UUID. Registration must finish before
|
|
387
|
+
any worker starts; save the prepared recovery anchor and inspect `team <id>`
|
|
388
|
+
after an uncertain response. Do not relaunch. A metadata coordinator anchors the
|
|
389
|
+
family and intentionally has no worker. The observer checks process identity
|
|
390
|
+
and command hashes and distinguishes missing, ambiguous, mismatched and
|
|
391
|
+
unavailable processes. It does not judge task correctness. In TUI registry
|
|
392
|
+
detail, press `v` to read live workers; registry-only startup needs no local task
|
|
393
|
+
receipts. Process access is authorized separately from registry family access.
|
|
394
|
+
`registry observe` supports `--limit` (1–100) and `--cursor`; follow returned
|
|
395
|
+
cursors and check `family_complete` before treating a page as the whole family.
|
|
396
|
+
|
|
397
|
+
Set `STATESET_AGENT_TASK_DIR` to the same absolute private journal directory in
|
|
398
|
+
the TUI, CLI and MCP server to share receipts; the default is
|
|
399
|
+
`.stateset-agent-tasks` under each process's working directory. Use a separate
|
|
400
|
+
journal for each account. Receipts survive parent restarts; sandbox files still
|
|
401
|
+
expire with their sandbox. An uncertain launch is inspected without replay.
|
|
402
|
+
Verified status changes are saved in the journal. After expiry or a live-read
|
|
403
|
+
failure, the board labels saved status as historical and keeps its timestamp
|
|
404
|
+
in task detail. Failed process exits show `FAILED | exit <code>`; exit zero
|
|
405
|
+
still requires artifact inspection. A failed history write is visible separately.
|
|
406
|
+
On the task board, `b` opens the result archive for the current family/search
|
|
407
|
+
and observed-state selection (up to 16 visible tasks). It lists saved bundle
|
|
408
|
+
metadata separately for each agent, including complete, partial, unavailable
|
|
409
|
+
and missing collections. Enter verifies the newest available bundle and its
|
|
410
|
+
files before showing artifacts. Esc returns through the preview, bundle list
|
|
411
|
+
and archive while preserving the selected agent. `r` refreshes local metadata.
|
|
412
|
+
Archive reads work during a stalled API poll, after sandbox expiry, and in
|
|
413
|
+
read-only mode. Metadata completeness does not establish file integrity or task
|
|
414
|
+
correctness; opening the bundle performs the integrity check. Collect artifacts
|
|
415
|
+
before sandbox expiry to make them available here.
|
|
416
|
+
|
|
417
|
+
In task detail, `c` reviews collecting declared artifacts into a new private
|
|
418
|
+
parent-side bundle, and `b` lists saved bundles. Enter verifies a bundle and
|
|
419
|
+
previews its text or binary metadata. These reads work after remote expiry;
|
|
420
|
+
collection must happen while the terminal worker and its files remain reachable.
|
|
421
|
+
Read-only TUI mode permits collection because it makes no remote mutations.
|
|
422
|
+
|
|
423
|
+
Agents use `sandboxctl collect <task-id>` (or `--dry-run collect` for its plan),
|
|
424
|
+
`bundles <task-id>` and `task-bundle <directory> --sha256 <saved-manifest-hash>`.
|
|
425
|
+
The last command verifies entirely offline without API credentials; add
|
|
426
|
+
`--artifact result.json` to return a verified artifact as base64.
|
|
427
|
+
Set `STATESET_AGENT_RESULT_DIR` to a shared absolute private root; the default
|
|
428
|
+
is `.stateset-agent-results` under the current working directory. Collection
|
|
429
|
+
is bounded to 5 MiB per file and 20 MiB total. A partial collection returns its
|
|
430
|
+
manifest with CLI exit 1. File integrity and task correctness are separate.
|
|
431
|
+
Agents use `sandboxctl history <id>` and `receipt <id> <execution-id>` to
|
|
432
|
+
retrieve status and output without rerunning the command.
|
|
433
|
+
Press `i` for a Python task with editable source, task name and runtime. Each
|
|
434
|
+
reviewed run gets its own workspace directory, source hash and saved source.
|
|
435
|
+
Press `f` to browse files, preview artifacts and review a local download with
|
|
436
|
+
its full path. Python runs in a fresh process; workspace files persist until expiry.
|
|
437
|
+
|
|
438
|
+
In workspace files, `u` opens a local input upload. Enter reviews the full
|
|
439
|
+
sandbox ID, generated destination, size and SHA-256; `y` uploads one file into
|
|
440
|
+
a new `/workspace/input-<uuid>` directory and verifies its remote bytes.
|
|
441
|
+
Text and binary files up to 5 MiB are supported. Local source symlinks, special
|
|
442
|
+
files and changes after review are refused. The terminal path editor accepts
|
|
443
|
+
ASCII paths; CLI uploads also accept Unicode paths. Read-only mode blocks uploads.
|
|
444
|
+
|
|
445
|
+
```bash
|
|
446
|
+
./sandboxctl --dry-run upload <sandbox-id> ./orders.csv
|
|
447
|
+
./sandboxctl upload <sandbox-id> ./orders.csv
|
|
448
|
+
# Save the returned remote_path, size and sha256 with the parent task.
|
|
449
|
+
./sandboxctl verify-input <sandbox-id> <remote-path> --size <bytes> --sha256 <hash>
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
An existing destination or uncertain directory creation prevents the file write.
|
|
453
|
+
No upload request is automatically repeated. If a response is lost, the error
|
|
454
|
+
retains the input plan and failing stage; `verify-input` or TUI `v` checks remote
|
|
455
|
+
bytes without uploading again. A failed verification does not prove the remote
|
|
456
|
+
file is absent. Inspect it before preparing another upload. Files expire with
|
|
457
|
+
their sandbox; the local source is not copied into the parent task journal.
|
|
458
|
+
|
|
459
|
+
Press `x` on a running sandbox to type or paste a shell command, review with
|
|
460
|
+
Enter and run with `y`. Read live stdout/stderr and exit status in a scrollable
|
|
461
|
+
result screen. `z` reviews cancellation, `r` recovers a saved receipt after a
|
|
462
|
+
disconnect, and `x` edits another command after completion. Commands run with `sh -lc` inside
|
|
463
|
+
the selected sandbox and are never automatically retried.
|
|
464
|
+
Press `b` to choose prepaid USD credits and continue to owner-authorized Stripe
|
|
465
|
+
Checkout in your browser. Agents can use `sandboxctl credits 25` for a JSON
|
|
466
|
+
billing link, or `stateset billing credits 25 --open` to open it directly.
|
|
467
|
+
Press `s` to review subscription plans or reactivate through owner billing.
|
|
468
|
+
Agents can use `sandboxctl subscribe --open` or `stateset billing subscribe --open`.
|
|
469
|
+
The browser handles plan selection and confirmation of recurring and usage charges.
|
|
470
|
+
|
|
471
|
+
See the [sandbox workbench guide](../docs/SANDBOX_WORKBENCH.md) for keyboard
|
|
472
|
+
controls, examples, resource limits and the local Docker isolation boundary.
|
|
473
|
+
|
|
46
474
|
### `stateset sandbox`
|
|
47
475
|
|
|
48
476
|
Manage sandbox environments.
|
|
@@ -68,6 +496,88 @@ stateset sandbox ls-files <id> # List directory contents
|
|
|
68
496
|
| `-m, --memory <memory>` | Memory limit | `--memory 1Gi` |
|
|
69
497
|
| `-i, --isolation <level>` | Isolation level | `--isolation gvisor` |
|
|
70
498
|
| `-e, --env <KEY=VALUE>` | Environment variables (repeatable) | `-e FOO=bar -e BAZ=qux` |
|
|
499
|
+
| `--template <id>` | Built-in template to create from, with its files and setup commands if it has any | `--template python-data-science` |
|
|
500
|
+
| `--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` |
|
|
501
|
+
| `--json` | Print the created sandbox as JSON | `--json` |
|
|
502
|
+
|
|
503
|
+
**Templates.** `--template <id>` creates the sandbox from any built-in template;
|
|
504
|
+
`stateset template list` shows the ids and `stateset template describe <id>` what
|
|
505
|
+
each one sets. `stateset run` takes the same flag.
|
|
506
|
+
|
|
507
|
+
```bash
|
|
508
|
+
stateset sandbox create --template claude-code
|
|
509
|
+
stateset sandbox create --template claude-code --timeout 900 --cpus 1 -e FOO=bar
|
|
510
|
+
stateset --json sandbox create --template claude-code | jq -r '.id, .template'
|
|
511
|
+
stateset run --template claude-code -- claude --version
|
|
512
|
+
stateset sandbox create --template python-data-science # writes files, runs pip install
|
|
513
|
+
stateset run --template node-basic -- node index.js
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
- The id is sent as typed in the `template` field of `POST /sandbox/create`.
|
|
517
|
+
- The template supplies the image and the defaults for CPUs, memory, timeout and
|
|
518
|
+
env. `--cpus`, `--memory` and `--timeout` replace the template's values, `-e`
|
|
519
|
+
entries are merged over its env, and `run --image` replaces its image.
|
|
520
|
+
- **Templates with setup.** Eight built-in templates write files or run setup
|
|
521
|
+
commands (the `Files` and `Setup Commands` sections of `template describe`):
|
|
522
|
+
`python-basic`, `node-basic`, `go-basic`, `rust-basic`, `node-express-api`,
|
|
523
|
+
`python-data-science`, `python-llm` and `devops-tools`. `POST /sandbox/create`
|
|
524
|
+
refuses them with a 400 that names `POST /sandbox/create-from-template`, and
|
|
525
|
+
the CLI then sends the same options to that route. `GET /templates` does not
|
|
526
|
+
say which kind a template is, so the CLI learns it from that 400, which creates
|
|
527
|
+
nothing; any other error is reported as it is, and neither request is sent a
|
|
528
|
+
second time by the CLI.
|
|
529
|
+
- Setup runs inside the create request. The spinner says so (`Creating sandbox
|
|
530
|
+
and running the setup of template <id> ...; waiting up to 510s...`): the API
|
|
531
|
+
allows one setup command 300 seconds, so the default 210 second startup wait
|
|
532
|
+
becomes 510. A `--startup-timeout` you give is used as the whole wait.
|
|
533
|
+
- The template route has no field for `--isolation`, `--desktop-os` (other than
|
|
534
|
+
`linux`) or `--credential`. With a template that has setup they are refused by
|
|
535
|
+
name before that route is called, and no sandbox is created. `--timeout`,
|
|
536
|
+
`--cpus`, `--memory`, `-e`, `--durable`, `--resource-class`, the egress and
|
|
537
|
+
budget flags and `run --image` are sent.
|
|
538
|
+
- **A setup step that fails does not undo the create.** The API keeps the
|
|
539
|
+
sandbox, running and billed, and lists the failed steps. `sandbox create`
|
|
540
|
+
prints the sandbox, then on stderr each step in the API's words (`Setup command
|
|
541
|
+
exited 1: pip install ...`, `Template files were not written: ...`) and that the
|
|
542
|
+
sandbox was kept, and exits 1; `--json` carries the steps as `warnings`.
|
|
543
|
+
`run` does not run the command: it stops the sandbox (or keeps it with
|
|
544
|
+
`--keep`), says which, and exits 1.
|
|
545
|
+
- If the template route times out, loses its connection or answers 5xx, the CLI
|
|
546
|
+
does not send it again: the sandbox may exist with its setup still running, so
|
|
547
|
+
look at `stateset sandbox list` before creating another.
|
|
548
|
+
- Without `--timeout`, a create with `--template` sends no timeout, so the
|
|
549
|
+
template's applies (3600 seconds for `claude-code`) and not the profile's default
|
|
550
|
+
timeout. Without `--template` the profile default is sent as before.
|
|
551
|
+
- A refusal is shown in the API's words. An unknown id is `Template "<id>" not
|
|
552
|
+
found`.
|
|
553
|
+
- The create response does not name the template, so the `Template:` line and the
|
|
554
|
+
`template` key of `--json` repeat the id that was sent. `run --json` carries the
|
|
555
|
+
same `template` key. Both are absent when no template was asked for.
|
|
556
|
+
|
|
557
|
+
### `stateset terminal` and `stateset ssh`
|
|
558
|
+
|
|
559
|
+
A terminal is a real shell (or any command) on a pseudo-terminal in the
|
|
560
|
+
sandbox. It keeps running when you detach or lose the connection. See
|
|
561
|
+
[docs/TERMINAL_SESSIONS.md](../docs/TERMINAL_SESSIONS.md).
|
|
562
|
+
|
|
563
|
+
```bash
|
|
564
|
+
stateset ssh <id> # start a shell and attach
|
|
565
|
+
stateset ssh <id> -c "npm test" # run one command and exit
|
|
566
|
+
stateset ssh <id> --line-mode # old behaviour: each line is its own command
|
|
567
|
+
|
|
568
|
+
stateset terminal create <id> [command...] # start a terminal and attach (alias: stateset term)
|
|
569
|
+
stateset terminal create <id> -d --name build # start it detached and print its id
|
|
570
|
+
stateset terminal ls <id>
|
|
571
|
+
stateset terminal attach <id> <terminal-id> # --from-start replays all retained output
|
|
572
|
+
stateset terminal screen <id> <terminal-id> # print what it is displaying; --scrollback <n>, --json
|
|
573
|
+
stateset terminal search <id> <terminal-id> <text> # --case-sensitive, --limit <n>, --json
|
|
574
|
+
stateset terminal record <id> <terminal-id> -o session.cast # asciicast v2; --idle-time-limit <seconds>
|
|
575
|
+
stateset terminal kill <id> <terminal-id>
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
While attached, `Ctrl-]` detaches and leaves the terminal running. `screen`,
|
|
579
|
+
`search` and `record` need no attachment and work on a terminal someone else
|
|
580
|
+
(or an agent) is using.
|
|
71
581
|
|
|
72
582
|
### `stateset checkpoint`
|
|
73
583
|
|
|
@@ -83,6 +593,29 @@ stateset checkpoint diff <id-1> <id-2> # Compare two checkpoints
|
|
|
83
593
|
stateset checkpoint rm <id> # Delete checkpoint
|
|
84
594
|
```
|
|
85
595
|
|
|
596
|
+
Checkpoint create, restore, clone and delete accept global `--json` or a local
|
|
597
|
+
`--json` flag. Standard output contains one receipt; warnings remain on standard
|
|
598
|
+
error and in the receipt when supplied. An explicit global `--format` takes
|
|
599
|
+
precedence. For example:
|
|
600
|
+
|
|
601
|
+
```bash
|
|
602
|
+
stateset --json checkpoint create <sandbox-id> before-task --no-env
|
|
603
|
+
stateset checkpoint restore <sandbox-id> <checkpoint-id> --json
|
|
604
|
+
stateset checkpoint clone <checkpoint-id> task-copy --json
|
|
605
|
+
stateset checkpoint rm <checkpoint-id> --force --json
|
|
606
|
+
```
|
|
607
|
+
|
|
608
|
+
These four mutations do not add a CLI retry loop around the SDK operation.
|
|
609
|
+
After a lost response, inspect `checkpoint list` or `checkpoint get <id>` before
|
|
610
|
+
repeating capture, cloning or deletion. Inspect the target sandbox's files and
|
|
611
|
+
environment before repeating a restore. The SDK transport retains its retry
|
|
612
|
+
policy; this does not guarantee exactly-once server execution. Restore/delete
|
|
613
|
+
require a positive acknowledgement, which does not independently verify restored
|
|
614
|
+
contents or backend cleanup. Create/clone reject incomplete receipt identity or
|
|
615
|
+
summary fields before reporting success; create checks the source sandbox, and
|
|
616
|
+
clone requires a new checkpoint ID. Read-only retries and dry-run previews are
|
|
617
|
+
preserved. Deletion still requires confirmation unless `--force` is provided.
|
|
618
|
+
|
|
86
619
|
**Create options:** `--description`, `--include <paths>`, `--exclude <paths>`, `--no-env`
|
|
87
620
|
**Restore options:** `--no-files`, `--no-env`, `--no-overwrite`
|
|
88
621
|
|
|
@@ -101,6 +634,61 @@ stateset artifact rm <id> # Delete artifact
|
|
|
101
634
|
|
|
102
635
|
**Upload options:** `--type <content-type>`, `--expires <seconds>`, `--metadata <key=value>`
|
|
103
636
|
|
|
637
|
+
Upload, download, delete and URL commands accept global `--json` or a local
|
|
638
|
+
`--json` flag. Receipts retain server metadata, and URL receipts include the
|
|
639
|
+
expiry. An explicit global `--format` takes precedence. For example:
|
|
640
|
+
|
|
641
|
+
```bash
|
|
642
|
+
stateset --json artifact upload <sandbox-id> /workspace/result.json
|
|
643
|
+
stateset artifact download <sandbox-id> <artifact-id> /workspace/input.json --json
|
|
644
|
+
stateset artifact url <artifact-id> --expires 300 --json
|
|
645
|
+
stateset artifact rm <artifact-id> --force --json
|
|
646
|
+
stateset --dry-run artifact download <sandbox-id> <artifact-id> /workspace/input.json
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
Upload/download/delete do not add a CLI retry loop around the SDK operation.
|
|
650
|
+
After an uncertain upload, inspect `artifact list --sandbox <sandbox-id>`;
|
|
651
|
+
after an uncertain download, inspect the destination file before repeating.
|
|
652
|
+
Inspect `artifact get <id>` after uncertain deletion. The SDK transport retains
|
|
653
|
+
its own retry policy, so this does not guarantee exactly-once execution. Download
|
|
654
|
+
and delete require positive acknowledgements; upload checks receipt identity,
|
|
655
|
+
source path, size and checksum fields before reporting success. Dry runs submit
|
|
656
|
+
no mutations, and deletion requires confirmation unless `--force` is supplied.
|
|
657
|
+
Metadata entries require a nonempty key and `=`; values may be empty or contain
|
|
658
|
+
additional equals signs.
|
|
659
|
+
|
|
660
|
+
Controller-managed downloads check the recorded size and SHA-256 checksum before
|
|
661
|
+
writing any bytes into the target sandbox. Invalid metadata, truncated objects
|
|
662
|
+
and altered content fail without issuing a sandbox write. Recorded sizes over
|
|
663
|
+
`ARTIFACT_MAX_BYTES` (default 100 MiB) are rejected before fetching the object.
|
|
664
|
+
Legacy records with invalid size or SHA-256 metadata must be repaired or the
|
|
665
|
+
artifact uploaded again. These checks verify fetched bytes against stored
|
|
666
|
+
metadata; a successful acknowledgement does not independently verify the final
|
|
667
|
+
sandbox file or make a write atomic.
|
|
668
|
+
|
|
669
|
+
Artifact expiry is checked before fetching a sandbox download and again before
|
|
670
|
+
its write is dispatched. Expired artifacts cannot receive new download URLs;
|
|
671
|
+
metadata inspection and deletion remain available. S3/GCS URLs are capped at the
|
|
672
|
+
artifact deadline, and `expires_in` reports the usable whole seconds remaining
|
|
673
|
+
after signing and provider time rounding. Requests with less than one usable
|
|
674
|
+
second remaining are rejected. For expiring artifacts on Azure/local storage,
|
|
675
|
+
use `artifact download`: the current shared SAS/file URL implementations cannot
|
|
676
|
+
bind a new URL to that artifact's deadline, so direct URL creation is refused.
|
|
677
|
+
Non-expiring artifacts retain their existing provider-specific URL behavior.
|
|
678
|
+
|
|
679
|
+
These access checks do not revoke previously issued URLs or downloaded copies.
|
|
680
|
+
A sandbox write already in flight may finish after the expiry deadline. Artifact
|
|
681
|
+
lists filter expired entries; expiry enforcement does not depend on the cleanup
|
|
682
|
+
job having deleted the stored object.
|
|
683
|
+
|
|
684
|
+
Artifact deletion and tunnel closure verify permissions against their source
|
|
685
|
+
sandbox using a strict lookup. A lookup failure or incomplete/mismatched source
|
|
686
|
+
response returns `503 SERVICE_UNAVAILABLE` with reason `source_lookup_failed`;
|
|
687
|
+
the resource is not deleted and no deletion webhook is emitted. Retry after the
|
|
688
|
+
lookup service recovers. A source confirmed absent retains the existing
|
|
689
|
+
organization-level resource policy; this check does not add creator ownership
|
|
690
|
+
for resources that outlive their sandbox.
|
|
691
|
+
|
|
104
692
|
### `stateset session`
|
|
105
693
|
|
|
106
694
|
Orchestrate long-running agent sessions with budget controls.
|
|
@@ -114,10 +702,30 @@ stateset session pause <id> # Pause session
|
|
|
114
702
|
stateset session resume <id> # Resume session
|
|
115
703
|
stateset session stop <id> # Stop gracefully
|
|
116
704
|
stateset session cancel <id> # Cancel immediately
|
|
117
|
-
stateset session exec <id> <command
|
|
705
|
+
stateset session exec <id> <command...> # Execute an argument vector in session
|
|
706
|
+
stateset --json session run --stop-on-exit -- node /workspace/task.js
|
|
707
|
+
stateset session exec <id> --json -- node /workspace/task.js
|
|
708
|
+
stateset --dry-run session run -- node /workspace/task.js
|
|
118
709
|
stateset session events <id> # List session events
|
|
119
710
|
```
|
|
120
711
|
|
|
712
|
+
`session exec` and `session run <command...>` preserve confirmed remote exit codes
|
|
713
|
+
from 0 through 255. Missing or uncertain execution results return status 1;
|
|
714
|
+
inspect session events before submitting the command again. JSON mode retains the
|
|
715
|
+
execution receipt, including output and outcome metadata, without interleaving raw
|
|
716
|
+
command output. `session run` returns its complete session/execution envelope.
|
|
717
|
+
|
|
718
|
+
Session creation, start, pause, resume, stop, cancellation and execution have no
|
|
719
|
+
additional CLI retry loop around their SDK operation. The SDK retains its transport
|
|
720
|
+
policy, so this does not guarantee exactly-once execution. Inspect `session list`,
|
|
721
|
+
`session get <id>` and `session events <id>` after an uncertain response. A stop or
|
|
722
|
+
cancellation acknowledgement confirms acceptance, not observed termination.
|
|
723
|
+
|
|
724
|
+
Global `--dry-run` previews session run/connect/create/start/pause/resume/stop/
|
|
725
|
+
cancel/exec/heartbeat/keepalive without initializing the API client, changing local
|
|
726
|
+
context or starting heartbeat timers. Run/exec previews show argument counts and
|
|
727
|
+
omit command contents and environment values.
|
|
728
|
+
|
|
121
729
|
**Create options:**
|
|
122
730
|
|
|
123
731
|
| Flag | Description |
|
|
@@ -130,6 +738,172 @@ stateset session events <id> # List session events
|
|
|
130
738
|
| `--cpus <cpus>` | CPU allocation (default: 2) |
|
|
131
739
|
| `--memory <memory>` | Memory allocation (default: 4Gi) |
|
|
132
740
|
|
|
741
|
+
### `stateset swarm`
|
|
742
|
+
|
|
743
|
+
Create, see, watch and cancel swarms: one goal split into tasks with dependencies, as the
|
|
744
|
+
service keeps it (`/api/v1/swarms`, "Swarms" in [docs/API_REFERENCE.md](../docs/API_REFERENCE.md)).
|
|
745
|
+
The service stores the plan and what a coordinator reports about each task; it starts
|
|
746
|
+
and stops no sandbox, and neither do these commands: `create` stores a plan and runs
|
|
747
|
+
none of its tasks.
|
|
748
|
+
|
|
749
|
+
```bash
|
|
750
|
+
stateset swarm create --plan plan.json # Check the plan file, then store it as a swarm
|
|
751
|
+
stateset swarm create --plan plan.json --name "Swarm API" # Under this name
|
|
752
|
+
stateset swarm create --plan plan.json --json # The stored swarm with its tasks, as the API answers
|
|
753
|
+
stateset --dry-run swarm create --plan plan.json # Check the plan; send nothing
|
|
754
|
+
stateset swarm list # Newest first: id, name, status, created
|
|
755
|
+
stateset swarm list --status running --limit 50
|
|
756
|
+
stateset swarm list --json # { "swarms": [...], "next_cursor": null }
|
|
757
|
+
stateset swarm get <id> # Header line, then one row per task
|
|
758
|
+
stateset swarm get <id> --json # The swarm with its tasks, as the API answers
|
|
759
|
+
stateset swarm watch <id> # `get`, drawn again every 5 seconds until the swarm has ended
|
|
760
|
+
stateset swarm watch <id> --interval 30 # Look every 30 seconds
|
|
761
|
+
stateset swarm cancel <id> # Cancel the swarm and its unfinished tasks
|
|
762
|
+
stateset --dry-run swarm cancel <id> # Say what would be sent; send nothing
|
|
763
|
+
```
|
|
764
|
+
|
|
765
|
+
| Flag | Description |
|
|
766
|
+
|------|-------------|
|
|
767
|
+
| `--plan <file>` | `create`: the plan file, JSON (required) |
|
|
768
|
+
| `--name <name>` | `create`: the swarm's name (default: the plan's `name`, else the file's name without `.json`) |
|
|
769
|
+
| `--status <status>` | `list`: only `planned`, `running`, `completed`, `failed` or `cancelled` swarms |
|
|
770
|
+
| `--limit <n>` | `list`: the most swarms to show (default: 25). Above 100 the CLI reads further pages |
|
|
771
|
+
| `-i, --interval <seconds>` | `watch`: seconds between two looks, a positive integer (default: 5) |
|
|
772
|
+
| `--json` | `create`, `list`, `get`, `cancel`: print JSON instead of a table or a line; the global `--json` and `--format json` do the same |
|
|
773
|
+
|
|
774
|
+
`swarm create` reads a plan file, checks it and stores it as a swarm (`POST /swarms`). A
|
|
775
|
+
plan file is what [`examples/claude-agent/swarm-plan.mjs`](../examples/claude-agent/swarm-plan.mjs)
|
|
776
|
+
writes, or the same written by hand:
|
|
777
|
+
|
|
778
|
+
```json
|
|
779
|
+
{
|
|
780
|
+
"goal": "Give the controller a place to keep a swarm.",
|
|
781
|
+
"repository": { "path": "/home/me/app", "base": "4f2c1d9" },
|
|
782
|
+
"defaults": { "timeout_seconds": 3600 },
|
|
783
|
+
"sandbox": { "template": "claude-code", "memory": "4Gi", "cpus": "2" },
|
|
784
|
+
"tasks": [
|
|
785
|
+
{ "id": "schema", "name": "Schema", "objective": "Add the migration." },
|
|
786
|
+
{ "id": "routes", "name": "Routes", "objective": "Add the routes.", "depends_on": ["schema"] }
|
|
787
|
+
]
|
|
788
|
+
}
|
|
789
|
+
```
|
|
790
|
+
|
|
791
|
+
The plan is checked against the API's limits before anything is sent:
|
|
792
|
+
|
|
793
|
+
| Part of the plan | What it must be |
|
|
794
|
+
|------------------|-----------------|
|
|
795
|
+
| The file | At most 4 MB of JSON: an object with its list of tasks in `tasks` |
|
|
796
|
+
| The swarm's name | 1 to 128 characters, on one line and without control characters |
|
|
797
|
+
| `goal` | A string of 1 to 16000 characters, without a NUL character |
|
|
798
|
+
| `repository`, `defaults` | Each a JSON object of at most 16384 characters as JSON, without a NUL character, or left out |
|
|
799
|
+
| `tasks` | 1 to 50 tasks, each an object |
|
|
800
|
+
| 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 |
|
|
801
|
+
| A task's `name` | As the swarm's name |
|
|
802
|
+
| A task's `objective` | As `goal` |
|
|
803
|
+
| A task's `depends_on` | A list of ids of other tasks of the plan, or left out; the dependencies form no cycle |
|
|
804
|
+
|
|
805
|
+
The lengths of the name, the goal, a task's name and an objective are counted without
|
|
806
|
+
the spaces around them. A plan with problems is refused with exit status 1 and nothing is
|
|
807
|
+
sent, under `--dry-run` too. Stderr names the file, then has one line per problem, which
|
|
808
|
+
names the task it is about (at most 20 problems; a last line says how many more there
|
|
809
|
+
are):
|
|
810
|
+
|
|
811
|
+
```text
|
|
812
|
+
Plan file "plan.json" has 2 problems:
|
|
813
|
+
- Task 1: id "Bad_Id" is not kebab-case (lowercase letters and digits joined by single hyphens, at most 64 characters).
|
|
814
|
+
- Task "routes": depends_on names "nowhere", which is not the id of a task in this plan.
|
|
815
|
+
```
|
|
816
|
+
|
|
817
|
+
A file that does not exist, cannot be read, is over 4 MB or is not JSON is refused the
|
|
818
|
+
same way, in one line.
|
|
819
|
+
|
|
820
|
+
What is sent is the body of `POST /swarms`: the name, the goal, `repository` and
|
|
821
|
+
`defaults` as the plan has them, and of every task its `id` as `key`, its `name`, its
|
|
822
|
+
`objective` and its `depends_on`, each dependency once. `sandbox`, `union`, `max_local`,
|
|
823
|
+
a task's `files` and anything else the API has no field for are left out: the service
|
|
824
|
+
stores a plan, not how to run it. The swarm's name is `--name`, else the plan's own
|
|
825
|
+
`name`, else the name of the file without `.json` (`plans/run-7.json` is stored as
|
|
826
|
+
`run-7`).
|
|
827
|
+
|
|
828
|
+
```text
|
|
829
|
+
✔ Swarm "run-7" created: 0b9f6c1e-2f0a-4a51-9d3e-6a1f5a0c7e11
|
|
830
|
+
Follow it with: stateset swarm watch 0b9f6c1e-2f0a-4a51-9d3e-6a1f5a0c7e11
|
|
831
|
+
No sandbox was started: the service keeps the plan; a coordinator runs the tasks and reports them.
|
|
832
|
+
```
|
|
833
|
+
|
|
834
|
+
With `--json` the stored swarm is printed as the API answers it, with its id and its
|
|
835
|
+
tasks (`ready` when a task depends on nothing, `waiting` otherwise), and nothing else.
|
|
836
|
+
`stateset --dry-run swarm create --plan <file>` checks the plan, prints the name, the
|
|
837
|
+
number of tasks and the file, and sends nothing. `create` starts no sandbox and runs no
|
|
838
|
+
task: the swarm is `planned` until a coordinator reports a task, which the CLI does not
|
|
839
|
+
do, and it counts among the organization's unfinished swarms until it has ended or is
|
|
840
|
+
cancelled. `stateset swarm watch <id>` follows it from there. Creating is not
|
|
841
|
+
idempotent: the request is sent once, and running the command again stores a second
|
|
842
|
+
swarm.
|
|
843
|
+
|
|
844
|
+
`swarm list` prints `No swarms found` for an empty answer. When there are more swarms
|
|
845
|
+
than `--limit`, the table is followed by a line saying so, and `--json` carries the
|
|
846
|
+
API's `next_cursor` (`null` when the list is complete). A swarm in a list has no tasks.
|
|
847
|
+
|
|
848
|
+
`swarm get` prints the name, the status and the goal on one line, then a table of the
|
|
849
|
+
tasks: key, phase, branch, cost and blocked by.
|
|
850
|
+
|
|
851
|
+
```text
|
|
852
|
+
Swarm API (running): Give the controller a place to keep a swarm.
|
|
853
|
+
╔════════╤══════════╤══════════════╤════════╤════════════╗
|
|
854
|
+
║ Key │ Phase │ Branch │ Cost │ Blocked by ║
|
|
855
|
+
╟────────┼──────────┼──────────────┼────────┼────────────╢
|
|
856
|
+
║ schema │ accepted │ swarm/schema │ $0.95 │ - ║
|
|
857
|
+
╟────────┼──────────┼──────────────┼────────┼────────────╢
|
|
858
|
+
║ routes │ failed │ swarm/routes │ $12.34 │ - ║
|
|
859
|
+
╟────────┼──────────┼──────────────┼────────┼────────────╢
|
|
860
|
+
║ docs │ blocked │ - │ $0.00 │ routes ║
|
|
861
|
+
╚════════╧══════════╧══════════════╧════════╧════════════╝
|
|
862
|
+
```
|
|
863
|
+
|
|
864
|
+
The API stores a task's cost in cents (`cost_cents`); the table prints dollars, and
|
|
865
|
+
`--json` keeps the cents. The header shows the first 240 characters of the goal on one
|
|
866
|
+
line, with control characters replaced by `?`; `--json` has the goal whole.
|
|
867
|
+
|
|
868
|
+
`swarm watch` follows one swarm: it prints what `swarm get` prints, looks again every
|
|
869
|
+
`--interval` seconds, and ends on the first look that finds the swarm `completed`,
|
|
870
|
+
`failed` or `cancelled`, which may be the first one. That look is printed too, followed
|
|
871
|
+
by one line. Only a failed swarm is an error:
|
|
872
|
+
|
|
873
|
+
| The swarm | Last line | Exit status |
|
|
874
|
+
|-----------|-----------|-------------|
|
|
875
|
+
| `completed` | `Swarm "<name>" completed` | 0 |
|
|
876
|
+
| `cancelled` | `Swarm "<name>" was cancelled` | 0 |
|
|
877
|
+
| `failed` | On stderr: `Swarm "<name>" failed: <keys of the failed tasks>` | 1 |
|
|
878
|
+
|
|
879
|
+
In a terminal the screen is cleared before each look is drawn, and a line under the
|
|
880
|
+
table says how often the swarm is looked at, that Ctrl+C stops the watch, and when the
|
|
881
|
+
swarm was last read. When the output is not a terminal (a pipe, a CI log), nothing is
|
|
882
|
+
cleared, that line is left out, and the swarm is printed again only when what is printed
|
|
883
|
+
has changed: the log holds one table per change, not one per look. `watch` only reads,
|
|
884
|
+
and it has no `--json`: a script reads `swarm get <id> --json`. An error on any look,
|
|
885
|
+
the first or a later one, ends the watch as it ends `swarm get`.
|
|
886
|
+
|
|
887
|
+
`swarm cancel` marks the swarm and its unfinished tasks `cancelled` in the service and
|
|
888
|
+
prints the cancelled swarm with `--json`. It stops no sandbox: a coordinator still
|
|
889
|
+
running the swarm goes on until it is stopped where it runs. Cancelling a swarm that is
|
|
890
|
+
already cancelled succeeds. It does not ask for confirmation.
|
|
891
|
+
|
|
892
|
+
Errors are one line on stderr with exit status 1 (for a plan with problems, one more per
|
|
893
|
+
problem), and the request is not repeated:
|
|
894
|
+
|
|
895
|
+
| Answer | Line |
|
|
896
|
+
|--------|------|
|
|
897
|
+
| A plan with problems on `create`: nothing is sent | `Plan file "<file>" has <n> problems:`, then one line per problem |
|
|
898
|
+
| `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 |
|
|
899
|
+
| `400` on `create` (the service refuses a plan the check let through) | The API's message, which names the field |
|
|
900
|
+
| `404` on `get`, `watch` or `cancel` | `Swarm "<id>" not found` |
|
|
901
|
+
| `409` on `cancel` (the swarm is completed or failed) | The API's message, e.g. `Swarm is already completed; there is nothing to cancel.` |
|
|
902
|
+
| `404` on `list` or `create` | `This API has no swarm routes (a deployment without a database, or an older controller).` |
|
|
903
|
+
|
|
904
|
+
Any other error (a `--status` or an id the API refuses, an expired login) is reported
|
|
905
|
+
as for the other commands.
|
|
906
|
+
|
|
133
907
|
### `stateset tunnel`
|
|
134
908
|
|
|
135
909
|
Expose sandbox services via tunnels.
|
|
@@ -140,7 +914,110 @@ stateset tunnel list <sandbox-id> # List active tunnels
|
|
|
140
914
|
stateset tunnel close <tunnel-id> # Close tunnel
|
|
141
915
|
```
|
|
142
916
|
|
|
143
|
-
**Open options:** `-p, --port <port>`, `--protocol <http|https>`, `--expires-in <seconds>`
|
|
917
|
+
**Open options:** `-p, --port <port>`, `--protocol <http|https>`, `--expires-in <seconds>`, `--idempotency-key <key>`
|
|
918
|
+
|
|
919
|
+
Tunnel open/list/close accept global `--json` or a local `--json` flag. Open
|
|
920
|
+
receipts retain the tunnel ID, target sandbox, port, protocol, expiry, URL and
|
|
921
|
+
any token supplied by the server. List JSON retains its `{ "tunnels": [...] }`
|
|
922
|
+
envelope; close JSON retains the server acknowledgement. An explicit global
|
|
923
|
+
`--format` takes precedence.
|
|
924
|
+
|
|
925
|
+
```bash
|
|
926
|
+
stateset --dry-run tunnel open <sandbox-id> --port 8080 --expires-in 600
|
|
927
|
+
stateset --json tunnel open <sandbox-id> --port 8080 --expires-in 600
|
|
928
|
+
stateset --json tunnel list <sandbox-id>
|
|
929
|
+
stateset tunnel close <tunnel-id> --json
|
|
930
|
+
```
|
|
931
|
+
|
|
932
|
+
Open/close do not add a CLI retry loop around SDK operations. After an uncertain
|
|
933
|
+
response, inspect `tunnel list <sandbox-id>` before repeating; the original
|
|
934
|
+
operation may already have applied. The SDK retains its transport retry policy,
|
|
935
|
+
so this does not guarantee exactly-once server execution. Both mutation commands
|
|
936
|
+
honor dry runs before client initialization and spinner startup. Invalid port,
|
|
937
|
+
protocol or TTL values are rejected locally; TTL accepts 60 through 86400 seconds,
|
|
938
|
+
and the deployment can cap it further.
|
|
939
|
+
|
|
940
|
+
The updated API honors the SDK's tunnel-creation retry key when server-side
|
|
941
|
+
idempotency is enabled. It replays only a still-active matching tunnel receipt
|
|
942
|
+
after checking current permissions. Closed, expired or unavailable records are
|
|
943
|
+
refused without creating a replacement. With both tunnel and idempotency storage
|
|
944
|
+
in DB mode, records and retry reservations work across controller replicas and
|
|
945
|
+
survive creator restarts. Memory mode remains local to a replica. Shared records
|
|
946
|
+
do not transfer in-flight connections. Without an explicit key, a separate CLI
|
|
947
|
+
invocation uses a new key.
|
|
948
|
+
|
|
949
|
+
For recovery across CLI invocations, save an opaque key with the agent's task
|
|
950
|
+
before opening its tunnel, then pass it on the initial request and every retry:
|
|
951
|
+
|
|
952
|
+
```bash
|
|
953
|
+
stateset --json tunnel open <sandbox-id> --port 8080 --expires-in 600 --idempotency-key task-17-http
|
|
954
|
+
```
|
|
955
|
+
|
|
956
|
+
Keep the same credentials, API URL, sandbox, port, protocol, TTL and `--public`
|
|
957
|
+
setting. A retry through another client must preserve the JSON body, including
|
|
958
|
+
the CLI's explicit `protocol` and `public` fields. Keys accept 1 through 256
|
|
959
|
+
printable ASCII characters without whitespace; invalid keys are refused locally,
|
|
960
|
+
and dry runs preview the supplied key. The key is sent in the `Idempotency-Key`
|
|
961
|
+
header and is excluded from the JSON request body.
|
|
962
|
+
Use a different key for an intentionally separate operation. Inspect the tunnel
|
|
963
|
+
list after uncertain outcomes; a key added only after the initial request cannot
|
|
964
|
+
recover that earlier request. Protection requires a server with tunnel idempotency
|
|
965
|
+
enabled and lasts for its reservation window (currently 24 hours). Stale or
|
|
966
|
+
unavailable receipts return an error without selecting another key automatically.
|
|
967
|
+
|
|
968
|
+
Creation checks receipt identity and the selected sandbox/port/protocol, an HTTP(S)
|
|
969
|
+
URL and a future expiry before reporting success. Provided tokens must be nonempty,
|
|
970
|
+
printable ASCII without whitespace; legacy receipts may omit the token. These
|
|
971
|
+
checks do not probe forwarding or independently verify authentication. Close
|
|
972
|
+
requires a positive acknowledgement and reports acceptance, which does not
|
|
973
|
+
establish that every existing forwarded connection has ended. `--public` remains
|
|
974
|
+
a compatibility flag; the current controller still requires token authentication.
|
|
975
|
+
|
|
976
|
+
### `stateset workbench`
|
|
977
|
+
|
|
978
|
+
Several sandboxes, each with this repository at `/workspace/repo` and Claude
|
|
979
|
+
Code running in a terminal session there. Run it from inside a git repository, or
|
|
980
|
+
name one with `--repo <path>` (accepted by all four subcommands).
|
|
981
|
+
|
|
982
|
+
```bash
|
|
983
|
+
stateset workbench up feat 3 # 3 claude-code sandboxes, HEAD uploaded, Claude Code started
|
|
984
|
+
stateset workbench up fix 2 --base v1.4 --hours 4 --shell # from tag v1.4, 4-hour lifetime, a shell instead
|
|
985
|
+
stateset workbench open feat # attach: one Herdr tab per sandbox, or print the commands
|
|
986
|
+
stateset workbench pull feat -o patches # patches/feat-1.patch ... (changes since the base commit)
|
|
987
|
+
stateset workbench down feat # stop the sandboxes this workbench created
|
|
988
|
+
```
|
|
989
|
+
|
|
990
|
+
**Up options:** `--repo <path>` (the repository to upload; default the current
|
|
991
|
+
directory), `--base <rev>` (the commit the sandboxes start from; default `HEAD`),
|
|
992
|
+
`--hours <n>` (sandbox lifetime, 1 to 24; replaces `--timeout`), `--shell` (start a
|
|
993
|
+
shell in each terminal instead of Claude Code; nothing is installed),
|
|
994
|
+
`--template <template>` (default `claude-code`), `--timeout <seconds>`
|
|
995
|
+
(default 7200), `--cpus`, `--memory`, `--inference-secret <name>` (the secret holding
|
|
996
|
+
the Anthropic credentials Claude Code uses), `--claude-code-version <x.y.z>` (installed
|
|
997
|
+
only when the image has no `claude`). Every subcommand accepts `--json`.
|
|
998
|
+
|
|
999
|
+
- **up** uploads the committed `HEAD`, or `--base` (uncommitted changes are not
|
|
1000
|
+
sent; it warns), as a `git archive`, checked by hash in the sandbox and made a
|
|
1001
|
+
one-commit repository holding every file of that commit, including committed
|
|
1002
|
+
files that `.gitignore` matches. A sandbox that cannot be prepared is reported
|
|
1003
|
+
with the reason and the others still start; the command then exits 1. A workbench
|
|
1004
|
+
that is up cannot be started again until `down`; nor can one whose creates were
|
|
1005
|
+
never confirmed (an interrupted `up`), until `down` has looked for their sandboxes.
|
|
1006
|
+
- **open** inside Herdr (`HERDR_ENV=1`) opens one tab per sandbox, each running
|
|
1007
|
+
`stateset terminal attach`; elsewhere it prints those commands. Ctrl-] detaches
|
|
1008
|
+
and leaves Claude Code running.
|
|
1009
|
+
- **pull** captures commits, uncommitted edits and new files that `.gitignore`
|
|
1010
|
+
does not exclude, without touching the agent's git index or writing anything
|
|
1011
|
+
under the sandbox repository's `.git`. Each download is
|
|
1012
|
+
checked against the size and hash the sandbox reported. Apply a patch on the
|
|
1013
|
+
base commit with `git apply <file>`. A sandbox with no changes writes no file.
|
|
1014
|
+
- **down** stops only sandboxes recorded as created by this workbench, including
|
|
1015
|
+
one whose create response was lost (found by the session ID it was given).
|
|
1016
|
+
|
|
1017
|
+
State lives in `.git/stateset-workbench/<name>.json`, so it is never committed and is
|
|
1018
|
+
shared by the repository's worktrees. `stateset tui` started in the repository reads
|
|
1019
|
+
these files and shows each sandbox's label and phase in its `AGENT` and `PHASE`
|
|
1020
|
+
columns and its agents view (`v`), without `--agents`.
|
|
144
1021
|
|
|
145
1022
|
### `stateset pool`
|
|
146
1023
|
|
|
@@ -195,6 +1072,13 @@ stateset grade --minimum A- # Fail if below A-
|
|
|
195
1072
|
stateset grade --cluster --json # Full check, JSON output
|
|
196
1073
|
```
|
|
197
1074
|
|
|
1075
|
+
A+ also requires a fresh signed evidence bundle with a separately trusted
|
|
1076
|
+
Ed25519 public key. Its API URL, Kubernetes context/namespace and immutable
|
|
1077
|
+
controller/runtime images must match the selected live target. Use
|
|
1078
|
+
`--evidence-report`, `--evidence-public-key`, `--context` and `--namespace` to
|
|
1079
|
+
select those inputs. See [execution readiness](../docs/EXECUTION_READINESS.md)
|
|
1080
|
+
for the full certification requirements.
|
|
1081
|
+
|
|
198
1082
|
## JSON Output
|
|
199
1083
|
|
|
200
1084
|
Most commands support `--json` for machine-readable output, useful for scripting:
|
|
@@ -202,11 +1086,61 @@ Most commands support `--json` for machine-readable output, useful for scripting
|
|
|
202
1086
|
```bash
|
|
203
1087
|
stateset sandbox list --json | jq '.[0].id'
|
|
204
1088
|
stateset pool stats --json
|
|
1089
|
+
stateset swarm get <id> --json | jq '.tasks[] | {key, phase, cost_cents}'
|
|
205
1090
|
stateset grade --json
|
|
206
1091
|
```
|
|
207
1092
|
|
|
208
1093
|
## Development
|
|
209
1094
|
|
|
1095
|
+
For prepared resident AI workers, `sandboxctl delegate --stdin` keeps a
|
|
1096
|
+
conversation open under the normal task deadline. `task-chat <task-id>` reads
|
|
1097
|
+
its model, thread, progress and curated messages; `task-message <task-id>
|
|
1098
|
+
'message'` starts or natively steers a turn. `task-interrupt <task-id>` interrupts
|
|
1099
|
+
the pinned turn while preserving the worker. Save the returned request ID and
|
|
1100
|
+
SHA-256; use `task-message-receipt <task-id> <request-id> --sha256 <hash>` after
|
|
1101
|
+
uncertain delivery, rather than repeating the message.
|
|
1102
|
+
|
|
1103
|
+
In `sandboxctl tui --task <task-id>`, **s** opens the conversation, **i** composes,
|
|
1104
|
+
**Enter** sends, and **x** reviews an interrupt. Reopening the saved task reconnects
|
|
1105
|
+
without launching another worker. `--read-only` disables these writes. See the
|
|
1106
|
+
[resident Codex worker](../examples/codex-agent/README.md#persistent-conversations-and-live-steering)
|
|
1107
|
+
for preparation, bounded lifetime and acknowledgement semantics.
|
|
1108
|
+
**c** opens control receipts; **Enter** verifies the selected UUID and hash.
|
|
1109
|
+
**d** restores a verified rejected draft into an empty composer for review;
|
|
1110
|
+
worker/provider rejections require this explicit action. Review the previous
|
|
1111
|
+
attempt for effects before sending a new message. Unknown delivery cannot be
|
|
1112
|
+
restored. **Delete** reviews forgetting only the selected draft's local text;
|
|
1113
|
+
**y** confirms and **Escape** cancels. Saved intents and pending receipt checks
|
|
1114
|
+
remain available. Read-only mode blocks restoration and disposal.
|
|
1115
|
+
Pending messages and interrupts are checked fairly, at most two per automatic
|
|
1116
|
+
refresh, even after the worker's recent-request list rolls over. The footer
|
|
1117
|
+
shows pending receipts and active checks. **r** during a read queues one
|
|
1118
|
+
follow-up refresh, including after switching to another conversation. A missing
|
|
1119
|
+
receipt remains pending; checking it never resends a control.
|
|
1120
|
+
|
|
1121
|
+
From the conversation, **b** opens saved result bundles without contacting the
|
|
1122
|
+
sandbox, including when the worker or sandbox is unavailable. **Enter** verifies
|
|
1123
|
+
the bundle and opens its artifacts; **Escape** returns through the bundle list
|
|
1124
|
+
to the same conversation. **f** opens the task's files while the sandbox remains
|
|
1125
|
+
available. Leaving either browser preserves the in-memory message draft. Both
|
|
1126
|
+
browsers work in read-only mode. To retain declared artifacts, return to task
|
|
1127
|
+
detail and use **c** after the worker stops and before sandbox expiry.
|
|
1128
|
+
While composing, **Ctrl+B** opens saved bundles and **Ctrl+F** opens task files
|
|
1129
|
+
without clearing or sending the draft; return and press **i** to resume editing.
|
|
1130
|
+
**Escape** in the composer still cancels and clears the draft.
|
|
1131
|
+
|
|
1132
|
+
Press **z** in the conversation to review finishing an idle session, then **y**
|
|
1133
|
+
to send one finish control or **Escape** to cancel. The worker must advertise
|
|
1134
|
+
`finish_session: "idle-only-v1"`; older workers and active turns are refused.
|
|
1135
|
+
Read-only mode blocks finish. The control makes no model call and leaves the
|
|
1136
|
+
sandbox available. Wait for terminal worker exit before collecting with **c**
|
|
1137
|
+
in task detail. Acceptance acknowledges the request, not exit or task quality.
|
|
1138
|
+
|
|
1139
|
+
CLI agents use `sandboxctl task-finish <task-id>` (or `--dry-run` to review),
|
|
1140
|
+
then `task-message-receipt <task-id> <request-id> --sha256 <hash>` to recover a
|
|
1141
|
+
lost acknowledgement. Never resend automatically. Observe terminal status with
|
|
1142
|
+
`task <task-id> --wait`, then `collect <task-id>` before sandbox expiry.
|
|
1143
|
+
|
|
210
1144
|
```bash
|
|
211
1145
|
cd cli
|
|
212
1146
|
npm install
|