raft / docs
Guides

Run a background job

You can disconnect while a command runs and inspect its result afterward. Set $box to your task's running box from raft list. Detaching does not extend its lifetime; stop, expiry and host reboot interrupt active jobs without saving process memory.

Start and inspect a job

job=$(raft exec "$box" --detach -- bash -lc 'echo "Job started"; sleep 60; echo "Job finished"')
raft status "$box" "$job"
raft logs "$box" "$job"

Keep both the original box handle and the returned rfcmd- job ID. Status and logs remain available on the host after box stop or deletion; snapshots and forks do not copy them.

A successful status query does not mean the payload succeeded. Read its state and exitCode:

StateMeaning
starting, runningNo confirmed result yet
completedExecution ended; only exitCode: 0 confirms success
cancelled, interrupted, failedNo confirmed payload exit code; inspect retained output and any reported error

startedAt and finishedAt use host Unix seconds. An interrupted transport can leave the guest command running; inspect or cancel it before rerunning a command with side effects.

Cancel or give the box more time

raft cancel "$box" "$job"

Cancellation stops the job and its child processes. It can fail while the guest unit is still starting. Inspect status before retrying. Cancellation waits up to 120 seconds; after a timeout, the request remains recorded, so inspect and retry cancellation rather than assume it stopped.

For work you intend to keep running, use raft extend "$box" --ttl 1800 before expiry. This resets the deadline to host time plus 1,800 seconds, not the old deadline plus 1,800.

Keep needed results outside the log store

Raft retains the first 1 MiB of combined stdout and stderr for seven days after completion. Further output is discarded and counted as droppedBytes. Download larger artifacts before deleting the box.

The host-private store at /var/lib/raft-jobs holds at most 512 records and removes expired records on job access. A full store refuses another job rather than evicting unexpired results. Damaged records count toward the limit; an error names their path for inspection. Unknown, expired or wrong-box job IDs are rejected.

Completed records survive host reboot, but this is not an off-host backup. Output can contain secrets. For applications that restart after resume, use persistent services.

On this page