GUI Getting Started

Build

From repository root:

make build-gui

Output binary:

bin/autonomy-gui

Run locally

Option A: demo database

make demo-seed-contested
bin/autonomy-gui --db demo/data/contested.db --addr :8090 --dev-mode

Open:

http://localhost:8090

Option B: your own control-plane DB

bin/autonomy-gui --db /path/to/orchestrator.db --addr :8090

Authentication

Production-style

• Provide static bearer tokens via env vars:

  • AUTONOMY_GUI_TOKEN_OPERATOR

  • AUTONOMY_GUI_TOKEN_ANALYST

  • AUTONOMY_GUI_TOKEN_AUDITOR

  • AUTONOMY_GUI_TOKEN_INTEGRATOR

• Send Authorization: Bearer <token>.

Dev mode

When --dev-mode is enabled:

• API accepts ?dev_role=<role> for local testing.

• Token bootstrap endpoint is enabled:

curl -sS -X POST http://127.0.0.1:8090/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"role":"analyst"}'

Role resolution endpoint:

curl -sS http://127.0.0.1:8090/api/v1/auth/me \
  -H "Authorization: Bearer <token>"

Health and baseline checks

curl -sS http://127.0.0.1:8090/healthz
curl -sS http://127.0.0.1:8090/api/v1/config

Troubleshooting

• --db is required: pass --db or set AUTONOMY_GUI_DB.

• bind ... address already in use: stop existing GUI or choose a new port with --addr.

• 401 unauthenticated: provide bearer token or enable dev mode and use ?dev_role=....

• 403 permission-denied: token role lacks required permission for that endpoint.

• 410 api-version-required: call /api/v1/*, not legacy /api/*.

Evidence

• Makefile targets build-gui, demo-seed-contested, demo-contested

• gui/cmd/gui/main.go (flags/env + startup behavior)

• gui/internal/auth/middleware.go

• gui/internal/api/gateway.go

• docs/_generated/test-outputs/gui-help.txt

• docs/_generated/test-outputs/gui-startup.txt