@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.
Files changed (431) hide show
  1. package/CHANGELOG.md +123 -0
  2. package/LICENSE +22 -0
  3. package/README.md +940 -6
  4. package/dist/client.d.ts +789 -10
  5. package/dist/client.d.ts.map +1 -1
  6. package/dist/client.js +694 -12
  7. package/dist/client.js.map +1 -1
  8. package/dist/commands/alias.d.ts +5 -0
  9. package/dist/commands/alias.d.ts.map +1 -0
  10. package/dist/commands/alias.js +131 -0
  11. package/dist/commands/alias.js.map +1 -0
  12. package/dist/commands/api-key.d.ts +3 -0
  13. package/dist/commands/api-key.d.ts.map +1 -0
  14. package/dist/commands/api-key.js +119 -0
  15. package/dist/commands/api-key.js.map +1 -0
  16. package/dist/commands/artifact.d.ts.map +1 -1
  17. package/dist/commands/artifact.js +105 -46
  18. package/dist/commands/artifact.js.map +1 -1
  19. package/dist/commands/audit.d.ts +3 -0
  20. package/dist/commands/audit.d.ts.map +1 -0
  21. package/dist/commands/audit.js +191 -0
  22. package/dist/commands/audit.js.map +1 -0
  23. package/dist/commands/auth.d.ts +3 -0
  24. package/dist/commands/auth.d.ts.map +1 -0
  25. package/dist/commands/auth.js +126 -0
  26. package/dist/commands/auth.js.map +1 -0
  27. package/dist/commands/benchmark.d.ts +3 -0
  28. package/dist/commands/benchmark.d.ts.map +1 -0
  29. package/dist/commands/benchmark.js +166 -0
  30. package/dist/commands/benchmark.js.map +1 -0
  31. package/dist/commands/billing.d.ts +3 -0
  32. package/dist/commands/billing.d.ts.map +1 -0
  33. package/dist/commands/billing.js +139 -0
  34. package/dist/commands/billing.js.map +1 -0
  35. package/dist/commands/checkpoint.d.ts.map +1 -1
  36. package/dist/commands/checkpoint.js +105 -48
  37. package/dist/commands/checkpoint.js.map +1 -1
  38. package/dist/commands/completion.d.ts +3 -0
  39. package/dist/commands/completion.d.ts.map +1 -0
  40. package/dist/commands/completion.js +134 -0
  41. package/dist/commands/completion.js.map +1 -0
  42. package/dist/commands/computer-use.d.ts +3 -0
  43. package/dist/commands/computer-use.d.ts.map +1 -0
  44. package/dist/commands/computer-use.js +124 -0
  45. package/dist/commands/computer-use.js.map +1 -0
  46. package/dist/commands/config.d.ts.map +1 -1
  47. package/dist/commands/config.js +2 -1
  48. package/dist/commands/config.js.map +1 -1
  49. package/dist/commands/context.d.ts +3 -0
  50. package/dist/commands/context.d.ts.map +1 -0
  51. package/dist/commands/context.js +98 -0
  52. package/dist/commands/context.js.map +1 -0
  53. package/dist/commands/cp.d.ts +3 -0
  54. package/dist/commands/cp.d.ts.map +1 -0
  55. package/dist/commands/cp.js +165 -0
  56. package/dist/commands/cp.js.map +1 -0
  57. package/dist/commands/deploy.d.ts +3 -0
  58. package/dist/commands/deploy.d.ts.map +1 -1
  59. package/dist/commands/deploy.js +68 -20
  60. package/dist/commands/deploy.js.map +1 -1
  61. package/dist/commands/diff.d.ts +3 -0
  62. package/dist/commands/diff.d.ts.map +1 -0
  63. package/dist/commands/diff.js +186 -0
  64. package/dist/commands/diff.js.map +1 -0
  65. package/dist/commands/doctor.d.ts +30 -0
  66. package/dist/commands/doctor.d.ts.map +1 -1
  67. package/dist/commands/doctor.js +177 -207
  68. package/dist/commands/doctor.js.map +1 -1
  69. package/dist/commands/egress.d.ts +3 -0
  70. package/dist/commands/egress.d.ts.map +1 -0
  71. package/dist/commands/egress.js +155 -0
  72. package/dist/commands/egress.js.map +1 -0
  73. package/dist/commands/env.d.ts +3 -0
  74. package/dist/commands/env.d.ts.map +1 -0
  75. package/dist/commands/env.js +169 -0
  76. package/dist/commands/env.js.map +1 -0
  77. package/dist/commands/governance.d.ts +47 -0
  78. package/dist/commands/governance.d.ts.map +1 -0
  79. package/dist/commands/governance.js +345 -0
  80. package/dist/commands/governance.js.map +1 -0
  81. package/dist/commands/grade.d.ts +41 -0
  82. package/dist/commands/grade.d.ts.map +1 -1
  83. package/dist/commands/grade.js +255 -160
  84. package/dist/commands/grade.js.map +1 -1
  85. package/dist/commands/history.d.ts +4 -0
  86. package/dist/commands/history.d.ts.map +1 -0
  87. package/dist/commands/history.js +157 -0
  88. package/dist/commands/history.js.map +1 -0
  89. package/dist/commands/images.d.ts +8 -0
  90. package/dist/commands/images.d.ts.map +1 -0
  91. package/dist/commands/images.js +145 -0
  92. package/dist/commands/images.js.map +1 -0
  93. package/dist/commands/info.d.ts +3 -0
  94. package/dist/commands/info.d.ts.map +1 -0
  95. package/dist/commands/info.js +86 -0
  96. package/dist/commands/info.js.map +1 -0
  97. package/dist/commands/init.d.ts +3 -0
  98. package/dist/commands/init.d.ts.map +1 -0
  99. package/dist/commands/init.js +185 -0
  100. package/dist/commands/init.js.map +1 -0
  101. package/dist/commands/logs.d.ts +3 -0
  102. package/dist/commands/logs.d.ts.map +1 -0
  103. package/dist/commands/logs.js +129 -0
  104. package/dist/commands/logs.js.map +1 -0
  105. package/dist/commands/mcp.d.ts +3 -0
  106. package/dist/commands/mcp.d.ts.map +1 -0
  107. package/dist/commands/mcp.js +141 -0
  108. package/dist/commands/mcp.js.map +1 -0
  109. package/dist/commands/open.d.ts +3 -0
  110. package/dist/commands/open.d.ts.map +1 -0
  111. package/dist/commands/open.js +96 -0
  112. package/dist/commands/open.js.map +1 -0
  113. package/dist/commands/platform-status.d.ts +25 -5
  114. package/dist/commands/platform-status.d.ts.map +1 -1
  115. package/dist/commands/platform-status.js +199 -149
  116. package/dist/commands/platform-status.js.map +1 -1
  117. package/dist/commands/plugin.d.ts +5 -0
  118. package/dist/commands/plugin.d.ts.map +1 -0
  119. package/dist/commands/plugin.js +126 -0
  120. package/dist/commands/plugin.js.map +1 -0
  121. package/dist/commands/pool.d.ts.map +1 -1
  122. package/dist/commands/pool.js +52 -66
  123. package/dist/commands/pool.js.map +1 -1
  124. package/dist/commands/profile.d.ts +3 -0
  125. package/dist/commands/profile.d.ts.map +1 -0
  126. package/dist/commands/profile.js +107 -0
  127. package/dist/commands/profile.js.map +1 -0
  128. package/dist/commands/repl.d.ts +3 -0
  129. package/dist/commands/repl.d.ts.map +1 -0
  130. package/dist/commands/repl.js +390 -0
  131. package/dist/commands/repl.js.map +1 -0
  132. package/dist/commands/run.d.ts +3 -0
  133. package/dist/commands/run.d.ts.map +1 -0
  134. package/dist/commands/run.js +154 -0
  135. package/dist/commands/run.js.map +1 -0
  136. package/dist/commands/sandbox-processes.d.ts +27 -0
  137. package/dist/commands/sandbox-processes.d.ts.map +1 -0
  138. package/dist/commands/sandbox-processes.js +195 -0
  139. package/dist/commands/sandbox-processes.js.map +1 -0
  140. package/dist/commands/sandbox.d.ts.map +1 -1
  141. package/dist/commands/sandbox.js +562 -108
  142. package/dist/commands/sandbox.js.map +1 -1
  143. package/dist/commands/secret.d.ts +3 -0
  144. package/dist/commands/secret.d.ts.map +1 -0
  145. package/dist/commands/secret.js +128 -0
  146. package/dist/commands/secret.js.map +1 -0
  147. package/dist/commands/session.d.ts.map +1 -1
  148. package/dist/commands/session.js +285 -52
  149. package/dist/commands/session.js.map +1 -1
  150. package/dist/commands/snapshot.d.ts +3 -0
  151. package/dist/commands/snapshot.d.ts.map +1 -0
  152. package/dist/commands/snapshot.js +253 -0
  153. package/dist/commands/snapshot.js.map +1 -0
  154. package/dist/commands/ssh.d.ts +5 -0
  155. package/dist/commands/ssh.d.ts.map +1 -0
  156. package/dist/commands/ssh.js +154 -0
  157. package/dist/commands/ssh.js.map +1 -0
  158. package/dist/commands/swarm.d.ts +12 -0
  159. package/dist/commands/swarm.d.ts.map +1 -0
  160. package/dist/commands/swarm.js +288 -0
  161. package/dist/commands/swarm.js.map +1 -0
  162. package/dist/commands/template.d.ts +3 -0
  163. package/dist/commands/template.d.ts.map +1 -0
  164. package/dist/commands/template.js +102 -0
  165. package/dist/commands/template.js.map +1 -0
  166. package/dist/commands/terminal.d.ts +55 -0
  167. package/dist/commands/terminal.d.ts.map +1 -0
  168. package/dist/commands/terminal.js +438 -0
  169. package/dist/commands/terminal.js.map +1 -0
  170. package/dist/commands/top.d.ts +3 -0
  171. package/dist/commands/top.d.ts.map +1 -0
  172. package/dist/commands/top.js +116 -0
  173. package/dist/commands/top.js.map +1 -0
  174. package/dist/commands/tunnel.d.ts.map +1 -1
  175. package/dist/commands/tunnel.js +73 -26
  176. package/dist/commands/tunnel.js.map +1 -1
  177. package/dist/commands/update.d.ts +3 -0
  178. package/dist/commands/update.d.ts.map +1 -0
  179. package/dist/commands/update.js +51 -0
  180. package/dist/commands/update.js.map +1 -0
  181. package/dist/commands/wait.d.ts +3 -0
  182. package/dist/commands/wait.d.ts.map +1 -0
  183. package/dist/commands/wait.js +64 -0
  184. package/dist/commands/wait.js.map +1 -0
  185. package/dist/commands/webhook.d.ts +3 -0
  186. package/dist/commands/webhook.d.ts.map +1 -0
  187. package/dist/commands/webhook.js +169 -0
  188. package/dist/commands/webhook.js.map +1 -0
  189. package/dist/commands/workbench.d.ts +138 -0
  190. package/dist/commands/workbench.d.ts.map +1 -0
  191. package/dist/commands/workbench.js +531 -0
  192. package/dist/commands/workbench.js.map +1 -0
  193. package/dist/config.d.ts +14 -6
  194. package/dist/config.d.ts.map +1 -1
  195. package/dist/config.js +109 -16
  196. package/dist/config.js.map +1 -1
  197. package/dist/index.js +169 -11
  198. package/dist/index.js.map +1 -1
  199. package/dist/sandboxctl.d.ts +3 -0
  200. package/dist/sandboxctl.d.ts.map +1 -0
  201. package/dist/sandboxctl.js +37 -0
  202. package/dist/sandboxctl.js.map +1 -0
  203. package/dist/utils/context.d.ts +23 -0
  204. package/dist/utils/context.d.ts.map +1 -0
  205. package/dist/utils/context.js +48 -0
  206. package/dist/utils/context.js.map +1 -0
  207. package/dist/utils/credentials.d.ts +8 -0
  208. package/dist/utils/credentials.d.ts.map +1 -0
  209. package/dist/utils/credentials.js +120 -0
  210. package/dist/utils/credentials.js.map +1 -0
  211. package/dist/utils/dry-run.d.ts +4 -0
  212. package/dist/utils/dry-run.d.ts.map +1 -0
  213. package/dist/utils/dry-run.js +24 -0
  214. package/dist/utils/dry-run.js.map +1 -0
  215. package/dist/utils/egress-policy.d.ts +31 -0
  216. package/dist/utils/egress-policy.d.ts.map +1 -0
  217. package/dist/utils/egress-policy.js +83 -0
  218. package/dist/utils/egress-policy.js.map +1 -0
  219. package/dist/utils/errors.d.ts +53 -0
  220. package/dist/utils/errors.d.ts.map +1 -0
  221. package/dist/utils/errors.js +278 -0
  222. package/dist/utils/errors.js.map +1 -0
  223. package/dist/utils/file-content.d.ts +10 -0
  224. package/dist/utils/file-content.d.ts.map +1 -0
  225. package/dist/utils/file-content.js +14 -0
  226. package/dist/utils/file-content.js.map +1 -0
  227. package/dist/utils/grade-target.d.ts +12 -0
  228. package/dist/utils/grade-target.d.ts.map +1 -0
  229. package/dist/utils/grade-target.js +106 -0
  230. package/dist/utils/grade-target.js.map +1 -0
  231. package/dist/utils/health-report.d.ts +18 -0
  232. package/dist/utils/health-report.d.ts.map +1 -0
  233. package/dist/utils/health-report.js +43 -0
  234. package/dist/utils/health-report.js.map +1 -0
  235. package/dist/utils/output.d.ts +20 -0
  236. package/dist/utils/output.d.ts.map +1 -0
  237. package/dist/utils/output.js +123 -0
  238. package/dist/utils/output.js.map +1 -0
  239. package/dist/utils/plugins.d.ts +17 -0
  240. package/dist/utils/plugins.d.ts.map +1 -0
  241. package/dist/utils/plugins.js +57 -0
  242. package/dist/utils/plugins.js.map +1 -0
  243. package/dist/utils/resource-class.d.ts +12 -0
  244. package/dist/utils/resource-class.d.ts.map +1 -0
  245. package/dist/utils/resource-class.js +17 -0
  246. package/dist/utils/resource-class.js.map +1 -0
  247. package/dist/utils/shutdown.d.ts +14 -0
  248. package/dist/utils/shutdown.d.ts.map +1 -0
  249. package/dist/utils/shutdown.js +54 -0
  250. package/dist/utils/shutdown.js.map +1 -0
  251. package/dist/utils/swarm-plan.d.ts +69 -0
  252. package/dist/utils/swarm-plan.d.ts.map +1 -0
  253. package/dist/utils/swarm-plan.js +321 -0
  254. package/dist/utils/swarm-plan.js.map +1 -0
  255. package/dist/utils/template-create.d.ts +36 -0
  256. package/dist/utils/template-create.d.ts.map +1 -0
  257. package/dist/utils/template-create.js +116 -0
  258. package/dist/utils/template-create.js.map +1 -0
  259. package/dist/utils/tty.d.ts +44 -0
  260. package/dist/utils/tty.d.ts.map +1 -0
  261. package/dist/utils/tty.js +93 -0
  262. package/dist/utils/tty.js.map +1 -0
  263. package/dist/utils/warnings.d.ts +4 -0
  264. package/dist/utils/warnings.d.ts.map +1 -0
  265. package/dist/utils/warnings.js +22 -0
  266. package/dist/utils/warnings.js.map +1 -0
  267. package/dist/utils/watch.d.ts +7 -0
  268. package/dist/utils/watch.d.ts.map +1 -0
  269. package/dist/utils/watch.js +55 -0
  270. package/dist/utils/watch.js.map +1 -0
  271. package/dist/workbench/actions.d.ts +26 -0
  272. package/dist/workbench/actions.d.ts.map +1 -0
  273. package/dist/workbench/actions.js +39 -0
  274. package/dist/workbench/actions.js.map +1 -0
  275. package/dist/workbench/agent-chat.d.ts +71 -0
  276. package/dist/workbench/agent-chat.d.ts.map +1 -0
  277. package/dist/workbench/agent-chat.js +223 -0
  278. package/dist/workbench/agent-chat.js.map +1 -0
  279. package/dist/workbench/agents.d.ts +96 -0
  280. package/dist/workbench/agents.d.ts.map +1 -0
  281. package/dist/workbench/agents.js +370 -0
  282. package/dist/workbench/agents.js.map +1 -0
  283. package/dist/workbench/batch-uploads.d.ts +36 -0
  284. package/dist/workbench/batch-uploads.d.ts.map +1 -0
  285. package/dist/workbench/batch-uploads.js +154 -0
  286. package/dist/workbench/batch-uploads.js.map +1 -0
  287. package/dist/workbench/commands.d.ts +6 -0
  288. package/dist/workbench/commands.d.ts.map +1 -0
  289. package/dist/workbench/commands.js +517 -0
  290. package/dist/workbench/commands.js.map +1 -0
  291. package/dist/workbench/connection-failure.d.ts +9 -0
  292. package/dist/workbench/connection-failure.d.ts.map +1 -0
  293. package/dist/workbench/connection-failure.js +27 -0
  294. package/dist/workbench/connection-failure.js.map +1 -0
  295. package/dist/workbench/connection.d.ts +4 -0
  296. package/dist/workbench/connection.d.ts.map +1 -0
  297. package/dist/workbench/connection.js +28 -0
  298. package/dist/workbench/connection.js.map +1 -0
  299. package/dist/workbench/creation.d.ts +22 -0
  300. package/dist/workbench/creation.d.ts.map +1 -0
  301. package/dist/workbench/creation.js +102 -0
  302. package/dist/workbench/creation.js.map +1 -0
  303. package/dist/workbench/credits.d.ts +11 -0
  304. package/dist/workbench/credits.d.ts.map +1 -0
  305. package/dist/workbench/credits.js +132 -0
  306. package/dist/workbench/credits.js.map +1 -0
  307. package/dist/workbench/docker.d.ts +18 -0
  308. package/dist/workbench/docker.d.ts.map +1 -0
  309. package/dist/workbench/docker.js +207 -0
  310. package/dist/workbench/docker.js.map +1 -0
  311. package/dist/workbench/execution.d.ts +14 -0
  312. package/dist/workbench/execution.d.ts.map +1 -0
  313. package/dist/workbench/execution.js +24 -0
  314. package/dist/workbench/execution.js.map +1 -0
  315. package/dist/workbench/files.d.ts +51 -0
  316. package/dist/workbench/files.d.ts.map +1 -0
  317. package/dist/workbench/files.js +80 -0
  318. package/dist/workbench/files.js.map +1 -0
  319. package/dist/workbench/history.d.ts +34 -0
  320. package/dist/workbench/history.d.ts.map +1 -0
  321. package/dist/workbench/history.js +50 -0
  322. package/dist/workbench/history.js.map +1 -0
  323. package/dist/workbench/input-batch-commands.d.ts +6 -0
  324. package/dist/workbench/input-batch-commands.d.ts.map +1 -0
  325. package/dist/workbench/input-batch-commands.js +41 -0
  326. package/dist/workbench/input-batch-commands.js.map +1 -0
  327. package/dist/workbench/kitty-diacritics.d.ts +2 -0
  328. package/dist/workbench/kitty-diacritics.d.ts.map +1 -0
  329. package/dist/workbench/kitty-diacritics.js +22 -0
  330. package/dist/workbench/kitty-diacritics.js.map +1 -0
  331. package/dist/workbench/kitty-graphics.d.ts +59 -0
  332. package/dist/workbench/kitty-graphics.d.ts.map +1 -0
  333. package/dist/workbench/kitty-graphics.js +263 -0
  334. package/dist/workbench/kitty-graphics.js.map +1 -0
  335. package/dist/workbench/live-execution.d.ts +51 -0
  336. package/dist/workbench/live-execution.d.ts.map +1 -0
  337. package/dist/workbench/live-execution.js +222 -0
  338. package/dist/workbench/live-execution.js.map +1 -0
  339. package/dist/workbench/model.d.ts +110 -0
  340. package/dist/workbench/model.d.ts.map +1 -0
  341. package/dist/workbench/model.js +249 -0
  342. package/dist/workbench/model.js.map +1 -0
  343. package/dist/workbench/overview.d.ts +11 -0
  344. package/dist/workbench/overview.d.ts.map +1 -0
  345. package/dist/workbench/overview.js +92 -0
  346. package/dist/workbench/overview.js.map +1 -0
  347. package/dist/workbench/png.d.ts +10 -0
  348. package/dist/workbench/png.d.ts.map +1 -0
  349. package/dist/workbench/png.js +51 -0
  350. package/dist/workbench/png.js.map +1 -0
  351. package/dist/workbench/python-task.d.ts +21 -0
  352. package/dist/workbench/python-task.d.ts.map +1 -0
  353. package/dist/workbench/python-task.js +52 -0
  354. package/dist/workbench/python-task.js.map +1 -0
  355. package/dist/workbench/registry-commands.d.ts +8 -0
  356. package/dist/workbench/registry-commands.d.ts.map +1 -0
  357. package/dist/workbench/registry-commands.js +93 -0
  358. package/dist/workbench/registry-commands.js.map +1 -0
  359. package/dist/workbench/registry.d.ts +76 -0
  360. package/dist/workbench/registry.d.ts.map +1 -0
  361. package/dist/workbench/registry.js +353 -0
  362. package/dist/workbench/registry.js.map +1 -0
  363. package/dist/workbench/renderer.d.ts +6 -0
  364. package/dist/workbench/renderer.d.ts.map +1 -0
  365. package/dist/workbench/renderer.js +18 -0
  366. package/dist/workbench/renderer.js.map +1 -0
  367. package/dist/workbench/results.d.ts +15 -0
  368. package/dist/workbench/results.d.ts.map +1 -0
  369. package/dist/workbench/results.js +29 -0
  370. package/dist/workbench/results.js.map +1 -0
  371. package/dist/workbench/task-archive.d.ts +23 -0
  372. package/dist/workbench/task-archive.d.ts.map +1 -0
  373. package/dist/workbench/task-archive.js +56 -0
  374. package/dist/workbench/task-archive.js.map +1 -0
  375. package/dist/workbench/task-board.d.ts +26 -0
  376. package/dist/workbench/task-board.d.ts.map +1 -0
  377. package/dist/workbench/task-board.js +43 -0
  378. package/dist/workbench/task-board.js.map +1 -0
  379. package/dist/workbench/task-monitor.d.ts +35 -0
  380. package/dist/workbench/task-monitor.d.ts.map +1 -0
  381. package/dist/workbench/task-monitor.js +176 -0
  382. package/dist/workbench/task-monitor.js.map +1 -0
  383. package/dist/workbench/tasks.d.ts +93 -0
  384. package/dist/workbench/tasks.d.ts.map +1 -0
  385. package/dist/workbench/tasks.js +195 -0
  386. package/dist/workbench/tasks.js.map +1 -0
  387. package/dist/workbench/terminal.d.ts +82 -0
  388. package/dist/workbench/terminal.d.ts.map +1 -0
  389. package/dist/workbench/terminal.js +2607 -0
  390. package/dist/workbench/terminal.js.map +1 -0
  391. package/dist/workbench/text.d.ts +10 -0
  392. package/dist/workbench/text.d.ts.map +1 -0
  393. package/dist/workbench/text.js +72 -0
  394. package/dist/workbench/text.js.map +1 -0
  395. package/dist/workbench/uploads.d.ts +12 -0
  396. package/dist/workbench/uploads.d.ts.map +1 -0
  397. package/dist/workbench/uploads.js +16 -0
  398. package/dist/workbench/uploads.js.map +1 -0
  399. package/dist/workbench/worker-launch.d.ts +10 -0
  400. package/dist/workbench/worker-launch.d.ts.map +1 -0
  401. package/dist/workbench/worker-launch.js +30 -0
  402. package/dist/workbench/worker-launch.js.map +1 -0
  403. package/dist/workbench/worker-monitor.d.ts +33 -0
  404. package/dist/workbench/worker-monitor.d.ts.map +1 -0
  405. package/dist/workbench/worker-monitor.js +142 -0
  406. package/dist/workbench/worker-monitor.js.map +1 -0
  407. package/dist/workbench/worker-output.d.ts +8 -0
  408. package/dist/workbench/worker-output.d.ts.map +1 -0
  409. package/dist/workbench/worker-output.js +32 -0
  410. package/dist/workbench/worker-output.js.map +1 -0
  411. package/dist/workbench/worker-result.d.ts +29 -0
  412. package/dist/workbench/worker-result.d.ts.map +1 -0
  413. package/dist/workbench/worker-result.js +85 -0
  414. package/dist/workbench/worker-result.js.map +1 -0
  415. package/dist/workbench/workers.d.ts +49 -0
  416. package/dist/workbench/workers.d.ts.map +1 -0
  417. package/dist/workbench/workers.js +53 -0
  418. package/dist/workbench/workers.js.map +1 -0
  419. package/package.json +38 -17
  420. package/dist/__tests__/client.test.d.ts +0 -2
  421. package/dist/__tests__/client.test.d.ts.map +0 -1
  422. package/dist/__tests__/client.test.js +0 -198
  423. package/dist/__tests__/client.test.js.map +0 -1
  424. package/dist/__tests__/config.test.d.ts +0 -2
  425. package/dist/__tests__/config.test.d.ts.map +0 -1
  426. package/dist/__tests__/config.test.js +0 -74
  427. package/dist/__tests__/config.test.js.map +0 -1
  428. package/dist/__tests__/utils-cli.test.d.ts +0 -2
  429. package/dist/__tests__/utils-cli.test.d.ts.map +0 -1
  430. package/dist/__tests__/utils-cli.test.js +0 -35
  431. 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 >= 20.
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.com
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> "echo hello world"
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` | `http://localhost:8080` |
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> # Execute in session
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