navaris-getting-started

name	navaris-getting-started
description	Use when a user is setting up the navaris CLI for the first time, connecting to an existing navarisd, or hitting "how do I start" questions. Covers install, env vars, health check, first project, first sandbox, and common startup errors (401, connection refused, DNS).

Navaris CLI — Getting Started

Gets a user from zero to "I just exec'd something in a sandbox" with minimum friction.

Reference

Install

From source (requires Go 1.26+):

go build -o navaris ./cmd/navaris
sudo mv navaris /usr/local/bin/       # optional; keep local if preferred

Or download a release binary from the navaris releases page and put it on $PATH.

Required env vars

Env var	Required	Purpose
NAVARIS_API_URL	yes	URL of navarisd, e.g. http://localhost:8080
NAVARIS_TOKEN	yes if daemon uses --auth-token	Bearer token for auth
NAVARIS_PROJECT	recommended	Default project ID so --project isn't needed every call

All three are also available as CLI flags: --api-url, --token, --project.

Health check

navaris project list --quiet --output json

Exit 0 = CLI installed, daemon reachable, auth accepted. Non-zero = see errors below.

sandbox create is asynchronous — it returns immediately with an operation; pass --wait to block until provisioning completes and receive the sandbox row instead.

Workflows

1. First-time setup from scratch (daemon + CLI on localhost)

1. Start navarisd (see README.md for daemon flags and the all-in-one Docker option) and capture the auth token it was started with.
2. Export the env vars in the CLI terminal:

   export NAVARIS_API_URL=http://localhost:8080
   export NAVARIS_TOKEN=<token-from-step-1>
   

3. Run the health check:

   navaris project list --quiet --output json
   

   Expect [] on a fresh daemon.

2. Connect to an existing remote navarisd

1. Ask the operator for the base URL and token (or pull them from your secret manager).
2. Export env vars:

   export NAVARIS_API_URL=https://navaris.example.com
   export NAVARIS_TOKEN=<token>
   

3. Run the health check.

3. First project → first sandbox → exec → destroy

1. Create a project and capture its ID:

   PROJECT_ID=$(navaris project create --name playground --output json | jq -r '.ProjectID')
   export NAVARIS_PROJECT="$PROJECT_ID"
   

2. Create a sandbox (Incus by default; image reference with / routes to Incus). --wait blocks until the create operation finishes so the JSON we capture is the sandbox row, not the still-pending operation:

   SANDBOX_ID=$(navaris sandbox create --name hello --image alpine/3.21 --wait --output json | jq -r '.SandboxID')
   

3. Belt-and-suspenders: wait until the sandbox is actually running:

   navaris sandbox wait-state "$SANDBOX_ID" --state running --timeout 60s
   

4. Exec a command:

   navaris sandbox exec "$SANDBOX_ID" -- echo "hello from the sandbox"
   

5. Destroy it:

   navaris sandbox destroy "$SANDBOX_ID" --wait
   

Common errors

Symptom	Cause	Fix
api error 401 (or HTTP 401)	NAVARIS_TOKEN missing or wrong	Re-export NAVARIS_TOKEN with the value the daemon was started with
connection refused	Daemon not running on the configured host/port	Start navarisd or point NAVARIS_API_URL at the right host
dial tcp: no such host	DNS miss or typo in NAVARIS_API_URL	Fix the URL
--project flag or NAVARIS_PROJECT env var is required	sandbox create invoked without a project	Either pass --project <id> or export NAVARIS_PROJECT=<id>