A stateless Selenium hub for Kubernetes that creates a browser resource per session and proxies traffic to it.

• What it does
• Requirements
• Configuration
• Endpoints
• Request flow
• Examples
  • Create a session
  • Proxy a command
• WebDriver BiDi support
• CDP support
• Networking and headers
• selenosis:options
  • Supported scope
  • Example payload
  • Behavioral notes
• Playwright (experimental)
• MCP (experimental)
  • Create an MCP session
  • Proxying MCP traffic
  • Terminating an MCP session
  • MCP Playwright example
  • MCP Selenium example
• Basic authentication
• Build and image workflow
• Deployment

• Selenosis exposes Selenium-compatible endpoints on both / and /wd/hub.
• Creates a Browser resource via browser-service based on requested capabilities.
• Waits for the browser pod to become ready, then proxies traffic to the sidecar seleniferous inside that pod.

• Kubernetes cluster.
• browser-controller CRDs installed (for Browser and BrowserConfig resources).
• browser-service running and reachable at BROWSER_SERVICE_URL.
• Browser pod image includes seleniferous sidecar listening on PROXY_PORT.

Selenosis is configured via environment variables:

Selenosis exposes Selenium-compatible endpoints on both / and /wd/hub.

1. Client calls POST /wd/hub/session with W3C capabilities, WS /playwright/{name}/{version}, or POST /mcp?browser=<name>&version=<version>} (MCP initialize).
2. Selenosis creates a Browser resource via browser-service.
3. When the browser pod is Running, Selenosis maps its IP to a UUID session id.
4. All session requests are proxied to the sidecar seleniferous in that pod.

curl -sS -X POST http://{selenosis_host:port}/wd/hub/session \
  -H 'Content-Type: application/json' \
  -d '{
    "capabilities": {
      "alwaysMatch": {
        "browserName": "chrome",
        "browserVersion": "120.0"
      }
    }
  }'

The response is proxied from the browser and contains the sessionId used for subsequent requests.

curl -sS -X GET http://{selenosis_host:port}/wd/hub/session/<sessionId>/url

Selenosis supports WebDriver BiDi by proxying WebSocket connections per session.

To enable BiDi, request webSocketUrl: true in capabilities.

curl -X POST http://{selenosis_host:port}/wd/hub/session \
  -H 'Content-Type: application/json' \
  -d '{
    "capabilities": {
      "alwaysMatch": {
        "browserName": "chrome",
        "browserVersion": "120.0"
        "webSocketUrl": true
      }
    }
  }'

The response will include capabilities.webSocketUrl for the BiDi connection.

Chromium-based browsers can expose Chrome DevTools Protocol (CDP). Selenosis transparently proxies CDP traffic through the seleniferous sidecar.

WS /playwright/{name}/{version}

The /playwright/{name}/{version} endpoint is responsible for provisioning a Browser resource and proxying the current WebSocket connection to the seleniferous sidecar.

The request flow is as follows:

• The endpoint extracts the browser name and version from the URL path.
• Query parameters are parsed and interpreted as Selenosis options, allowing dynamic configuration of the underlying Kubernetes resources (for example, labels or environment variables).
• A new Browser custom resource is created in Kubernetes using the resolved configuration.
• A WebSocket reverse proxy is established, and the current WebSocket connection is transparently proxied to the seleniferous sidecar.

import { chromium } from 'playwright';

const browser = await chromium.connect({
  wsEndpoint: 'ws://http://{selenosis_host:port}/playwright/playwright-chrome/1.58.0'
});

const context = await browser.newContext();
const page = await context.newPage();

await page.goto('https://example.com');
await page.screenshot({ path: 'example.png' });

await browser.close();

If you run behind a reverse proxy or ingress, set these headers so Selenosis can build correct external URLs for the sidecar:

• X-Forwarded-Proto
• X-Forwarded-Host

Selenosis also adds Selenosis-Request-ID to outgoing requests for tracing.

selenosis options is a vendor-namespaced WebDriver capability that allows users to pass session-specific overrides to Selenosis without changing CRDs or cluster-level configuration.

The options are attached to the Browser resource (via annotations) and applied by the controller at Pod creation time.

• labels: Kubernetes labels applied to the Browser Pod

• containers..env: environment variables injected into matching containers

The controller does not rely on hard-coded container names. It iterates over the Pod containers and applies overrides only when names match.

selenosis:options = {
  "labels": { "<string>": "<string>" },
  "containers": {
    "<containerName>": {
      "env": { "<ENV_NAME>": "<ENV_VALUE>" }
    }
  }
}

Pod Labels:

labels.<key>=<value>

Container environment variables:

containers.<container>.env.<ENV_NAME>=<value>

• labels are optional.
• containers is optional.
• Each section is applied independently.

{
  "capabilities": {
    "alwaysMatch": {
      "browserName": "chrome",
      "version": "139.0",
      "selenosis:options": {
        "labels": {
          "team": "qa"
        },
        "containers": {
          "browser": {
            "env": {
              "LOG_LEVEL": "debug"
            }
          },
          "seleniferous": {
            "env": {
              "SESSION_IDLE_TIMEOUT": "3m"
            }
          }
        }
      }
    }
  }
}

Result

Pod labels:

team=qa

Container browser receives:

LOG_LEVEL=debug

Container seleniferous receives:

SESSION_IDLE_TIMEOUT=3m

If a container name does not exist in the Pod, its configuration is ignored.

import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;

import java.net.URL;
import java.util.HashMap;
import java.util.Map;

public class SelenosisOptionsExample {

  public static void main(String[] args) throws Exception {

    DesiredCapabilities caps = new DesiredCapabilities();
    caps.setCapability("browserName", "chrome");

    // Global labels
    Map<String, String> labels = new HashMap<>();
    labels.put("project", "payments");

    // Container env vars
    Map<String, String> browserEnv = new HashMap<>();
    browserEnv.put("LOG_LEVEL", "debug");

    Map<String, Object> browserContainer = new HashMap<>();
    browserContainer.put("env", browserEnv);

    Map<String, Object> containers = new HashMap<>();
    containers.put("browser", browserContainer);

    Map<String, Object> selenosisOptions = new HashMap<>();
    selenosisOptions.put("labels", labels);
    selenosisOptions.put("containers", containers);

    // Vendor-namespaced capability
    caps.setCapability("selenosis:options", selenosisOptions);

    RemoteWebDriver driver = new RemoteWebDriver(
        new URL("http://{selenosis_host:port}/wd/hub"),
        caps
    );

    try {
      driver.get("https://example.com");
    } finally {
      driver.quit();
    }
  }
}

import { chromium } from 'playwright';

const browser = await chromium.connect({
  wsEndpoint: 'ws://http://{selenosis_host:port}/playwright/playwright-chrome/1.58.0?labels.team=qa&labels.project=selenosis&containers.seleniferous.env.SESSION_IDLE_TIMEOUT=5m&containers.seleniferous.env.SESSION_CREATE_TIMEOUT=5m'
});

const context = await browser.newContext();
const page = await context.newPage();

await page.goto('https://example.com');
await page.screenshot({ path: 'example.png' });

await browser.close();

• selenosis:options is validated and parsed by the controller.
• Invalid JSON results in the Browser being marked as Failed.
• Options are applied when the Pod is created.

When proxying to a browser pod fails, Selenosis maps the failure to a status code that lets clients react correctly. A pod that is unreachable (for example, torn down after the idle timeout) is detected as a connection/dial failure to the sidecar:

For session-scoped endpoints an unreachable pod returns 404 so the client can tell the session no longer exists and start a new one. WebSocket endpoints (BiDi/CDP/Playwright) are not covered by this mapping — a failed upstream dial closes the connection.

Selenosis supports the Model Context Protocol (MCP) for Playwright and Selenium MCP servers running inside browser pods.

The MCP server runs inside the browser container (not in seleniferous). Selenosis creates the browser pod and proxies MCP traffic through the seleniferous sidecar to the MCP server.

Only the Streamable HTTP transport is supported, exposed on a single endpoint /mcp (POST, GET, DELETE). Sessions are identified by the Mcp-Session-Id header — Selenosis is stateless and derives the target pod from it.

A session is created by the standard MCP initialize call: a POST /mcp without an Mcp-Session-Id header. Selenosis requires browser and version query parameters to know which browser to start:

POST /mcp?browser=<name>&version=<version>

Selenosis creates a Browser resource, waits for the pod to become ready, and forwards the initialize request to the MCP server. The pod-derived session id is returned in the Mcp-Session-Id response header; clients send it back on every subsequent request.

Additional query parameters are parsed as selenosis:options (same as the Playwright endpoint).

curl -isS -X POST 'http://{selenosis_host:port}/mcp?browser=playwright-mcp&version=0.0.75' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"example","version":"1.0.0"}}}'
# the response includes header: Mcp-Session-Id: <pod-uuid>

Once initialized, send the returned Mcp-Session-Id header on every request. Selenosis routes by that header to the correct pod and proxies to the sidecar /mcp.

# Client request
curl -sS -X POST http://{selenosis_host:port}/mcp \
  -H 'Content-Type: application/json' \
  -H 'Mcp-Session-Id: <pod-uuid>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Server-initiated message stream
curl -sS http://{selenosis_host:port}/mcp \
  -H 'Mcp-Session-Id: <pod-uuid>'

curl -sS -X DELETE http://{selenosis_host:port}/mcp \
  -H 'Mcp-Session-Id: <pod-uuid>'

This ends the MCP session and tears down the browser pod.

If a browser pod is torn down (for example after the idle timeout), a later POST/GET/DELETE /mcp carrying the now-stale Mcp-Session-Id returns 404. Per the MCP spec, a 404 on a request that includes a session id signals that the session no longer exists, so a spec-compliant client drops the id and performs a fresh initialize — which transparently starts a new browser pod. A missing Mcp-Session-Id header on a non-initialize request returns 400, as does a malformed (non-UUID) id.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

// Point the transport at /mcp with the desired browser/version.
// The SDK performs `initialize`, captures the Mcp-Session-Id response header,
// and replays it on every subsequent request automatically.
const url = new URL('http://{selenosis_host:port}/mcp?browser=playwright-mcp&version=0.0.75');
const transport = new StreamableHTTPClientTransport(url);
const client = new Client({ name: 'example', version: '1.0.0' });
await client.connect(transport);

const tools = await client.listTools();
await client.callTool({
  name: 'browser_navigate',
  arguments: { url: 'https://example.com' }
});

await client.close(); // sends DELETE /mcp and tears down the pod

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const url = new URL('http://{selenosis_host:port}/mcp?browser=playwright-mcp&version=0.0.75');
const transport = new StreamableHTTPClientTransport(url);
const client = new Client({ name: 'example', version: '1.0.0' });
await client.connect(transport);

const tools = await client.listTools();
await client.callTool({
  name: 'navigate',
  arguments: { url: 'https://example.com' }
});

await client.close();

Selenosis supports optional HTTP Basic Authentication for protecting its public API endpoints. Authentication is enabled by providing a users file via a Kubernetes Secret and referencing it through environment variables. When Basic Auth is enabled, all incoming HTTP requests must include valid credentials.

Basic Auth is disabled by default.

It becomes active when the following environment variable is set:

BASIC_AUTH_FILE

This variable must point to a file containing a JSON list of users.

[
  { "user": "alice", "pass": "secret1" },
  { "user": "bob",   "pass": "secret2" }
]

• user — username
• pass — password (plain text in this example)

apiVersion: v1
kind: Secret
metadata:
  name: basic-auth
  namespace: selenosis
type: Opaque
stringData:
  users.json: |
    [
      { "user": "alice", "pass": "secret1" },
      { "user": "bob",   "pass": "secret2" }
    ]

env:
  - name: BASIC_AUTH_FILE
    value: /etc/auth/users.json

volumeMounts:
  - name: basic-auth
    mountPath: /etc/auth
    readOnly: true

volumes:
  - name: basic-auth
    secret:
      secretName: basic-auth

Clients must send credentials using http://{username}:{password}@{selenosis_host:port}/*

The project is built and packaged entirely via Docker. Local Go installation is not required for producing the final artifact.

The build process is controlled via the following Makefile variables:

REGISTRY and VERSION are expected to be provided externally, which allows the same Makefile to be used locally and in CI.

Helm chart selenosis-deploy