First working box
Launch and manage a workspace after provisioning your host and pinning the image fingerprint (see Installation and setup).
Step 1: Launch a workspace
Create a workspace with raft new:
box=$(raft new --location lab --ttl 600)
echo "Created workspace: $box"The command returns a location-qualified handle formatted as <location>:<instance-name> (for example lab:rf-a1b2c3d4e5f60718).
Omitting --location targets the first location in ~/.config/raft/incus.json. The --ttl flag sets the lifetime in seconds (default: 600).
Step 2: Verify command execution and Docker daemon
Execute commands inside the container with raft exec:
raft exec "$box" -- node --version
raft exec "$box" -- docker version
raft exec "$box" -- docker infoDaemon readiness check
docker version and docker info verify guest dockerd readiness. Running docker --version inspects only the client binary without checking the daemon.
Arguments after -- pass directly to execve. For pipes, redirects, or environment variables, wrap the command in bash -lc '...'.
Step 3: Open an interactive terminal
Open a root terminal session inside the container:
raft ssh "$box"Type exit or press Ctrl+D to disconnect.
User namespace security
Commands run as root in /workspace inside an unprivileged Linux user namespace. Container root maps to an unprivileged high UID on the host, sharing the host kernel.
Step 4: Stop, resume, and destroy
Manage the workspace lifecycle:
# Stop running processes while preserving files and snapshots
raft stop "$box"
# Resume the stopped workspace with a renewed lifetime
raft resume "$box" --ttl 600
# Permanently destroy the workspace and release host capacity
raft destroy "$box"raft stop: Stops running processes and frees active allocations while retaining files and snapshots.raft resume: Starts a stopped container with a new expiration deadline (now + TTL). Does not restore process memory.raft destroy: Permanently deletes the container, filesystem, and snapshots from the host storage pool.
Next steps
- Docker in workspaces: Run nested containers and build images.
- File transfer: Upload and download files over SSH.
- Background jobs: Run detached commands under systemd.
- Desktop and private services: Forward guest ports and open noVNC desktop.
- Snapshots and forks: Capture disk states and create same-host clones.
- Backup and recovery: Export portable archives and restore across hosts.
- Troubleshooting: Diagnose common errors and inspect host services.