Web Dashboard

The web dashboard is a React SPA served directly by koyal gateway. No separate Node server required.

Starting the Dashboard

# Start gateway (serves API + dashboard)
koyal gateway

# Output:
# [koyal] Gateway   http://127.0.0.1:8790/api
# [koyal] Dashboard http://127.0.0.1:8790/

Open the dashboard:

koyal dashboard open           # opens in default browser
koyal dashboard url            # prints URL to stdout
koyal dashboard status         # checks if gateway is running

How It Works

koyal-gateway auto-detects the web/dist/ directory on startup and serves it as a static SPA:

/assets/{*path} → hashed static files with long-lived cache headers
/* → index.html SPA fallback

The detection probes these paths in order:

Binary-adjacent web/dist/ (binary release tarballs)
$CWD/web/dist/ (source builds)
/koyal-data/web/dist/ (Docker)
/usr/share/koyal/web/dist/ (system packages)
~/.local/share/koyal/web/dist/ (XDG user install)

If none found, the gateway runs API-only mode (no dashboard UI, all API routes still work).

Dashboard Pages

Route	Page	Description
`/`	Overview	Agent summary, halt state, pending proposals
`/agents`	Agents	Agent list, create, tick
`/bots`	Bots	Bot list, lifecycle control, risk config
`/wallets`	Wallets	Wallet list, generate, assign to bot
`/vault`	Vault	Agent bible editor — soul, instructions, memories
`/proposals`	Proposals	Trade proposal queue, approve/reject
`/loops`	Loops	Loop list, create from blueprint, toggle
`/skills`	Skills	Skill catalog, toggle, refresh
`/mcp`	MCP	MCP server list, add, test
`/connectors`	Connectors	Integration connections
`/logs`	Logs	Structured log viewer
`/system`	System	Provider health, token usage, harness status
`/settings`	Settings	Runtime settings editor

Development

Run the dashboard in development mode (hot reload):

cd web
npm install
npm run dev
# Dashboard at http://localhost:3000, API at http://localhost:8790

The Vite dev server proxies /api and /ws to the gateway — configure in web/vite.config.ts.

Build for production:

cd web
npm run build
# Output: web/dist/

Docker

The official Docker image bundles web/dist/ at /usr/share/koyal/web/dist:

# Dockerfile excerpt
COPY web/dist /usr/share/koyal/web/dist

docker run -p 8790:8790 ghcr.io/your-org/koyal:latest
# Dashboard at http://localhost:8790

Reverse Proxy

To expose publicly, proxy with nginx or Caddy and add TLS:

server {
    listen 443 ssl;
    server_name koyal.example.com;

    location / {
        proxy_pass http://127.0.0.1:8790;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

The WebSocket (/ws) requires the Upgrade header passthrough for real-time updates to work.

Dashboard CLI Reference

koyal dashboard open [--host 127.0.0.1] [--port 8790]
    # Open dashboard in default browser

koyal dashboard url [--host 127.0.0.1] [--port 8790]
    # Print dashboard URL

koyal dashboard status [--host 127.0.0.1] [--port 8790]
    # Check if gateway is running and print health JSON

Keyboard shortcuts

Koyal Docs