Local Dashboard Development

Run the hosted-style dashboard locally with mock OAuth, disposable state, protected APIs, and filesystem-served UI assets.

Start the local dashboard

make dev-dashboard

The launcher starts two local Go processes: the mock OAuth provider on 127.0.0.1:8090 and cmd/server on localhost:8080. It also creates a temporary API key file, SQLite security store, user store, cookie jar path, and session secret.

Sign in with mock OAuth

Open the dashboard URL printed by the command, or start the OAuth flow directly:

open http://localhost:8080/oauth/google

The mock provider returns [email protected] by default. Override it with NFLTR_DEV_ADMIN_EMAIL when you need to test another account.

Call protected APIs locally

The script prints exact commands with the generated state directory. The flow is:

COOKIE_JAR=/tmp/nfltr-dev-cookies.txt
curl -sS -c "$COOKIE_JAR" -b "$COOKIE_JAR" -L http://localhost:8080/oauth/google >/dev/null
curl -sS -b "$COOKIE_JAR" http://localhost:8080/session
curl -sS -b "$COOKIE_JAR" http://localhost:8080/api/v1/dashboard/agents
curl -sS -b "$COOKIE_JAR" http://localhost:8080/api/v1/dashboard/settings
curl -sS -b "$COOKIE_JAR" http://localhost:8080/api/v1/dashboard/global-settings
curl -sS -b "$COOKIE_JAR" http://localhost:8080/api/v1/dashboard/fleet-tokens

For planner-side protected APIs, use the local API key printed by make dev-dashboard:

curl -sS -H "X-API-Key: dev-local-api-key" \
  -H "Content-Type: application/json" \
  -d '{"tasks":[{"task_id":"local-demo","planner_id":"dev-planner","state":"running","worker_id":"dev-worker","events":[{"at":"2026-01-01T00:00:00Z","kind":"state","detail":"running"}]}]}' \
  http://localhost:8080/api/v1/orchestration/digest

curl -sS -b "$COOKIE_JAR" http://localhost:8080/api/v1/orchestration/tasks
curl -sS -b "$COOKIE_JAR" "http://localhost:8080/api/v1/orchestration/events/tail?limit=50"

Edit website and docs

The server runs with UI_DEV_DIR=web, so HTML, CSS, landing, login, dashboard, and docs files are read from disk. Refresh the browser after editing files under web/.

For TypeScript dashboard changes, rebuild generated JavaScript before refreshing:

make web-build

Useful overrides

NFLTR_DEV_PROXY_PORT=18080 make dev-dashboard
NFLTR_DEV_OAUTH_PORT=18090 make dev-dashboard
NFLTR_DEV_STATE_DIR=.nfltr/dev-dashboard make dev-dashboard
NFLTR_DEV_KEEP_STATE=1 make dev-dashboard
[email protected] make dev-dashboard

Troubleshooting

If startup fails, inspect the log paths printed by the launcher. Port conflicts can be fixed by changing the matching NFLTR_DEV_*_PORT variable. If the browser has an old cookie, visit /logout or remove the cookie jar and sign in again.