Skip to content
Docs menu

The web console

Configure the venom web console's login, reverse-proxy trust, connection to the orchestrator and venom serve, and the data files behind its Flow and Scorecards pages.

View .md

The console is a Next.js app over the orchestrator's admin API: requests, spend, keys, routes, upstreams, local models, sessions and agents. It holds no data of its own; it reads the orchestrator (and, for the Agents pages, venom serve) server-side, so no key reaches the browser. Compose runs it as the web service (Docker Compose); the desktop daemon runs it as its dashboard (The desktop daemon).

Minimal setup

# .env
VENOM_ADMIN_TOKEN=<a long random value>
VENOM_CONSOLE_PASSWORD=<what people type at the login page>
make up                         # console on http://127.0.0.1:3000

To serve it to other machines, put a TLS reverse proxy in front, then set WEB_BIND=0.0.0.0 (or keep loopback and let the proxy on the same host reach it) and VENOM_CONSOLE_TRUST_PROXY=1.

Environment variables

Variable Default What it does
VENOM_CONSOLE_PASSWORD empty: VENOM_ADMIN_TOKEN is the password The login password. Outside production, with neither set, the password is dev-admin-token.
VENOM_ADMIN_TOKEN none in production; dev-admin-token outside it The orchestrator admin token the console sends to /admin/v1/*, and the login fallback. A production console with neither this nor VENOM_CONSOLE_PASSWORD exits at start.
VENOM_API_KEY none in production; dev-venom-key outside it A /v1 client key, for the Playground and other pages that call models.
VENOM_ORCH_URL http://localhost:8787 (compose: http://orchestrator:8787) Where the console reaches the orchestrator.
VENOM_BASE_URL VENOM_ORCH_URL + /v1 The /v1 URL the console shows people for their SDKs. Only displayed.
VENOM_CONSOLE_TRUST_PROXY off Exactly 1 (not true) when a reverse proxy you run fronts the console and every request goes through it (below).
VENOM_SERVE_URL http://127.0.0.1:8790 (compose: http://host.docker.internal:8790) Where the Agents pages reach venom serve.
VENOM_SERVER_TOKEN empty: the Agents pages say "not configured" The bearer token venom serve runs with (16 characters or more). Used server-side only.
VENOM_CONSOLE_HANDOFF_DIR unset: /api/auth/handoff answers 404 The directory of one-time sign-in tokens. Only the desktop daemon's launcher sets it (below).
VENOM_FLOW_FILE <repo>/dist/flow/metrics.json The data file behind the Flow page (below).
VENOM_SCORECARD_FILE <repo>/dist/scorecards/runs.json The data file behind the Scorecards page.
WEB_BIND, WEB_PORT 127.0.0.1, 3000 Compose only: the host address and port the console is published on.

<repo> is two directories above the console's working directory, which is the checkout root when it runs from services/nodejs-web.

Login and sessions

The login page checks one shared password. A successful login sets an HttpOnly cookie, venom_session, valid for 12 hours and signed with a key derived from the password, so changing the password (or the admin token it falls back to) signs everyone out. Logging out also revokes that cookie for the rest of its life; the revocation list is in memory, so it is lost on restart and not shared between replicas. Run one replica.

The cookie is marked Secure when the request came over HTTPS, read from X-Forwarded-Proto when a proxy sets it. Serving the console over plain HTTP on a network is possible but sends the password and the cookie in the clear.

Rate limit. Failed logins are limited to 5 per client per 15 minutes (then 429 until the window ends) and 100 per 15 minutes across all clients. A successful login clears the client's count. State is per process.

Behind a reverse proxy

By default the console identifies a client by the TCP peer address and ignores X-Forwarded-For, because a client reaching it directly could put anything there and get a fresh rate-limit bucket on every try. Behind your own proxy every peer is the proxy, so all clients would share one bucket.

VENOM_CONSOLE_TRUST_PROXY=1 changes two things:

  • the rate limiter keys on the rightmost X-Forwarded-For entry (the one your proxy appended), then X-Real-IP, then the peer;
  • the cross-site check compares Origin with X-Forwarded-Host instead of Host.

Set it only when every request comes through the proxy. With the console reachable directly as well, any client could choose its own key again.

location / {
  proxy_pass http://127.0.0.1:3000;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-Host $host;
}

The Agents pages

The Agents pages list and drive venom serve sessions. venom serve is not a compose service; run it on the host and give both sides the same token:

export VENOM_SERVER_TOKEN=$(openssl rand -hex 32)
echo "VENOM_SERVER_TOKEN=$VENOM_SERVER_TOKEN" >> .env
venom serve --root ~/work        # listens on 127.0.0.1:8790
make up

From the compose console, venom serve is reached through host.docker.internal. The server's API is documented in the Server API section.

One-time sign-in (desktop daemon)

GET /api/auth/handoff?token=<t>&next=<path> signs a browser in without a password. The desktop daemon's launcher writes the SHA-256 of a random token to a file in VENOM_CONSOLE_HANDOFF_DIR with a two-minute expiry, then opens that URL. A valid, unexpired, unused token gets the same session cookie as a password login and continues to next (same origin only) or /; the file is deleted on first use. Anything else goes to /login?error=handoff and counts as a failed login. Without the variable the route does not exist (404), so a compose or self-hosted console has no passwordless entry.

The Flow and Scorecards pages

Two console pages read JSON files that scripts in the console's directory write from local data only:

Page File Written by
Flow: lead time, review wait, revert rate, $ per merged change over 30 days VENOM_FLOW_FILE node services/nodejs-web/scripts/flow-metrics.mjs [--days 30] [--ref origin/main] [--out <file>]: squash merges on main from git log, reverts, and this machine's gate logs. The $ comes from the orchestrator's spend ledger.
Scorecards: weekly pass rate, cost and $ per solved task per model, gear and role VENOM_SCORECARD_FILE node services/nodejs-web/scripts/scorecards.mjs [--days 90] [--dir evals/results] [--out <file>]: one row per eval run result.

Run them from services/nodejs-web on whatever schedule you like. A missing or malformed file shows the page's empty state.

Troubleshooting

Symptom Cause and fix
venom console: refusing to start. Set VENOM_CONSOLE_PASSWORD (or VENOM_ADMIN_TOKEN) A production build with no login credential. Set one.
Everyone was signed out The password or admin token changed, or the console restarted after a logout (sessions themselves survive restarts).
Login says too many attempts for every user behind a proxy Set VENOM_CONSOLE_TRUST_PROXY=1.
Requests from the browser fail as cross-site behind a proxy Forward Host, or X-Forwarded-Host with VENOM_CONSOLE_TRUST_PROXY=1.
Pages show the orchestrator as unreachable Check VENOM_ORCH_URL from the console's point of view (inside Docker, not localhost).