---
title: The web console
description: 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.
section: deploy
order: 20
audience: [operator]
sources: [services/nodejs-web/lib/auth/session.ts, services/nodejs-web/lib/auth/startup.ts, services/nodejs-web/lib/auth/client-key.ts, services/nodejs-web/lib/auth/ratelimit.ts, services/nodejs-web/app/api/auth/handoff/route.ts, services/nodejs-web/lib/orchestrator.ts, services/nodejs-web/lib/harness.ts, services/nodejs-web/lib/flow-server.ts, services/nodejs-web/lib/scorecard-server.ts, .env.example, docker-compose.yml]
features: [deploy.console-env]
---

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](/docs/deploy/compose.md)); the desktop daemon runs it as its dashboard ([The desktop daemon](/docs/deploy/desktop-daemon.md)).

## Minimal setup {#example}

```bash
# .env
VENOM_ADMIN_TOKEN=<a long random value>
VENOM_CONSOLE_PASSWORD=<what people type at the login page>
```

```bash
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 {#env}

| 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](#proxy)). |
| `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](#handoff)). |
| `VENOM_FLOW_FILE` | `<repo>/dist/flow/metrics.json` | The data file behind the Flow page ([below](#data-files)). |
| `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 {#login}

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 {#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.

```nginx
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 {#agents}

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:

```bash
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](/docs/server-api.md).

## One-time sign-in (desktop daemon) {#handoff}

`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 {#data-files}

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 {#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`). |

## Related

- [Docker Compose and profiles](/docs/deploy/compose.md)
- [Orchestrator admin API](/docs/orchestrator/admin-api.md): what the console reads.
- [The desktop daemon](/docs/deploy/desktop-daemon.md): the console as a dashboard with one-time sign-in.
