selenosis-deploy

August 30, 2026 · View on GitHub

Helm chart that deploys the full Selenosis stack on Kubernetes — CRDs, RBAC, all services, and ingress, in one command.

What it deploys

Component	Role
selenosis	Stateless Selenium / Playwright / MCP hub.
seleniferous	Sidecar proxy inside each browser pod — required in every `BrowserConfig`, and the container must be named `seleniferous`.
browser-controller	Operator that reconciles `Browser` / `BrowserConfig` CRDs into pods.
browser-service	REST + SSE facade over `Browser` and `BrowserConfig` resources.
browser-ui	Web dashboard with live sessions + VNC.

Browser and BrowserConfig CRDs ship as Helm templates (templates/crds/) and are applied on every helm install/upgrade. Each service is configured through Helm values that map to the environment variables documented in the individual project READMEs. For the architecture, see selenosis → How it works.

Quick start

# 1. Add the Helm repository
helm repo add selenosis https://alcounit.github.io/selenosis-deploy/
helm repo update

# 2. Install the full stack
helm install selenosis selenosis/selenosis-deploy -n selenosis --create-namespace

# 3. Apply a ready-made BrowserConfig (defines which browser images to run)
kubectl apply -n selenosis \
  -f https://raw.githubusercontent.com/alcounit/selenosis-deploy/main/examples/browserconfig-selenium-standalone-chrome-example.yaml

Install from the git repository instead

git clone https://github.com/alcounit/selenosis-deploy.git
cd selenosis-deploy
helm upgrade --install selenosis . -n selenosis --create-namespace --wait
helm status selenosis -n selenosis

CRD management

CRDs are part of the chart templates, controlled by the crds values block:

crds:
  enabled: true  # set to false to skip CRD installation (managed externally)
  keep: true     # adds helm.sh/resource-policy: keep — CRDs survive `helm uninstall`

# Install / upgrade without touching CRDs
helm upgrade --install selenosis selenosis/selenosis-deploy -n selenosis --set crds.enabled=false

Because CRDs are templated (not in the legacy crds/ directory), helm upgrade updates them when the schema changes. Migrating from an older crds/-based chart? See the release notes.

BrowserConfig examples

Ready-to-use BrowserConfig manifests live in examples/. Apply any after deploying the chart:

kubectl apply -n selenosis -f ./examples/<filename>.yaml

Writing your own? Every BrowserConfig must declare the seleniferous sidecar, and the container name is reserved — the hub waits for a container with that exact name before proxying, and the controller treats its termination as fatal for the session. Nothing rejects a config without it; the pods are simply created and never usable.
template:
  sidecars:
  - name: seleniferous
    image: alcounit/seleniferous:v2.1.1
    env:
    - name: POD_IP
      valueFrom:
        fieldRef:
          fieldPath: status.podIP

Per-image families: Selenoid, Selenium Standalone, Moon, Playwright, Playwright MCP

VNC password: browser-ui no longer ships a global VNC password. When you open a session in the UI it prompts for the password and can remember it per browser name or name + version. Use the value baked into each image family below (selenoid for Selenoid/Moon, or whatever you set via SE_VNC_PASSWORD for Selenium Standalone).

Selenoid (`twilio/selenoid`)

Community-maintained Selenoid image family. VNC is built in, enabled via ENABLE_VNC=true (password selenoid). Minimal two-container setup: browser + seleniferous sidecar.

chrome · firefox

Selenium Standalone (`selenium/standalone`)

Official Selenium standalone images with a built-in VNC server; the password is whatever you set via SE_VNC_PASSWORD in the browserconfig. Minimal two-container setup: browser + seleniferous sidecar.

chrome · firefox

Moon (`quay.io/browser`)

Moon images via quay.io/browser (VNC password selenoid). VNC needs a full X11 sidecar stack (xvfb, openbox, x11vnc from quay.io/aerokube) plus a usergroup ConfigMap (included) mapping the user:4096 identity.

chrome · firefox
Playwright CDP/BiDi variants: chrome · firefox

Playwright Standalone (`mcr.microsoft.com/playwright`)

Official Microsoft Playwright base image (Chromium, Firefox, WebKit). playwright-core is installed via an init container; run-server starts a multi-browser WebSocket server and the client picks the browser at connect time.

example

Playwright MCP (`mcr.microsoft.com/playwright/mcp`)

Microsoft Playwright MCP server image — browser automation over MCP Streamable HTTP, built-in MCP server, no init container.

example

Service types & ingress

Each service (selenosis, browserService, browserUI) supports ClusterIP, NodePort, or LoadBalancer, and selenosis/browserUI each have their own ingress block.

Service type values

browserUI:
  service:
    type: NodePort
    port: 8080
    nodePort: 30080

browserService:
  service:
    type: LoadBalancer
    port: 8080

selenosis:
  service:
    type: ClusterIP
    port: 4444

helm upgrade --install selenosis . -n selenosis -f values.local.yaml

Ingress with TLS and WebSocket (NGINX)

Browser UI requires WebSocket support for the VNC proxy — the annotations below are required for the NGINX Ingress Controller (other controllers differ).

selenosis:
  ingress:
    enabled: true
    className: nginx
    host: selenosis.example.com
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
    tls:
      secretName: selenosis-tls

browserUI:
  ingress:
    enabled: true
    className: nginx
    host: ui.example.com
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
      nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
      nginx.ingress.kubernetes.io/websocket-services: "browser-ui"
    tls:
      secretName: browser-ui-tls

helm upgrade --install selenosis . -n selenosis -f ingress-values.yaml

Maintainer release process

How to cut a new chart release

Bump version in Chart.yaml.
Commit and push.
Tag and push: git tag vX.Y.Z && git push origin vX.Y.Z.
GitHub Actions lints, packages, creates the GitHub Release, and publishes to the Helm repository (GitHub Pages).
Users upgrade: helm repo update && helm upgrade selenosis selenosis/selenosis-deploy --version X.Y.Z.

License

Apache-2.0