Script the CLI
You can call Raft from a Linux controller or trusted CI runner with Python 3.11.8+, OpenSSH and configured host access. Your SSH identity controls the host through sudo; do not expose it to untrusted code. For one-shot work, prefer raft run over writing your own allocation and cleanup logic.
Read output
Use raft --json COMMAND ... for JSON Lines events. Put --json before the command:
raft --json list --location lab | jq 'select(.type == "data") | .value'Events have a type: data carries structured value; stdout and stderr carry base64 bytes in data with encoding: "base64"; error carries code and message; the final exit carries code. Decode stream chunks in order within each channel, not as independent text lines. ssh, forward and desktop reject JSON mode. Help and version need no host configuration.
Without global JSON mode, stdout is command-specific:
| Command | Output |
|---|---|
new, fork, recover | One qualified handle |
exec --detach | One job ID |
list | JSONL with box, state, stopAt, deleteAt, disk, note; no records for no boxes |
locations, capacity --json, prune | One JSON object per location or candidate |
info, usage, config, status | A JSON object; info uses native Incus keys |
logs | Retained combined output |
exec, run | Payload stdout and stderr |
stopAt and deleteAt are Unix seconds encoded as strings, or "" when absent. note is a note object or null; disk is "shared" or a size such as "20GiB". usage reports memoryBytes, memoryLimit, cpuTime, effectiveCpus, filesystemUsedBytes, filesystemAvailableBytes and filesystemScope. Shared filesystem counters describe the pool, not one box.
Keep stderr separate from parsed stdout. Recovery prints its allocated handle on stderr before import completes. Set RAFT_NO_UPDATE_CHECK=1 for pinned runs to suppress release notices; JSON mode also suppresses them.
Preserve failures
Successful control operations return 0; recognized operation/configuration errors return 1; argument errors return 2; self-update --check returns 100 when an update exists. Caught Ctrl+C returns 130. Synchronous exec preserves the command's status when transport succeeds, and reads caller stdin:
printf '%s\n' 'input from the controller' | raft exec "$box" -- cat
raft exec "$box" -- bash -lc 'echo "Command failed" >&2; exit 7'SSH failures can report transport status instead. status returning zero only confirms the query; read the job's terminal state and exitCode for its result. See background jobs.
Wait before running setup
Creation returns before guest services are necessarily ready. This Bash example creates a task-owned persistent box with explicit settings and retries only a harmless readiness probe:
box=$(raft new --location lab --ttl 3600 --cpu 1 --memory 2GiB --disk shared --persistent --purpose "Scripted project setup" --owner "Local operator" --next "Inspect and stop after setup") || exit "$?"
ready=false
for attempt in {1..30}; do
if raft exec "$box" -- true; then ready=true; break; fi
sleep 2
done
if [ "$ready" != true ]; then
printf 'Guest not ready; inspect %s\n' "$box" >&2
exit 1
fi
raft exec "$box" -- node --versionThe wait is about a minute plus transport time. If it fails, the box still exists: inspect it before stopping or destroying it. Probe Docker with docker info or an application with its health check separately; command readiness does not prove either is ready. After collecting results, stop your persistent box. Host retention may later delete it.
Pass explicit location, TTL, sizes and lifecycle flags when scripts need stable settings. Controller defaults otherwise differ. Supply all note fields if host policy requires them.
Recover from a lost connection
Raft does not automatically retry ordinary operations or provide idempotency keys. A dropped connection during create, resume, import or execution can leave the operation completed remotely. Inspect inventory, metadata and command effects before retrying. Creation can leave a saved box without delivering a handle to stdout.
Use the recovery handle printed on stderr for an interrupted import. Never treat an unreachable host as proof that a box is absent or a command did not run.