Gridlane

Gridlane reads a single strict-schema v1 JSON file. The smallest usable shape is one user, one backend, and one browser:

See Router Configuration for every field and validation rule. The parser uses DisallowUnknownFields — misspelled keys are rejected loudly, not silently ignored.

Gridlane listens on :4444 by default. Change it with -listen (see CLI Flags). The image runs as unprivileged 65532:65532 and exposes 4444 (main listener) and 9090 (metrics listener, when -metrics-listen is set).

To enable the admin scope (needed for /config and for /metrics on the main listener), add an admin.token_ref to the config and pass the corresponding environment variable:

Tests connect to Gridlane the same way they would connect to a single Selenwright instance:

Auth is HTTP BasicAuth (for users[]) or bearer token (for admin). See Authentication for the full picture.

Go 1.26, stdlib-only — no go get, no vendoring. Download a prebuilt binary from releases or build locally:

Flags and config file are identical to the container path — the Docker image’s ENTRYPOINT is the binary with no wrapper. Use this form when you are hacking on Gridlane itself, or in environments without a container runtime.

Pick any opaque values for local development and rotate them in real deployments:

A two-backend version of the shape from Quick Start Guide, with the upstream_identity block added:

Each Selenwright backend in this topology runs in trusted-proxy mode with the same router secret:

Selenwright rejects every request whose X-Router-Secret header does not match -trusted-proxy-secret. Without this guard any client could set X-Forwarded-User: alice directly against Selenwright and impersonate any user.

With Gridlane on :4444:

For a Playwright WebSocket handshake smoke using a configured catalog version and backend image:

See Identity Propagation for the deeper view of what happens on each upstream request.

Almost always a typo in the Authorization header. WebDriver session create and Playwright upgrade are user scope — BasicAuth matching a users[] entry, or anonymous guest access if guest is configured. If the header is malformed, Gridlane falls through to the guest check; if guest is not configured the final response is 401.

/quota rejects the same way. If you are getting a 200 on /quota with the same credentials, recheck the header you are actually sending on the WebDriver request — tooling sometimes rewrites headers in unexpected ways.

Side endpoints (/vnc/, /video/, /logs/, /devtools/, /download/, /downloads/, /clipboard/, /history/settings) are side scope — they require BasicAuth matching a users[] entry and do not fall back to guest. Sessions a guest created cannot be observed through VNC unless the observer authenticates as a named user.

See Authentication for the scope ladder.

Yes — Gridlane keeps no per-session state. Public session IDs are r1_<route-token>_<upstream-id>, and the <route-token> is a deterministic HMAC of the backend pool ID. Any replica serving the same router.json will route a follow-up for r1_<token>_…​ to the same backend as the replica that created the session.

See Session ID Format for how this works and Identity Propagation for how the per-request identity survives across replicas.

Yes — SIGHUP reloads the config (unless started with -reload-on-sighup=false). Reload is fail-closed: if the new config fails validation (schema violation, unresolvable secret, bad endpoint URL), the previous runtime keeps serving and the error is logged. You never serve a half-loaded config.

What reloads: users, guest, catalog, backend_pools, admin.token_ref, upstream_identity. What needs a restart: -listen, -metrics-listen, -log-format, -graceful-period, -session-attempt-timeout, -proxy-timeout, -reload-on-sighup.

See Reload (SIGHUP).

Gridlane’s health tracking is passive — it marks a pool unhealthy after failure_threshold consecutive failing proxy attempts through the pool (5xx, 408/425/429, 401/403) and keeps it out of rotation for cooldown. There is no active probe. A backend that is fine right now but failed the last failure_threshold requests will stay out of rotation until cooldown expires, even if the underlying issue has recovered.

Lower cooldown in the pool’s health block if you are seeing recovery lag in development. In production the default makes retries cheap and prevents a flaky pool from burning the whole request flow.

See Backend Health.

Gridlane picks the session ID for Playwright and tells Selenwright about it via X-Selenwright-External-Session-ID on the upgrade. If the Selenwright you’re running does not accept that header, it mints its own random ID — the two sides then disagree about what the session is called, the session itself is fine (frames flow through the tunnel), but everything that addresses the session by ID afterwards (/vnc/<id>, /video/<id>, /logs/<id>, …) `404`s.

Fix: use a Selenwright build that accepts the header. WebDriver is not affected — there the server picks the ID, so any Selenwright works.

No. Without it, Gridlane still authenticates clients, enforces per-user quotas on its own side, and proxies transparently. Upstream Selenwright will see every session as coming from the pool-level BasicAuth account.

Turn on upstream_identity when you want per-user quotas / session ACL / admin bypass on the Selenwright side as well, which is the common production case. See Identity Propagation.

On the main listener, /metrics is admin scope — Prometheus metrics carry per-route latency histograms and per-backend health, which you probably do not want to expose on an internet-reachable listener.

For Prometheus scraping run a separate listener with -metrics-listen :9090 (or another address). That listener serves /metrics with no auth and is intended to be bound to a private interface or an internal overlay network.

Today the HMAC key used to derive the <route-token> prefix is a fixed domain separator (gridlane-route-token-v1), not a per-deployment secret. It stops an attacker from guessing the token for a specific backend pool ID, but two Gridlane deployments that happen to use the same backend_pools[*].id will produce identical tokens.

This is acknowledged tech debt. A -route-salt flag that accepts an env: / file: reference is the planned path forward. Until then, keep pool IDs unique across deployments that might ever share traffic.

The session-create request (POST /session or POST /wd/hub/session) carries the W3C capabilities payload. Gridlane parses browserName and, when present, browserVersion + platformName from alwaysMatch/firstMatch, and looks up a browser entry in the loaded catalog:

If no matching pool is available the client gets 503 Service Unavailable; if the browser is not in the catalog the client gets 400 Bad Request with a W3C-shaped error body.

Pool selection is weighted. Each healthy pool contributes weight slots to the selection pool, and region filtering is applied when the client requests a specific region via capabilities extension (selenwright:options.region). A region mismatch falls back to any region.

Once a backend accepts the session create, Gridlane:

The public ID is what the client uses for every follow-up.

Follow-up requests (GET /session/<id>/url, DELETE /session/<id>, …) carry the public ID on the path. Gridlane splits r1_<route-token>_<upstream-id>:

Because the mapping is deterministic, any Gridlane replica that has the same router.json loaded will route the same follow-up to the same pool without any shared state. Replicas can be round-robin’d behind an L4 load balancer.

If the Selenwright backend enforces its own BasicAuth (or any Authorization header), configure it per-pool:

Gridlane injects BasicAuth on the proxied request with these credentials. The client’s own Authorization header is consumed by Gridlane’s auth layer and is not forwarded.

If upstream_identity is configured, Gridlane additionally stamps X-Forwarded-User, optionally X-Admin, and X-Router-Secret on every upstream request — see Identity Propagation.

Gridlane is protocol-transparent for WebDriver capabilities — whatever the client sends in alwaysMatch/firstMatch is forwarded to Selenwright verbatim. Gridlane does not enforce a capability policy of its own; that lives on the Selenwright side (see Selenwright’s -caps-policy flag).

Every new session counts against the caller’s quota (users[*].quota.max_sessions or guest.quota.max_sessions). When the quota is reached, Gridlane returns 429 Too Many Requests without attempting the upstream call.

Quotas count concurrent sessions that Gridlane has routed for the caller. A session that ends (client DELETE, upstream timeout, upstream 5xx) releases the slot.

The caller can query their own live quota state at GET /quota — see HTTP API.

Gridlane returns W3C-shaped error bodies ({"value":{"error":"…​","message":"…​","stacktrace":""}}) on session create so W3C clients interpret the failure correctly:

Follow-up requests (GET /session/<id>/…​) return the upstream response as-is, including upstream-generated W3C errors, with the session ID rewritten back to the public form.

On the incoming GET /playwright/<browser>/<version> with an Upgrade: websocket header:

Selenwright uses the external-ID header as the session key in its own storage. Clients that do not read headers off the 101 response can still address side endpoints — the public ID is also the one they would see by inspecting the WebSocket URL if they needed to reconnect.

Once a Playwright session is up, the usual Selenwright side surfaces are accessible at their normal paths, using the public session ID. Some are HTTP, some are WebSocket — see HTTP API for the full matrix. Typical examples:

Gridlane forwards these to the pool selected by the public ID’s <route-token>, keeping the public ID on the upstream path (Selenwright stored the session under the public ID, so /vnc/r1_…/ lands on the right container).

These routes are side scope — BasicAuth required, no guest fallback.

A small set of capabilities is accepted as query parameters on the upgrade URL and passed through to Selenwright verbatim:

Gridlane performs no semver matching — <version> must exactly match one of catalog.browsers[].versions[]. Keep the catalog version, the Selenwright image tag, and the client’s connection URL aligned. Playwright client/server major.minor mismatches are rejected by the Playwright protocol itself, not by Gridlane.

WebSocket upgrade failures are returned as regular HTTP responses before the 101. Failures that happen after the upgrade (upstream disconnect, idle timeout) are surfaced as WebSocket close frames.

Public session IDs carry enough information for any Gridlane replica serving the same router.json to route a follow-up to the correct backend, without any shared session state. A client that created a session through Gridlane replica A can send the next request through replica B and it lands on the same Selenwright container.

The route token is also a cheap forgery check: a client that wants to target a specific backend pool has to present a session ID whose route-token matches, which means they had to have a session ID Gridlane issued for that pool. There is no per-session shared key — the HMAC is over the pool ID, not the session — so this is a routing constraint, not an authentication signal. Authentication happens at the scope layer; see Authentication.

The key is a domain separator, not a per-deployment secret. This means:

A -route-salt flag that accepts an env: / file: secret reference is planned to make this a real per-deployment secret; see FAQ. Until then, uniqueness of pool.id is the mitigation.

For WebDriver, Gridlane rewrites the upstream ID to the public form on the session-create response body. The client never sees the raw upstream ID.

For Playwright, Gridlane echoes the public ID back to the client on the 101 Switching Protocols response in X-Selenwright-Session-ID, and also uses it as the path segment for all side endpoints (/vnc/<public-id>, /logs/<public-id>, …).

Every request that carries a session ID on its path (WebDriver /session/<id>/…​, or any Playwright side endpoint) is routed as:

Follow-up requests do not re-check health. A session that belongs to a now-unhealthy pool is still routed to that pool, because:

If the pool is genuinely down, the proxied request fails and the client sees the upstream error shape. The pool’s failure counter ticks up — see Backend Health.

Do not regenerate a Gridlane session ID on the client side. The ID is cryptographically bound to a specific pool via the route token; a hand-crafted ID with the wrong token will route to the wrong pool (or be rejected) and the session will not exist on that backend anyway. Use the ID Gridlane returned.

Per-pool, inside router.json:

Gridlane classifies every proxied request outcome:

Transport-level errors (connection refused, i/o timeout, etc.) are surfaced as 502 Bad Gateway to the client and count as a failure.

Health affects new session placement only. A session that already exists on a now-unhealthy pool is still routed to that pool on follow-up, because:

See Session ID Format for how follow-up routing works.

GET /status returns a rolled-up view of all pools:

available_count is the number of pools currently in the healthy state. If any pool is in cooldown, available_count < backend_count. If no pool is healthy, status becomes degraded and new session placement returns 503.

/status is public — no auth required. It is intended for external health-check probes.

Per-pool health is also exposed as a gauge:

available is 1 when the pool is in the healthy state, 0 when in cooldown. failures_total, despite its name, is the count of current consecutive failures — it ticks up while the pool misbehaves and resets to 0 on the first subsequent success or when the cooldown expires. See Observability.

Defaults (failure_threshold=1, cooldown=30s) are tuned for production where any backend failure is a real signal and a brief removal from rotation is cheap. In local development with a single backend, you probably want failure_threshold=3 and cooldown=5s so a transient issue during setup does not shut down the whole grid. For very flaky environments (shared CI hosts, spot instances), bump failure_threshold higher to avoid oscillation.

A request is evaluated bottom-up — a valid admin token satisfies all four scopes; valid BasicAuth satisfies user, side, and public; guest satisfies only user and public.

Defined in router.json:

Passwords are compared in constant time. BasicAuth credentials are consumed by Gridlane and are not forwarded upstream; if the backend pool enforces its own BasicAuth, use the pool-level credentials block — see Router Configuration.

When guest is configured, requests that arrive at a user-scope endpoint without BasicAuth (or with BasicAuth that does not match any users[] entry) are admitted as an anonymous guest:

Guest requests share a single quota pool keyed on the literal subject guest. When the pool’s max_sessions is reached, further guest session creates get 429.

Guest access applies to user scope only. Side endpoints always require named BasicAuth — there is no way to VNC into a guest-created session without authenticating as a user first.

Omit the guest block entirely to disable anonymous access. At least one of users[] or guest must be present.

The admin scope unlocks endpoints that expose internal state (/config, /metrics on the main listener). Configure a reference to the token:

Gridlane reads the token at startup and on reload. Clients present it in one of two forms:

Both forms are compared in constant time. The Bearer form wins if both headers are set.

If admin.token_ref is omitted, /config and main-listener /metrics are permanently unavailable — there is no in-band way to mint an admin token, deliberately.

Passwords and tokens never appear in plaintext in router.json. Every *_ref field accepts one of:

Anything else — plaintext, relative path, bare : — is rejected with a validation error. This is a hard rule; there is no plaintext fallback.

Secrets are re-resolved on every reload. Rotate a password by updating the referenced env var / file and sending SIGHUP.

All password and token comparisons use crypto/subtle.ConstantTimeCompare after a length check. This is defense in depth; the primary protection against credential guessing is rate-limiting at the network edge, which Gridlane does not implement itself.

Gridlane logs the authenticated subject and scope on every request (subject=alice scope=user, subject=guest scope=user, subject=admin scope=admin). Passwords, tokens, and the Authorization header contents are never logged.

A concrete routing example. Assume users[] has alice, guest is configured with max_sessions=2, and admin.token_ref points to root-token:

Inside router.json:

Omit the entire upstream_identity block to keep the legacy behavior — Gridlane authenticates the client on its own and forwards nothing about the identity upstream.

On every upstream request Gridlane stamps:

For a guest-scope request, <user_header> is set to the literal string guest — it is still a named identity from Selenwright’s perspective, just a shared one.

The pool-level credentials block (BasicAuth injection) is independent of this. Gridlane can both inject Authorization: Basic …​ for Selenwright’s legacy -htpasswd mode and stamp identity headers. Selenwright will honour whichever matches its running auth mode.

Before Gridlane’s own auth layer runs, a middleware strips these headers from the incoming request:

This means a client cannot set X-Forwarded-User: alice themselves and inherit Alice’s identity downstream — the header is erased before any auth decision happens, and Gridlane re-derives the identity from the client’s real credentials.

Selenwright in trusted-proxy mode honours identity from headers only when the source is trusted. Run Selenwright with:

-trusted-proxy-secret must resolve to the same value as Gridlane’s upstream_identity.secret_ref. Selenwright rejects any request whose X-Router-Secret does not match — so a direct client that bypasses Gridlane and tries to spoof X-Forwarded-User against Selenwright gets 401.

Selenwright also supports -trusted-proxy-cidr and -trusted-proxy-mtls-ca for additional source-trust validation. Combine them — AND across all configured checks — when the overlay network itself is not trustworthy.

With the setup above, Selenwright logs a DELETE /session/<id> like:

And Selenwright enforces its own per-user ACL against alice, not against the pool service account. Alice can only kill her own sessions; a team member in Alice’s Selenwright-side group can observe them; Selenwright admin bypass works for Gridlane admins.

secret_ref is technically optional. Without it, Gridlane still stamps X-Forwarded-User / X-Admin on upstream requests, but there is nothing to distinguish a request from Gridlane from a direct client on the same network that forged X-Forwarded-User. Selenwright-side identity would be trivially spoofable.

Leave secret_ref out only when the overlay network between Gridlane and Selenwright is itself authenticated (mTLS, a private overlay with no other clients) and Selenwright’s trusted-proxy-cidr / trusted-proxy-mtls-ca already gate by source trust.

For the default local-compose topology, always set secret_ref.

Update the referenced env var or file and send SIGHUP to both Gridlane and Selenwright. Both sides re-resolve the secret on reload. There is a brief window during rotation where Gridlane and Selenwright disagree — plan the rotation order (update Selenwright’s new value first, then flip Gridlane over) or accept a short read failure.

The log line on every request includes subject=<name> scope=<scope>. When an upstream request is made with identity headers, the line also includes upstream_identity=true. /metrics counts admin-scope requests separately (via the route label on /config / /metrics).

See Observability for the full metric list.

Inside Docker:

Disable with -reload-on-sighup=false if you prefer to roll out config changes via restart only.

Everything that lives in router.json:

Health state is reset for pools that are new or whose endpoint / id changed. Pools that survive the reload unchanged keep their failure counter and cooldown state.

Anything that is not in router.json — that is, every CLI flag:

Flags are frozen at startup. Move anything you need to tune live into router.json fields.

Reload proceeds in phases:

The swap is a single atomic.Value.Store call. Concurrent in-flight requests finish against whichever handler they started with — there is no torn state where a request sees a mix of old and new config.

A reload logs one of:

The error message is the specific validation or resolution failure so you can fix the file and SIGHUP again without reading through the whole process log.

Confirm the new config took effect with the admin /config endpoint:

The response is the sanitized view of the live config — secrets are redacted, resolved values are not included. If /config still shows the old pool list after a SIGHUP, the reload either did not happen (log) or failed (log). Check the log.

If Gridlane starts up successfully but the current runtime is later invalidated (for example, the file that admin.token_ref=file:…​ points at is deleted, then SIGHUP is sent), the reload fails and the old runtime keeps serving. The admin token the old runtime loaded on startup is still valid.

The runtime is only torn down on process exit.

Prometheus text format on /metrics. On the main listener it is admin scope (X-Gridlane-Admin-Token or Authorization: Bearer). When -metrics-listen is set to a separate address (typically bound to a private interface), /metrics there has no auth.

Gridlane emits one log/slog record per request and one per lifecycle event. Pick the format with -log-format:

Per-request fields:

Passwords, tokens, the Authorization header, and X-Router-Secret are never logged.

Lifecycle log lines include config reload (msg="config reloaded" / msg="config reload failed"), startup (msg="listening"), and shutdown (msg="gracefully stopping").

Public JSON rollup for external health probes:

status is "ok" when at least one pool is healthy, "degraded" otherwise. A degraded /status with available_count=0 means every new session placement is failing with 503.

Gridlane does not emit OpenTelemetry spans today. The gridlane_http_request_duration_seconds histogram combined with backend / route labels is the current latency breakdown surface. If you need end-to-end tracing across Gridlane and Selenwright, run a sidecar proxy that injects W3C traceparent on the ingress edge — Gridlane forwards unknown request headers transparently.

Omit the block to disable anonymous access. When enabled, guest applies to user scope only — side endpoints still require named BasicAuth. See Authentication.

catalog.browsers[] must be non-empty. Per entry:

The catalog is advertised via /quota and is the authoritative source of truth for which Playwright /<browser>/<version> paths are accepted.

credentials (optional):

health (optional):

See Identity Propagation for the end-to-end behavior.

Every *_ref field accepts exactly two forms:

Anything else — a raw password string, a relative path, a URL — is rejected with a validation error. There is no plaintext fallback.

Secrets are re-resolved on every reload. Rotate a secret by updating the env var or the file content, then SIGHUP.

Gridlane validates the whole config before it replaces the live runtime. The most common reasons a reload (or startup) fails:

Every failure is logged with the JSON path of the bad field (e.g. backend_pools[1].endpoint must use http or https) so a reload failure is self-diagnosing.

See examples/router.compose.json for the canonical example that ships with the repo.

Liveness. Returns 200 with a fixed body. No auth.

Rolled-up backend view. No auth.

status is "ok" when at least one pool is healthy, "degraded" otherwise. See Backend Health.

Caller’s own quota. user scope — BasicAuth matches the returned user, or (when guest is configured) an unauthenticated request returns the guest quota.

The users array contains only the requesting user; other users' quotas are never exposed. guest is omitted when guest access is disabled.

Sanitized live config — no secrets, no resolved passwords, no admin token. admin scope.

Returns a JSON body shaped like router.json with *_ref fields rendered as-is ("env:GRIDLANE_ALICE_PASSWORD") and no resolved plaintext. Safe to dump into a log or paste into a ticket.

Prometheus text format. On the main listener it is admin scope; on the -metrics-listen listener it has no auth. See Observability for the metric list.

POST /session or POST /wd/hub/session — user scope. Gridlane routes the session create by catalog + weighted pool selection, then rewrites the upstream session ID in the response body to the public form.

Follow-up requests (GET /session/<id>/url, DELETE /session/<id>, …) route by the <route-token> embedded in the public ID. Gridlane rewrites the session segment on the upstream path before proxying.

See WebDriver Routing.

GET /playwright/<browser>/<version> with Upgrade: websocket — user scope. Gridlane mints a public session ID, sends the upgrade upstream with X-Selenwright-External-Session-ID, and echoes the public ID back on the 101 response in X-Selenwright-Session-ID.

See Playwright Routing.

All side endpoints are side scope — BasicAuth matching a users[] entry, no guest fallback. The session ID on the path is the Gridlane public ID; Gridlane decodes it, picks the backend by the embedded route-token, and rewrites the upstream path per protocol: for WebDriver it substitutes the decoded upstream ID (Selenwright stored the session under that); for Playwright it keeps the public ID (Selenwright stored the session under the public ID via X-Selenwright-External-Session-ID). For /video/ Gridlane appends .mp4 if the client omitted it.

Most endpoints return a minimal body on failure — the status code is authoritative:

WebDriver session create returns a W3C-shaped error body on 4xx/5xx:

Durations use Go time.Duration format: 500ms, 30s, 2m, 1h.

See Observability for the field catalog.

Mount the config read-only. Pass secrets through environment variables — Gridlane reads them at startup and on reload via the env:NAME references in router.json.

Rotate a password or the admin token:

(env: references pin the value at process start. To rotate the in-process value you either restart the container or, for file: references, update the mounted file and send SIGHUP. For strict rotations without restart, use file: refs with a tmpfs secret mount.)

End-to-end recipe: one Gridlane in front of two Selenwright backends, with trusted-proxy identity propagation. See Running With Selenwright for the router.json shape.

Bring it up with the three secrets in your environment:

Exposed ports:

Smoke checks follow the pattern from Running With Selenwright.

The Dockerfile is a multi-stage build with no build-time args you need to set. The resulting image tag is gridlane:local; run it the same way as the published image.

Pin production deployments to a specific semver tag, not latest-release.