Installation and host setupCopy Anchor Link

Install prerequisites on the workspace hostCopy Anchor Link

Connect to your host over SSH, verify its host key fingerprint, and install baseline packages:

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
  ca-certificates curl gnupg python3 openssh-server iptables btrfs-progs

Verify passwordless sudo on the host:

sudo -n true && echo "Passwordless sudo is functional"

Clone repository and install controller CLICopy Anchor Link

On your controller machine, clone the repository and install the raft CLI tool using uv:

git clone https://github.com/Microck/raft.git raft
cd raft
uv sync --locked
uv tool install --editable .

Add ~/.local/bin to PATH and verify the CLI:

export PATH="$HOME/.local/bin:$PATH"
raft --help

Configure host inventory on the controllerCopy Anchor Link

The controller reads host definitions from ~/.config/raft/incus.json. Initialize the configuration directory and template:

mkdir -p ~/.config/raft
cp docs/incus.example.json ~/.config/raft/incus.json
chmod 600 ~/.config/raft/incus.json

Verify interactive SSH to establish known host keys:

ssh user@host-address "echo Host SSH connected successfully"
ssh -o BatchMode=yes user@host-address "echo Batch SSH functional"

Edit ~/.config/raft/incus.json. Set the ssh target. Leave image empty during initial setup:

{
  "lab": {
    "ssh": "user@host-address",
    "image": ""
  }
}

Location names use letters, digits, underscores, or hyphens. The first configured location is the default for raft new.

Provision the dedicated hostCopy Anchor Link

Run the automated host deployer from your controller:

python3 deploy/deploy.py --location lab

Acquire a native workspace imageCopy Anchor Link

Workspaces require an unprivileged Debian 13 development image matching the host architecture:

curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.1.0/raft-dev-arm64.tar.gz
curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.1.0/SHA256SUMS
curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.1.0/manifest-arm64.json

sha256sum --ignore-missing -c SHA256SUMS && \
  sudo incus --project raft image import ./raft-dev-arm64.tar.gz --alias raft-dev

Retrieve and pin the image fingerprintCopy Anchor Link

Query the published raft-dev image on the host:

sudo incus --project raft image list raft-dev --format json | python3 -c '
import json, sys
data = json.load(sys.stdin)
print(next(img["fingerprint"] for img in data if any(a.get("name") == "raft-dev" for a in img.get("aliases", []))))
'

Copy the 64-character hex output into image in ~/.config/raft/incus.json on the controller:

{
  "lab": {
    "ssh": "user@host-address",
    "image": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}

Replace the example string with your actual fingerprint. Raft requires this immutable fingerprint to prevent unexpected image mutations when creating workspaces.

Check host status with doctorCopy Anchor Link

Run raft doctor on your controller to inspect host readiness:

raft doctor

Check that Incus, the network service, and the expiration timer are active. For the full report contents, see Controller diagnostics.