navaris-managing-sandboxes

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>