CLI command referenceCopy Anchor Link

Command-line reference for the raft controller tool.

Syntax: raft <subcommand> [options] [arguments]

Workspaces are referenced by location-qualified handles formatted as <location>:<instance-name> (for example lab:rf-a1b2c3d4e5f60718).

Command indexCopy Anchor Link

Workspace lifecycle commandsCopy Anchor Link

newCopy Anchor Link

Create and launch a new workspace container.

raft new [--location LOCATION] [--ttl TTL] [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB}]

• --location LOCATION: Target host location in ~/.config/raft/incus.json. Defaults to first configured location.
• --ttl TTL: Lifetime in seconds before automatic stop (60 to 2592000). Default: 600.
• --cpu {1,2}: CPU core count managed by Incus. Default: 1.
• --memory {1GiB,2GiB,4GiB}: Memory limit. Default: 2GiB.

Returns the qualified workspace handle.

stopCopy Anchor Link

Stop a running workspace.

raft stop <box>

Terminates guest processes and stops the container. Filesystem contents, packages, and snapshots are preserved on disk.

resumeCopy Anchor Link

Start a stopped workspace with a renewed lifetime deadline.

raft resume <box> --ttl TTL

• --ttl TTL: Lifetime in seconds from resumption (60 to 2592000). Required.

extendCopy Anchor Link

Reset the expiration deadline for a running workspace without restarting it.

raft extend <box> --ttl TTL

• --ttl TTL: Lifetime in seconds from the current host timestamp. Required.

destroyCopy Anchor Link

Permanently delete a workspace container and its snapshots.

raft destroy <box>

Stops the container if running, removes all associated Btrfs snapshots, and releases host storage.

Execution and inspection commandsCopy Anchor Link

execCopy Anchor Link

Execute a command inside a workspace.

raft exec <box> [--detach] [--] <command ...>

• --detach: Run in background as a guest systemd unit. Returns a job ID immediately.
• <command ...>: Command and arguments passed to execve. For shell features (pipes, redirects, variables), wrap with bash -lc '...'.

Example:

job=$(raft exec "$box" --detach -- make test)

sshCopy Anchor Link

Open an interactive root terminal session inside the workspace over host SSH and Incus exec.

raft ssh <box>

infoCopy Anchor Link

Display container metadata from Incus in JSON format, including status, IP addresses, resource limits, and timestamps.

raft info <box>

usageCopy Anchor Link

Display active resource consumption for a running workspace: cgroup memory, CPU microseconds, CPU affinity, and shared-pool disk space.

raft usage <box>

Background job commandsCopy Anchor Link

status, logs and cancel require a job ID returned by exec --detach in the selected running workspace. Unknown jobs return an error.

Cancelled jobs remain inspectable while their guest journal records exist. Rotating old logs does not prevent inspection of a live job.

statusCopy Anchor Link

Check the execution state of a detached background job.

raft status <box> <job>

Queries systemctl show inside the container and outputs ActiveState, SubState, and ExecMainStatus.

logsCopy Anchor Link

Retrieve journal output from a detached background job using journalctl --no-pager -o cat -u <job>.

raft logs <box> <job>

cancelCopy Anchor Link

Terminate a running detached background job using systemctl stop <job>.

raft cancel <box> <job>

File transfer commandsCopy Anchor Link

uploadCopy Anchor Link

Transfer a local file from the controller to an absolute path inside the workspace.

raft upload <box> <source> <destination>

• <source>: Path to local file on controller.
• <destination>: Target absolute path inside container.

downloadCopy Anchor Link

Transfer a file from an absolute path inside the workspace to the local controller.

raft download <box> <source> <destination>

• <source>: Absolute path to file inside container.
• <destination>: Local file destination path on controller.

Snapshots and cloning commandsCopy Anchor Link

snapshotCopy Anchor Link

Create a named point-in-time snapshot of a stopped workspace. Names use alphanumeric characters, underscores, or hyphens up to 64 characters.

raft snapshot <box> <name>

snapshotsCopy Anchor Link

List existing snapshots and creation timestamps for a workspace.

raft snapshots <box>

restoreCopy Anchor Link

Roll back a stopped workspace filesystem to a named snapshot using --diskonly, preserving container configuration and MAC address.

raft restore <box> <name>

forkCopy Anchor Link

Clone a stopped workspace into an independent container on the same host and start it.

raft fork <box> --ttl TTL

• --ttl TTL: Lifetime in seconds for the clone. Required.

Returns the qualified handle of the clone.

Port forwarding and desktop commandsCopy Anchor Link

forwardCopy Anchor Link

Open a private SSH tunnel between a guest port and controller loopback (127.0.0.1).

raft forward <box> --remote REMOTE --local LOCAL

• --remote REMOTE: Port number inside the workspace (bound to 0.0.0.0 or container IP).
• --local LOCAL: Port number on controller loopback (127.0.0.1).

Runs in foreground; press Ctrl+C to close.

desktopCopy Anchor Link

Start raft-desktop.service inside the container and open a private tunnel for noVNC.

raft desktop <box> [--local LOCAL]

• --local LOCAL: Controller port to bind (default: 6080). Access at http://127.0.0.1:<LOCAL>/vnc.html. Press Ctrl+C to close.

Backup and recovery commandsCopy Anchor Link

backupCopy Anchor Link

Export a stopped workspace and its snapshots to a compressed archive on the controller.

raft backup <box> <destination>

• <destination>: Output archive path (e.g. ./workspace.tar.gz). Must not exist. Created with mode 0600.

recoverCopy Anchor Link

Import a portable backup archive onto a host as a fresh stopped workspace.

raft recover <source> --location LOCATION

• <source>: Path to archive file on controller.
• --location LOCATION: Target host location. Required.

Returns the qualified handle of the imported stopped workspace.

Host inspection and maintenance commandsCopy Anchor Link

limitsCopy Anchor Link

Inspect host resource capacity, active allocations, and recommended workspace limits.

raft limits [--location LOCATION] [--json]

• --location LOCATION: Filter report to a specific host.
• --json: Output report as JSON.

doctorCopy Anchor Link

Inspect host connectivity, Incus version, active systemd units (incus, raft-expire.timer, raft-network.service), root filesystem usage, storage pool status, and saved box count across configured hosts.

raft doctor

listCopy Anchor Link

List existing workspace containers across configured hosts.

raft list [--location LOCATION]

gcCopy Anchor Link

Trigger the host expiration worker across all configured hosts immediately to stop expired containers.

raft gc