Get Started
WORK IN A BOX

Keep a Task Running

Start a server, a long test, or an import that keeps going after you close the terminal, then come back for its output.

A dev server, a watcher, a long test, or a slow import should not die because your terminal closed or your laptop went to sleep. box exec-bg starts the command in the background, returns an exec_id, and lets you come back later for output or control.

Start one background task

sys9 run box create runner
sys9 run box exec-bg runner /bin/sh -lc 'i=1; while [ "$i" -le 6 ]; do echo "tick $i"; i=$((i+1)); sleep 10; done'

The start command returns quickly with the exec_id, current state, idle deadline, and the exact pull-output command you can use next.

Read output as it runs

If you want the visible log from the beginning, use --from-start the first time:

sys9 run box exec-bg pull-output <exec-id> --from-start

Later reads on the same machine can omit --from-start and continue from the saved local cursor, so you only see new output by default:

sys9 run box exec-bg pull-output <exec-id>
sys9 run box exec-bg pull-output <exec-id> --wait 20s

--wait 20s is useful when you want the CLI to keep waiting a little longer for the next output window or the final exit event.

Keep it alive

A background task runs for as long as you keep checking on it. Each successful pull-output gives it another hour. If an hour passes without one, run9 cancels the task and execs inspect shows the reason idle_timeout.

For a task that should run all day, read its output on a schedule, for example once every half hour from a script or an agent loop. To set a fixed limit instead, start it with --deadline:

sys9 run box exec-bg runner --deadline 6h ./long-import.sh

pull-output returns the most recent 20 MiB of output and keeps working for one hour after the task ends. Write anything you need longer than that to a file in the box.

Check whether it is still running

When you want the latest state, exit code, or deadlines without rereading the log, inspect the exec directly:

sys9 run box execs inspect <exec-id>

Stop the task when you are done

If the task is still running and you no longer need it, stop it by exec_id:

sys9 run box exec-bg kill <exec-id>
sys9 run box execs inspect <exec-id>

kill is the clean way to end the background task. After that, execs inspect shows the final state.

  • Run Commands keeps one command attached to your current terminal.
  • Open a Shell keeps shell-local state and manual typing inside one live session.