Configure locations and defaults
Use host onboarding to create inventory and raft config set to manage defaults. Your controller reads both files from ~/.config/raft/; host note and retention policies are separate and apply across controllers.
Configure a location
~/.config/raft/incus.json maps location names to hosts. This is an illustrative entry; replace the SSH target and fingerprint with your host's values before use:
{
"lab": {
"ssh": "ubuntu@192.0.2.10",
"image": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"note": "Preferred for builds"
}
}| Field | Accepted value |
|---|---|
| Location key | Starts with an ASCII letter or digit, then letters, digits, _ or - |
ssh | Required nonempty SSH target, such as user@host or an alias from ~/.ssh/config |
image | Full 64-character lowercase hexadecimal fingerprint for image-based creation; may be empty during provisioning |
note | Optional string of operator guidance, not an enforced restriction |
ARM64 and AMD64 images have different fingerprints. Image aliases are not accepted. Changing a pin affects future image-based creation, not saved boxes or snapshot copies.
The first inventory location is the built-in creation default; an explicit flag or configured default can override it. raft locations reads the file without contacting hosts and marks the first entry as default, even when config.json selects another location. list, capacity, doctor, gc, prune and the config policy report accept --location; without it they contact all configured hosts.
Use raft note lab "Preferred for builds" or raft note lab --clear to change location guidance. Raft preserves location order and writes mode 0600. For manually edited inventory, run chmod 600 ~/.config/raft/incus.json.
Defaults for new
Optional ~/.config/raft/config.json has one top-level defaults object. For example:
{"defaults": {"location": "lab", "ttl": 3600, "cpu": 2, "memory": "4GiB", "disk": "shared", "disposable": false}}| Key | Accepted value | Built-in default |
|---|---|---|
location | Configured location name | First inventory entry |
ttl | 60 to 2,592,000 seconds | 600 |
cpu | Positive whole number, up to the host CPU count | 1 |
memory | Positive whole GiB, such as 16GiB, up to host RAM rounded up to GiB | 2GiB |
disk | Positive whole GiB for an own disk, or shared | shared |
disposable | JSON boolean; true or false in config set | false |
Explicit creation flags win over defaults. Size defaults do not apply to new --from; the snapshot supplies CPU, RAM and disk. A disposable default does apply to snapshot copies. Forks ignore controller defaults entirely. See defaults and policies.
set and unset report changes, write privately and remove the file when no defaults remain. Unknown keys, bad values and malformed JSON fail instead of being ignored. set or unset can repair a recognized key's value; edit malformed JSON or unknown keys directly.
Authenticate over SSH
Verify a host's fingerprint before accepting its key. Configure identities in ~/.ssh/config and confirm ssh -o BatchMode=yes ubuntu@192.0.2.10 'sudo -n true' with your host target.
Raft uses batch SSH without password prompts. Most control, execution and transfer connections use a 10-second connection timeout, not a session-duration limit; recovery and tunnels use SSH defaults without that explicit timeout. An unreachable host does not prove that a remote operation failed or a box is absent.
Control release notices
Set RAFT_NO_UPDATE_CHECK=1 to disable passive release checks. Their cache is $XDG_CACHE_HOME/raft/update.json, or ~/.cache/raft/update.json by default. Notices use stderr and never install an update; global JSON mode suppresses them. See upgrades.