navaris-managing-sandboxes

name	navaris-managing-sandboxes
description	Use when the user wants to create, list, start, stop, or destroy navaris sandboxes, manage projects, publish ports, or decide between the Incus and Firecracker backends. Covers the full sandbox lifecycle plus project/port CRUD.

Navaris CLI — Managing Sandboxes & Projects

Covers projects, sandbox lifecycle, port forwarding, and backend selection.

Reference

Projects

Command	Purpose
navaris project create --name <n>	Create a project
navaris project list	List projects
navaris project get <project-id>	Get one
navaris project update <project-id> --name <n>	Rename
navaris project delete <project-id>	Delete

Sandboxes

Command	Key flags
navaris sandbox create	--name, --image (required), --cpu, --memory, --project (or NAVARIS_PROJECT), --wait, --timeout
navaris sandbox list	(filters via --project)
navaris sandbox get <sandbox-id>	—
navaris sandbox start <sandbox-id>	--wait, --timeout
navaris sandbox stop <sandbox-id>	--force, --wait, --timeout
navaris sandbox destroy <sandbox-id>	--wait, --timeout

Use -q / --quiet on create/start/stop/destroy to print only the resulting ID (good for scripting).

sandbox create and sandbox list both require --project or NAVARIS_PROJECT.

Ports

Command	Purpose
navaris port create --sandbox <id> --port <target-port>	Publish a sandbox port to the host (published host port is daemon-assigned; see HOST_ADDRESS/PUBLISHED_PORT in the response)
navaris port list --sandbox <id>	List published ports
navaris port delete --sandbox <id> <target-port>	Unpublish

Backend selection

Auto-detected from the image reference:

• Slash-style (alpine/3.21, ubuntu/22.04) → Incus container
• Flat-style (alpine-3.21, debian-12) → Firecracker microVM

Override with --backend incus or --backend firecracker on sandbox create if you have a reason to pin.

Workflows

1. Ephemeral dev sandbox on Incus (fast, throwaway)

Best when you want quick iteration and don't need hardware-level isolation.

SANDBOX_ID=$(navaris sandbox create \
  --name dev-$$ \
  --image alpine/3.21 \
  --cpu 2 --memory 1024 \
  --wait --output json | jq -r '.SandboxID')
navaris sandbox wait-state "$SANDBOX_ID" --state running --timeout 60s
# ... use it ...
navaris sandbox destroy "$SANDBOX_ID" --wait

2. Isolated untrusted workload on Firecracker (hardware isolation)

Best for running user-submitted code, multi-tenant workloads, or anything security-sensitive.

SANDBOX_ID=$(navaris sandbox create \
  --name scan-$$ \
  --image alpine-3.21 \
  --cpu 1 --memory 512 \
  --wait --output json | jq -r '.SandboxID')
navaris sandbox wait-state "$SANDBOX_ID" --state running --timeout 120s
navaris sandbox exec "$SANDBOX_ID" -- ./scan.sh
navaris sandbox destroy "$SANDBOX_ID" --wait

Firecracker startup is a bit slower than Incus — allow ~2-3s plus image load time.

3. Publish a port and verify it's reachable

navaris sandbox exec "$SANDBOX_ID" -- sh -c 'nc -l -p 8000 &'
navaris port create --sandbox "$SANDBOX_ID" --port 8000 --output json
# response contains HOST_ADDRESS and PUBLISHED_PORT — capture them for curl:
PUBLISHED=$(navaris port list --sandbox "$SANDBOX_ID" --output json | jq -r '.[] | select(.TargetPort==8000) | "\(.HostAddress):\(.PublishedPort)"')
curl -fsS "http://$PUBLISHED/"

To tear down: navaris port delete --sandbox "$SANDBOX_ID" 8000.

4. Bulk-destroy all sandboxes in a project

navaris sandbox list --project "$NAVARIS_PROJECT" --output json \
  | jq -r '.[].SandboxID' \
  | xargs -n1 -I{} navaris sandbox destroy {} --quiet

Each line is the destroy operation ID, not the sandbox ID. Add --wait to each invocation if you need the loop to block until every sandbox is actually gone (slower but safer).

Common errors

Symptom	Cause	Fix
operation ... failed: firecracker copy rootfs ...: open ...: no such file or directory (Firecracker) or operation ... failed: incus create instance: ... (Incus)	Image ref typo, image not registered for that backend, or image present in a different store	navaris image list --name <partial> to find the right ref; for Incus use slash-style (alpine/3.21), for Firecracker use flat-style (alpine-3.21); register a missing image with navaris image register
api error 500: internal server error after sandbox create	Daemon doesn't have the requested backend enabled — common causes: Firecracker requested but /dev/kvm unavailable; Incus requested but daemon started without the Incus socket; rootfs/image directory not mounted	Check daemon startup logs (provider "<name>" not available); restart navarisd with the right backend flags (see README.md); pick an image that routes to a supported backend
operation <id> failed: ... after destroy	Backend rejected the destroy (e.g. provider error, transient I/O)	navaris operation get <op-id> to read the wrapped error text; retry or escalate based on the underlying message
--project flag or NAVARIS_PROJECT env var is required	sandbox create or sandbox list invoked without a project	Set NAVARIS_PROJECT in the environment, or pass --project <id>