@stateset/sandbox-cli 1.0.5 → 3.3.1

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