sandbox_procs

Lists, waits for or stops the commands started with sandbox_exec and background: true, and fetches or waits for a foreground command by its execId. Use it instead of pkill -f or pgrep -f, whose pattern matches every process whose command line holds it, other jobs included.

Every command started with sandbox_exec and background: true has a bgId and writes its output to its logPath, /work/.sbx/logs/<bgId>.log. sandbox_procs looks after those commands:

sandbox_procs { "id": "<id>" }
sandbox_procs { "id": "<id>", "action": "list", "bgId": "<bgId>" }
sandbox_procs { "id": "<id>", "action": "wait", "bgId": "<bgId>", "timeoutSec": 300 }
sandbox_procs { "id": "<id>", "action": "stop", "bgId": "<bgId>" }

• list (also what a call without action does) returns { "procs": [...] }: the background commands still running, oldest first, each with bgId, running, note (as given to sandbox_exec), cmd (its first 120 characters, secret values masked), startedAt, logPath, cpu (the %CPU of all its processes added up; 100 is one core) and mine (whether this conversation started it). foreground lists the foreground commands running right now, from every conversation using the box, the same way, with their execId as bgId: on a box several conversations share, cpu and mine show whose work is using the machine. When finished commands were left out, finished says how many and hint how to see them. all: true lists finished ones too, each with its exitCode (a running command has none). bgId returns just that command, running or not, with logTail, the end of its log.
• logTail is left out of a plain list. list with bgId, wait and stop return the last 4096 bytes of the log; tailBytes (1 to 16384) sets how many, also for a plain list. Secret values in it come back as **** (sandbox_exec); the log file itself is not changed.
• wait blocks until that command ends, or until timeoutSec runs out (default 600, at most 600), and returns { "proc": {...}, "stillRunning": false }, the proc with its exitCode. When the time runs out first, it returns stillRunning: true rather than an error: call it again. Use it for a long build or test run started in the background, instead of polling with sleep in sandbox_exec.
• until: "ready" returns as soon as the command is ready instead: its readyPort accepts connections or a line of its log matches readyLog (both given to sandbox_exec), with ready: true and readyAt. Passing readyPort or readyLog to wait sets (or replaces) that condition for a command started without one, and implies until: "ready"; the log is searched from its start, so a line printed before the call counts. If the command ends before it is ready, wait returns it finished with ready: false.
• A foreground command's execId works as bgId: while it runs, list with it and wait show it with foreground: true and its output so far as logTail; once it ends, proc.result holds what its sandbox_exec returned (stdout, stderr, exitCode, truncated, durationMs, timedOut, and outputPath when the output was cut). Use it when that call was cut off. The last 200 foreground results are kept.
• steps (one command only) lists what psbx-step recorded in it: each step's name, exitCode, ms and startedAt, with running: true for the one still going (see sandbox_exec).
• A command ended by a signal has signal, and endReason says what sent it: stopped by sandbox_procs stop, the out-of-memory killer (the box ran out of memory), or another process.
• stop ends the command's whole process group: SIGTERM, then SIGKILL after 5 seconds if anything is still there. What the command started goes with it, so a server started through npx or npm run stops too and its port is freed. It returns { "proc": {...}, "stopped": true }, with exitCode -1 for a command it stopped. On a command that had already ended, it returns that command's state as it was.
• Stop background commands this way, not with pkill -f or pgrep -f in sandbox_exec. Commands run from a script file, so the pattern no longer matches the shell running your own sandbox_exec, but it matches every other process whose command line holds it, other background jobs included. pkill -x <name> matches only the exact process name, for a process you did not start in the background. kill <pid> signals only that one process, and the processes it started (the server under an npx, say) can keep running. stop ends the whole group.
• Background commands are recorded in /work/.sbx/procs, so they survive a restart of boxd, the box's agent (an update, a crash, being killed for memory): still-running ones are listed and stopped as before; one that ended while boxd was down has exitCode -1 and an endReason saying its real exit code is unknown. Boxes started from an image older than this lose that record when boxd restarts and answer bgId not found.
• Errors: a bgId the box does not know gives box <id>: bgId not found: … with the likely reason; wait or stop without bgId gives bgId is required: list them first with action list; any other action gives action must be list, stop or wait.
• Each call counts as use of the box, like other tools, so waiting for a long job with wait keeps the box from being frozen for being idle; on a frozen box it wakes it first (Box states). Background commands carry on across a freeze and thaw, and keep the box awake for at most 1 hour after its last use. A process started with & inside a foreground sandbox_exec is not one of them: this tool does not list or stop it, and the call that started it reports it with leftoverChildren: true (sandbox_exec).

Every tool and topic is listed in the tool reference.