krex381/openbrowse

Purpose and Runtime

OpenBrowse is a self-hosted Node.js (>=24) service for authenticated web retrieval and browser automation. It uses direct HTTP first, escalating to sandboxed Chromium only when rendering or browser-only outputs are needed. Service startup is rooted at src/index.ts, with HTTP server composition in src/server.ts and src/server/lifecycle.ts.

API Edge and Interface Adapters

The server exposes native REST endpoints for fetch, render, extraction, artifacts, jobs, and owned sessions. Request parsing, authentication, validation, and route dispatch form the main trust boundary:

• src/server.ts

• src/server/input.ts

• src/server/routes/execution.ts

Optional Browserless-compatible, BrowserQL, MCP, and CDP reconnect surfaces adapt into the same execution core rather than owning separate browser pipelines:

• src/server/browserql-handler.ts

• src/server/mcp.ts

• src/server/routes/cdp-reconnect.ts

Policy and Security Boundary

Before fetch or navigation, the service applies API-key ownership, target validation, and network-target policy, including rejection of private, loopback, metadata, and DNS-resolved internal addresses. Security configuration and policy enforcement are concentrated in:

• src/security.ts

• src/config/policies.ts

• src/server/input/validation.ts

This is application-layer defense; deployment still requires DNS-aware egress enforcement. Raw CDP bridges and other high-risk capabilities are operator-controlled.

Execution Routing and Outputs

The execution core accepts normalized requests, chooses HTTP-only or browser execution, applies typed waits, and produces bounded HTML, Markdown, links, media, and extraction results. HTTP-first auto mode can detect client-rendered shells and escalate to Chromium:

• src/execution.ts

• src/execution/http.ts

• src/execution/workflow.ts

Content transformation and output-specific handling are separated from routing:

• src/execution/markdown.ts

• src/execution/media.ts

• src/execution/content.ts

Browser Workers, Sessions, and Admission Control

Browser work is managed as bounded pooled execution contexts with session lifecycle, queueing, process-memory admission, health/draining, and reconnect support. This separates externally visible session ownership from Chromium process management:

• src/execution/pool.ts

• src/execution/sessions.ts

• src/queue.ts

Chromium/CDP integration and recovery reside in:

• src/cdp.ts

• src/cdp-reconnect.ts

• src/process-memory.ts

Persistent Owned State

SQLite-backed storage persists API-key-scoped sessions, browser profiles, jobs, artifacts, proxies, handoffs, and operational records. Sensitive persisted state, including profiles and proxy credentials, is encrypted:

• src/storage/database.ts

• src/storage/crypto.ts

• src/storage/sessions.ts

Artifacts and queued/background work have dedicated persistence boundaries:

• src/storage/artifacts.ts

• src/storage/jobs.ts

• src/storage/operations.ts

The default SQLite one-writer model drives the single-replica Kubernetes deployment assumption.

Deployment and Client Surface

Production packaging runs Chromium in Docker with sandboxing, non-root execution, read-only filesystem, dropped capabilities, resource limits, and a seccomp profile:

• Dockerfile

• docker-compose.yml

• deploy/seccomp_profile.json

Kubernetes deployment is intentionally single replica and expects external egress controls:

• deploy/kubernetes/openbrowse.yaml

• deploy/kubernetes/README.md

A separate Vite/React landing and local viewer UI is served as a client surface, not the execution authority:

• frontend/landing/src/main.tsx

• frontend/landing/src/app.tsx

• frontend/landing/src/components/workbench.tsx