Configuration reference

The Raft controller CLI reads host inventory and image mappings from ~/.config/raft/incus.json.

File location and security

~/.config/raft/incus.json

Ensure the configuration file is accessible only by your user account:

CONTROLLER: Set strict file permissions

chmod 600 ~/.config/raft/incus.json

Schema format

The configuration file maps location names to host definition objects:

Example ~/.config/raft/incus.json

{
  "lab": {
    "ssh": "ubuntu@192.0.2.10",
    "image": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "remote-builder": {
    "ssh": "builder.example.com",
    "image": ""
  }
}

Location keys

Naming format: Matches ^[a-zA-Z0-9][a-zA-Z0-9_-]*$. Starts with an alphanumeric character and contains ASCII letters, digits, underscores, or hyphens.
Default location: The first location listed is the default for raft new. raft list and raft limits accept --location filters; raft doctor and raft gc check all configured hosts.

Host entry fields

Field	Type	Required	Description
`ssh`	`string`	Yes	Non-empty SSH connection string (IP, `user@host`, or SSH host alias from `~/.ssh/config`).
`image`	`string`	For `raft new` only	Full 64-character hexadecimal SHA-256 fingerprint (`^[a-f0-9]{64}$`). An empty string `""` is allowed during initial host provisioning.

Replace placeholder image fingerprint

The image field requires the full 64-character hash for raft new; aliases such as raft-dev are rejected. Replace the example hash with the actual imported image fingerprint for that host.

ARM64 and AMD64 images produce different fingerprints; do not reuse an ARM64 hash on an AMD64 host.

SSH configuration and connection behavior

Primary remote commands (raft ssh, upload, download, and control commands) run OpenSSH with BatchMode=yes and -o ConnectTimeout=10 to fail fast on unreachable hosts. The timeout applies to initial connection establishment, not session or transfer duration.

Other operations, recovery routines, and tunnels use standard SSH defaults without an explicit timeout flag.

Configure host connections in ~/.ssh/config for batch authentication:

~/.ssh/config

Host lab-host
    HostName 192.0.2.10
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

Verify passwordless batch SSH before running Raft commands:

CONTROLLER: Verify passwordless batch connection

ssh -o BatchMode=yes lab-host "echo SSH connection verified"

Configuration referenceCopy Anchor Link

File location and securityCopy Anchor Link

Schema formatCopy Anchor Link

Location keysCopy Anchor Link

Host entry fieldsCopy Anchor Link

SSH configuration and connection behaviorCopy Anchor Link