| name | navaris-snapshots-images-async |
| description | Use when the user wants to snapshot a sandbox, restore from a snapshot, promote a snapshot to a reusable base image, register an external image, or manage long-running async operations (wait-state, operation wait/get/cancel). Covers stopped vs live snapshots and the async operation lifecycle. |
Navaris CLI — Snapshots, Images & Async Operations
Covers snapshots, images, and the async operation surface that underpins every long-running CLI call.
Reference
Snapshots
| Command | Flags |
|---|
navaris snapshot create --sandbox <sandbox-id> --label <name> | --consistency stopped (default) or live; --wait, --timeout |
navaris snapshot list --sandbox <id> | — |
navaris snapshot get <snapshot-id> | — |
navaris snapshot restore <snapshot-id> | --wait, --timeout |
navaris snapshot delete <snapshot-id> | --wait, --timeout |
stopped consistency requires the sandbox to be in the stopped state — the service enforces this and returns an error if the sandbox is running. live captures a running sandbox (memory + disk) and is only supported by backends that implement it (Firecracker supports live; Incus supports stateful snapshots).
Images
| Command | Flags |
|---|
navaris image promote --snapshot <snapshot-id> --name <n> --version <v> | --wait, --timeout; promotes a snapshot into a reusable image |
navaris image register --name <n> --version <v> --backend <type> --backend-ref <ref> | Register a pre-existing external image (rootfs/kernel) |
navaris image list [--name <partial>] | List images; filter by name |
navaris image get <image-id> | — |
navaris image delete <image-id> | --wait, --timeout |
Operations
Every long-running call (create, start, stop, destroy, snapshot, restore) produces an operation. The CLI usually waits for it to finish (controlled by --wait / --timeout on each command); pass --wait=false to return immediately with the operation ID for later polling.
| Command | Flags |
|---|
navaris operation list | --sandbox <id>, --state <state> (filter) |
navaris operation get <operation-id> | — |
navaris operation wait <operation-id> | --timeout <duration> |
navaris operation cancel <operation-id> | — |
Sandbox wait-state
navaris sandbox wait-state <sandbox-id> --state running [--timeout 60s] [--interval 500ms]
Workflows
1. Safety net: snapshot → upgrade → restore on failure
SNAP_ID=$(navaris snapshot create --sandbox "$SANDBOX_ID" --label pre-upgrade --wait --output json | jq -r '.SnapshotID')
if ! navaris sandbox exec "$SANDBOX_ID" -- ./upgrade.sh; then
echo "upgrade failed, restoring..." >&2
navaris snapshot restore "$SNAP_ID" --wait
fi
2. Promote a working snapshot to a reusable base image
SNAP_ID=$(navaris snapshot create --sandbox "$SANDBOX_ID" --label base-candidate --wait --output json | jq -r '.SnapshotID')
IMAGE_ID=$(navaris image promote \
--snapshot "$SNAP_ID" \
--name my-service-base \
--version 2026.04 \
--wait --output json | jq -r '.ImageID')
3. Register an externally built rootfs/kernel as a Firecracker image
navaris image register \
--name debian-minimal \
--version 12.5 \
--backend firecracker \
--backend-ref /var/lib/firecracker/images/debian-12.5.rootfs
Use this when you build rootfs images yourself (outside navaris) and want them addressable by image reference.
4. Fire-and-forget async with polling and timeout
OP_ID=$(navaris sandbox create \
--name long-boot \
--image alpine-3.21 \
--wait=false --output json | jq -r '.OperationID')
if ! navaris operation wait "$OP_ID" --timeout 5m; then
echo "operation did not finish in 5m, cancelling" >&2
navaris operation cancel "$OP_ID"
fi
Common errors
Cobra's SilenceErrors: true setting plus a bare os.Exit(1) in cmd/navaris/main.go means client errors are not currently printed to stderr. Check $? to confirm the command failed, and read the daemon logs for the underlying cause. The symptom strings below are what the client would render if the suppression were lifted.
| Symptom | Cause | Fix |
|---|
sandbox must be stopped for stopped-consistency snapshot | snapshot create called while the sandbox is running with the default --consistency stopped | Stop the sandbox first (navaris sandbox stop <id> --wait), then snapshot; or pass --consistency live if your backend supports it |
operation <id> failed: ... after image delete | Backend rejected the delete (e.g. backend reference missing or I/O error) | navaris operation get <id> to read the wrapped error text; inspect backend logs for the root cause |
operation stuck in pending | Worker backlog or dependency waiting | navaris operation get <id> to inspect; navaris operation list --state running to see what's busy |
snapshot restore times out | Restore is longer than --timeout | Pass --wait=false and poll with operation wait at a longer timeout |
image register succeeds but sandbox create fails to find it | --backend value doesn't match the backend navarisd is configured to use, or --backend-ref path is not reachable by the daemon | Verify the backend type (incus or firecracker) and that the path exists on the host running navarisd |
