seleniferous

Per-pod sidecar proxy for the Selenosis browser platform. It lives inside every browser pod, fronts the browser for Selenium, Playwright, and MCP traffic, gives the session a stable identity, and tears the pod down when the session ends or goes idle.

What it does

seleniferous is not something you run by hand — it ships inside the browser pod as a sidecar and is driven by the selenosis hub. In that pod it:

• Fronts the browser. Proxies WebDriver (incl. BiDi), Chrome DevTools Protocol, Playwright (WebSocket), and MCP traffic to the local browser process on BROWSER_PORT.
• Gives the session a stable identity. Rewrites the browser-provided sessionId to a deterministic, pod-derived UUID, so routing stays stateless across the whole stack.
• Owns the session lifecycle. Tracks create and idle timeouts and tears the pod down when the session ends or goes idle — no orphaned browsers.
• Exposes per-session helper routes. Internal HTTP routing to custom sidecars and a VNC proxy endpoint, both used by selenosis and browser-ui.

How it fits

A request travels client → selenosis (hub) → seleniferous (this sidecar) → browser. The hub resolves which pod a session belongs to and proxies traffic to that pod's seleniferous; seleniferous forwards it to the browser next to it and manages everything session-scoped. See the selenosis architecture for the full picture.

You normally don't deploy seleniferous directly — it's attached to every browser pod through a BrowserConfig sidecar entry. The Helm chart and example BrowserConfigs in selenosis-deploy wire it up for you.

Session identity

This is the mechanism that keeps the whole platform stateless — worth understanding before touching any routing code.

A pod's IP maps to a deterministic UUID (IPUUID) and back. seleniferous rewrites the real upstream session id (the browser's WebDriver session id, or the MCP session) to that stable, pod-derived id on the way out, and maps it back on the way in. Because the id encodes the pod, selenosis can route any later request straight to the right pod by decoding it — there is no session registry anywhere. The same scheme carries the id in the WebDriver sessionId for Selenium/Playwright and in the Mcp-Session-Id header for MCP.

Configuration

seleniferous is configured via environment variables:

Endpoints

seleniferous exposes Selenium-compatible endpoints plus internal proxy routes for selenosis.

Request flow

1. selenosis proxies POST /wd/hub/session to POST /session on the sidecar.
2. seleniferous forwards the request to the local browser on BROWSER_PORT.
3. The browser returns a sessionId; seleniferous rewrites it to the pod IPUUID.
4. All subsequent requests are proxied by seleniferous to the browser, and each one resets the idle timeout. When it expires (or the session is deleted), the pod is torn down.

# Create a session
curl -sS -X POST http://{pod_ip}:4445/session \
  -H 'Content-Type: application/json' \
  -d '{ "capabilities": { "alwaysMatch": { "browserName": "chrome", "browserVersion": "120.0" } } }'

# Proxy a command on an existing session
curl -sS -X GET http://{pod_ip}:4445/session/<sessionId>/url

Internal HTTP routing (ROUTING_RULES)

seleniferous can route HTTP requests arriving on /selenosis/v1/sessions/{sessionId}/proxy/http/* to targets reachable inside the browser pod — a file server, a recorder, a mock backend, any custom sidecar — so per-session helpers are reachable through the hub at the same host and auth as the browser.

[
  {
    "pathRegex": "^/selenosis/v1/sessions/[^/]+/proxy/http/(?P<path>.*)$",
    "target": "127.0.0.1:8080",
    "rewritePath": "/{path}"
  }
]

ROUTING_RULES='[{"pathRegex":"^/selenosis/v1/sessions/[^/]+/proxy/http/(?P<path>.*)$","target":"127.0.0.1:8080","rewritePath":"/{path}"}]'

MCP (experimental)

seleniferous proxies Model Context Protocol Streamable HTTP traffic to an MCP server running inside the browser container on BROWSER_PORT, exposed on a single /mcp endpoint (POST / GET / DELETE). One MCP session per pod.

Networking and headers

Behind a reverse proxy or ingress, set X-Forwarded-Proto and X-Forwarded-Host so seleniferous can build correct external URLs.

Build

The project builds and packages entirely via Docker — a local Go install is not required.

License

Apache-2.0