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

• Accepts standard WebDriver requests at /wd/hub (and root).
• 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.
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.

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.

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:

Variable Description

• BINARY_NAME Name of the produced binary (selenosis).
• REGISTRY Docker registry prefix (default: localhost:5000).
• IMAGE_NAME Full image name (/selenosis).
• VERSION Image version/tag (default: develop).
• PLATFORM Target platform (default: linux/amd64).
• CONTAINER_TOOL docker cmd

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

Minimal configuration

apiVersion: v1
kind: ServiceAccount
metadata:
  name: selenosis
  namespace: default

apiVersion: v1
kind: Service
metadata:
  name: selenosis
  labels:
    role: selenosis
spec:
  type: NodePort
  selector:
    role: selenosis
  ports:
  - name: http
    port: 4444   
    targetPort: 4444

apiVersion: apps/v1
kind: Deployment
metadata:
  name: selenosis
  labels:
    role: selenosis
spec:
  replicas: 1
  selector:
    matchLabels:
      role: selenosis
  template:
    metadata:
      labels:
        role: selenosis
    spec:
      serviceAccountName: selenosis
      containers:
      - name: service
        image: alcounit/selenosis:latest
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 4444
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "500m"
            memory: "256Mi"