REST + Server-Sent-Events facade over the Selenosis Browser and BrowserConfig resources.
It gives clients a plain HTTP API and a real-time event stream on top of the Kubernetes
CRDs — without ever creating Pods itself.
- CRUD over CRDs. Create, get, list, and delete
BrowserandBrowserConfigresources through a namespaced HTTP API. - Real-time events. Streams
ADDED/MODIFIED/DELETEDlifecycle events for both resource types over Server-Sent Events, optionally filtered by name. - Read-only status. Surfaces
Browser.status(phase, pod IP, failure message) so clients can wait on readiness or react to failures. - A thin, stateless facade. It does not create Pods or act as a controller — all writes go straight to the Kubernetes API server; no state is kept outside Kubernetes.
It's the boundary between protocol semantics and Kubernetes resources: the selenosis hub calls it to create sessions and watch for readiness, and browser-ui consumes its event stream for the live session list.
| Component | Role |
|---|---|
| selenosis | Stateless Selenium / Playwright / MCP hub. Calls this service to create sessions and watch readiness. |
| seleniferous | Sidecar proxy inside each browser pod. |
| browser-controller | Operator that reconciles Browser / BrowserConfig CRDs into pods. Owns the CRD types this service uses. |
| browser-service (this repo) | REST + SSE facade over Browser and BrowserConfig resources. |
| browser-ui | Dashboard; consumes this service's event stream + VNC. |
| selenosis-deploy | Helm chart that deploys the whole stack. Start here. |
Depends on browser-controller for the
Browser/BrowserConfigCRD definitions and generated clientsets/informers/listers. CRDs must be installed and the controller running.
All endpoints are namespaced under /api/v1/namespaces/{namespace}.
| Method | Path | Description |
|---|---|---|
POST |
/browsers |
Create a Browser. |
GET |
/browsers/{name} |
Get a single Browser. |
DELETE |
/browsers/{name} |
Delete a Browser. |
GET |
/browsers |
List browsers in the namespace. |
GET |
/browsers/events |
Stream browser lifecycle events (SSE). Optional ?name= to filter. |
| Method | Path | Description |
|---|---|---|
POST |
/browserconfigs |
Create a BrowserConfig. |
GET |
/browserconfigs/{name} |
Get a single BrowserConfig. |
DELETE |
/browserconfigs/{name} |
Delete a BrowserConfig. |
GET |
/browserconfigs |
List browserconfigs in the namespace. |
GET |
/browserconfigs/events |
Stream BrowserConfig lifecycle events (SSE). Optional ?name= to filter. |
GET /healthz → 200 OK when the service is running.
Event types are ADDED, MODIFIED, and DELETED. Browser events carry the full
Browser object (incl. status.phase / status.podIP / failure message);
BrowserConfig events carry the full BrowserConfig.
How events are produced and fanned out
- The service uses shared informers to watch
BrowserandBrowserConfigresources. - Events are delivered to connected clients through an in-memory fan-out broadcaster.
- Subscribers may pass a predicate to receive only events for a specific resource name.
- Nothing is persisted outside Kubernetes; all writes forward directly to the API server.
The project builds and packages entirely via Docker — a local Go install is not required.
Makefile build variables
| Variable | Description |
|---|---|
BINARY_NAME |
Name of the produced binary (fixed: browser-service). |
REGISTRY |
Docker registry prefix (default: localhost:5000). |
IMAGE_NAME |
Full image name, derived as $(REGISTRY)/$(BINARY_NAME). |
VERSION |
Image version/tag (default: develop). |
EXTRA_TAGS |
Additional -t tags passed to docker-push (default: none). |
PLATFORM |
Target platform (default: linux/amd64). |
CONTAINER_TOOL |
Container build tool (default: docker). |
REGISTRY and VERSION are expected to be supplied externally so the same Makefile works
locally and in CI.
Deployed as part of the full stack via the selenosis-deploy Helm chart.