BrowserPane

BrowserPane is a self-hostable remote browser and workflow execution platform for humans and agents.

Many browser automation products expose managed browsers, CDP endpoints, or live debug links. BrowserPane treats the live browser session itself as the product surface: a real Chromium session that browser users, supervisors, and automation can all attach to with shared-session policy, owner/viewer controls, and persistent session resources.

The key technical difference is that BrowserPane includes its own host-layer remote browser stack. The Rust bpane-host process runs next to Chromium inside the Linux runtime, captures and classifies the desktop surface, streams tiles, ROI video, audio, cursor, clipboard, files, input, microphone, camera, and resize events through BrowserPane's protocol, and lets the web client render the live session in a regular browser page.

BrowserPane is intended to be integrated into larger automation and workflow systems. Its workflow layer is primarily about browser-run execution, supervision, artifacts, and human intervention around a live browser session, not about replacing a general scheduler or DAG orchestrator.

This means BrowserPane is not only a wrapper around Playwright, CDP, screenshots, or a hosted debug iframe. It owns the live browser transport path from the Linux host to the browser client.

Project walkthrough: watch on YouTube.

Unified Admin Console

BrowserPane consolidates live session operation, resource configuration, workflow execution, recordings, and project/egress governance in the route-backed /admin-new/ application. Local Compose opens this standard admin experience from the web root. The legacy /admin/ console remains directly available as an explicit compatibility fallback until a separate removal decision is implemented.

The current prototype includes the dashboard; project, browser-context, egress-profile, and file-workspace catalogs; session create/detail and popup preview flows; recording catalog/download; workflow source, version, and run launching; workflow-run catalog/detail; identity/access review and registry management; approved-extension, credential-binding, and workflow-event subscription catalogs; and refresh-safe session live, files, recordings, network, automation, policy, and observability routes. Contract-derived API, coverage, and docs companions are implemented. Session-template and operation counter catalogs remain open. Project governance is carried into session and workflow creation and inspection with quota pressure, policy reasons, related-resource links, and authoritative admission or queue evidence kept distinct from client-side guidance. See the admin-new implementation status for the maintained route-level matrix.

These screenshots show the current /admin-new/ prototype with local demo data. The frozen owner-scoped v1 control-plane contract lives in openapi/bpane-control-v1.yaml.

The unified console also provides three contract-derived integration surfaces:

• /admin-new/api presents task-oriented, copyable commands for common project, session, workflow-run, and file-workspace flows.
• /admin-new/coverage inventories all frozen operations by family, authentication domain, and UI/worker ownership.
• /admin-new/docs explains contract scope and keeps non-v1 compatibility surfaces separate from the frozen owner-scoped API.

These routes load the committed operation, classification, example, and compatibility manifests published beside the OpenAPI document. They do not store a bearer token or act as a generic in-browser API executor.

Why BrowserPane

BrowserPane may fit when you need more than "a browser for an agent."

• BrowserPane owns the remote browser protocol. bpane-host, bpane-gateway, bpane-protocol, and bpane-client form a browser-native live session stack rather than delegating the user experience to a generic remote desktop product.
• Shared sessions are a first-class feature, not an afterthought. Multiple browser clients can join the same session with collaborative or restricted viewer behavior.
• Automation attaches to governed sessions instead of bypassing session policy. MCP and other automation flows operate through explicit ownership and session-control APIs.
• The remoting stack is browser-native. BrowserPane uses WebTransport plus a tile-first render path with optional ROI H.264 instead of relying only on full-frame streaming or vendor-hosted live debug UIs.
• The session behaves like a real remote workspace. Clipboard, file transfer, audio out, microphone in, camera ingress, resize, and input policy are part of the system design.
• The platform is self-hostable. Teams can run BrowserPane in their own environment instead of treating browser control as a SaaS-only dependency.

Where It Fits

BrowserPane is a strong fit for:

• human-in-the-loop browser automation
• collaborative investigation, support, or review sessions
• regulated or private deployments that need self-hosted browser access
• workflow systems that need durable session identity, artifacts, logs, and audit history
• platforms that need a governed browser execution target inside a larger orchestration stack

Current Status

BrowserPane is still experimental.

Use the capability maturity matrix for evidence-backed status and the product phases and release gates for Foundation, Phase 0, Phase 1, Production, and Phase N claim boundaries. A working local flow is Prototype evidence; it is not by itself a Production-readiness claim.

Current support and scope:

• Host runtime: Linux only. Ubuntu 24.04 container is the primary target.
• Browser runtime: Chromium desktop only. Firefox and Safari are not production targets.
• Shared sessions: collaborative by default, intended for small curated groups rather than broadcast-scale delivery.
• Owner/viewer mode: optional exclusive-owner mode is supported in the gateway; restricted viewers are read-only.
• Camera: disabled by default in the compose stack and requires browser H.264 encode support plus a mapped v4l2loopback device.
• Control plane: owner-scoped v1 APIs now cover identity/access-review summaries, service principals, identity-to-project mappings, projects, sessions, session templates, egress profiles, automation tasks, session recordings, workflow definitions/runs, file workspaces, credential bindings, and approved extensions.
• Workflow execution: Git-backed workflow versions run through a gateway-managed workflow-worker; the current executor model is Playwright.
• Admin console: /admin-new/ is the standard operator application and the local web-root target. Its first-pass dashboard, primary resource catalogs, session creation/detail and popup preview, recording catalog/download, workflow launcher, workflow-run catalog/detail, identity/access review, and session live/files/recordings/network/automation/policy/observability routes are implemented. Contract-derived API, coverage, and docs companions are also implemented, together with approved-extension, credential-binding, and signed workflow-event subscription catalogs. Session-template and operation-counter catalogs remain open. /admin/ remains the directly addressable compatibility fallback until a separate removal decision is implemented.
• Workflow boundary: BrowserPane currently focuses on executing and supervising browser workflows. Broader scheduling, DAG orchestration, and cross-system coordination are expected to sit above BrowserPane rather than inside it.
• External BPM integration: the stable project-scoped Workflow Endpoint is planned under issue #172; the existing owner-scoped workflow-run API is not that production contract.
• Teach Mode: prose/demonstration-to-workflow authoring and controlled repair are planned under issue #171 and are not current capabilities.
• Remote protocol: the integrated BrowserPane protocol is implemented, while its public specification, version negotiation, conformance, fuzzing, and compatibility policy remain planned under issue #175.
• Platform telemetry: the gateway exposes aggregate OpenMetrics request and runtime-capacity signals at /metrics, together with label-free workflow, event-delivery, recording, playback, and retention counters. An opt-in OpenTelemetry checkpoint also propagates W3C Trace Context across gateway-to-runtime-broker browser lifecycle operations and exports bounded spans through OTLP gRPC. A checked-in Prometheus starter pack adds validated recording rules, conservative alerts, operator runbooks, and a provisioned aggregate Grafana operations dashboard for the shipped metrics. These are initial operating proposals, not contractual SLOs. Broader worker/store tracing, queue/state and dependency metrics, calibrated SLOs/error budgets, alert routing, synthetics, and capacity envelopes remain planned under issue #178; configuration and the supported evidence boundary are documented in Platform Telemetry.
• Security baseline: the current trust boundaries, implemented controls, deployment obligations, and residual risks are linked in the threat model and production security baseline. BrowserPane now includes an independent, broker-only single-node deployment baseline for a controlled Linux Docker host. It is bounded packaging evidence, not an HA, managed-cloud, compliance, or universal production-readiness claim; broader deployment work remains issue #66.

How The System Is Shaped

At a high level, BrowserPane has five responsibilities:

1. Run a real browser session in a Linux host environment.
2. Capture and classify that surface efficiently.
3. Transport state, input, and media between host and browser.
4. Render the remote session in a regular web page.
5. Coordinate durable control-plane resources for identity, projects, sessions, workflows, recordings, files, credentials, extensions, and automation ownership.

The default local runtime looks like this:

browser client
  <-> bpane-gateway
  <-> bpane-host
  <-> Chromium + Xorg/Openbox inside a Linux runtime

bpane-host captures the browser desktop surface and emits BrowserPane protocol frames.
bpane-gateway applies session policy and relays WebTransport traffic.
bpane-client renders the live session and sends input/media/file events back.

bpane-gateway also talks to:
  - postgres
  - docker-proxy (private Docker API boundary for local runtime launch)
  - mcp-bridge
  - workflow-worker
  - recording-worker

Projects And Responsibilities

Rendering Model

BrowserPane is not a simple full-frame video streamer.

• UI and text travel primarily over the reliable tile path.
• Media-heavy regions can move to ROI H.264 on the video path.
• Desktop audio travels separately from visual updates.
• Input, clipboard, file transfer, microphone, and camera each have dedicated protocol flows.

That split is what lets the system keep static UI sharp while still handling moving video efficiently.

Protocol Model

The BrowserPane wire contract is a compact binary protocol implemented by the Rust bpane-protocol crate and the corresponding TypeScript client codec.

• Reliable typed channels are used for control, input, cursor, clipboard, file transfer, and tiles.
• Raw media channels are used for video, desktop audio, microphone, and camera payloads.
• The interoperating Rust and TypeScript implementations are the current code-level contract. A language-neutral public specification, explicit version negotiation, and conformance suite remain planned in issue #175.

Local Development

Recommended: Docker Compose

The local stack defaults to docker_pool mode. Creating a session persists its control-plane resource; opening its preview starts or reconnects the isolated browser runtime when needed.

Generate a dev certificate once:

./deploy/gen-dev-cert.sh dev/certs

Start the stack:

BPANE_GATEWAY_MAX_ACTIVE_RUNTIMES=2 \
docker compose -f deploy/compose.yml up --build

Then open http://localhost:8080/ in Chromium. The web root redirects to the unified console at /admin-new/; /admin/ remains the explicit compatibility fallback.

The unified session preview popup includes a local Metrics drawer that can sample browser transition diagnostics from the BrowserPane client runtime without creating a backend artifact. It reports FPS, transfer rates, tile mix, cache health, scroll fallback health, video datagrams, and render backend, and can copy the current sample as JSON for debugging.

The unified admin redirects unauthenticated users to the local Keycloak login. Use these development credentials:

• username: demo
• password: demo-demo

Then:

1. Open Sessions, choose New session, configure the resource, and click Create session. Creation does not start a browser runtime.
2. Open the session Live area to inspect runtime/connection state, then choose Connect or Start and connect. The browser opens in a separate popup window.
3. Open the session Files area to inspect retained uploads/downloads and manage policy-approved workspace bindings.
4. Open the same session detail and preview from another signed-in browser window to test collaborative access.
5. In MCP Delegation, choose Authorize and, for compatibility clients, Set default when the local mcp-bridge should drive that session.
6. For external MCP clients, prefer the session-scoped URL shown in the MCP panel, for example http://localhost:8931/sessions/{session_id}/mcp.

If you explicitly want the older single-runtime compatibility stack, opt into it:

BPANE_GATEWAY_RUNTIME_BACKEND=static_single \
docker compose -f deploy/compose.yml up --build

The compose stack starts:

• host: Linux host runtime with Xorg dummy, Openbox, Chromium, and bpane-host
• gateway: WebTransport relay on :4433 and HTTP APIs on :8932
• docker-proxy: internal-only, allowlisted Docker API proxy used by the gateway in direct mode and by the runtime broker in the opt-in broker overlay
• runtime-broker: internal-only authenticated typed-operation boundary; its base configuration remains fail-closed, while the opt-in overlay enables policy-owned Docker adapters for browser, workflow, recording, and isolated storage helpers
• postgres: session-control database on :5433
• vault: local HashiCorp Vault dev server on :8200 for workflow credential bindings
• keycloak: local OIDC provider on :8091
• web: local frontend on :8080
• mcp-bridge: MCP bridge on :8931 (/sessions/{id}/mcp for recommended session-scoped Streamable HTTP, /sessions/{id}/sse for session-scoped legacy SSE, /mcp and /sse for compatibility)
• recording-worker-image: one-shot build helper for the on-demand recording worker image used by recording.mode=always; the selected direct or broker worker-control path launches short-lived recorder containers

The gateway exposes unauthenticated, resource-free operational probes and an aggregate OpenMetrics scrape endpoint on its HTTP port:

curl -fsS http://localhost:8932/healthz
curl -fsS http://localhost:8932/readyz
curl -fsS http://localhost:8932/metrics

/healthz reports process liveness. /readyz admits traffic only while the gateway is running and its configured session store, runtime manager, credential provider, and recording/workspace artifact stores are reachable. Compose uses /readyz for the gateway health check. On SIGINT or SIGTERM the gateway first withdraws readiness, rejects new API and WebTransport work, keeps the probes visible for a short grace period, and then drains owned in-flight work up to a bounded timeout. The local defaults can be overridden with BPANE_GATEWAY_READINESS_CHECK_TIMEOUT_SECS, BPANE_GATEWAY_SHUTDOWN_READINESS_GRACE_SECS, and BPANE_GATEWAY_SHUTDOWN_DRAIN_TIMEOUT_SECS.

/metrics reports bounded HTTP RED signals, aggregate runtime active/starting/ limit gauges, and label-free workflow, event-delivery, recording, playback, and retention counters. The subsystem counters are process-local and share their source with the authenticated operations snapshots; they are operational signals, not durable audit or billing records. Metrics never use resource ids or raw request paths as labels. Keep this unauthenticated collector endpoint on a trusted private network in production. See Platform Telemetry for the metric contract, Prometheus recording/alert rules, provisioned Grafana operations dashboard, operator runbook, and validation commands.

The repository-wide security contract validates the current admin-header, Docker-proxy, and runtime-broker invariants against the composed manifests:

node scripts/check-production-security-baseline.mjs

This static contract is part of the fast validation profile. It does not replace live broker isolation, affected API/admin/workflow/recording smokes, or target-specific production qualification.

Workflow-worker and recording-worker containers run as short-lived jobs; do not run them as long-lived services. In direct mode the gateway launches them; in broker_pool the gateway sends typed intent and the broker owns container materialization. The default compose startup builds the recording-worker-image helper. Before local workflow runs or workflow smokes, build the profile-gated workflow-worker image once:

docker compose -f deploy/compose.yml --profile workflow build workflow-worker

Rebuild that image after changing code/integrations/workflow-worker or its container definition.

Worker control-plane and OIDC calls default to a 30-second deadline. Gateway supervisors and workflow entrypoints retain at most 256 KiB from each stdout or stderr stream, preserving the newest diagnostic tail. Local compose exposes these bounds through BPANE_WORKFLOW_WORKER_REQUEST_TIMEOUT_MS, BPANE_RECORDING_WORKER_REQUEST_TIMEOUT_MS, BPANE_WORKFLOW_WORKER_OUTPUT_LIMIT_BYTES, and BPANE_RECORDING_WORKER_OUTPUT_LIMIT_BYTES.

The gateway mounts the repository at /workspace:ro for local git-backed workflow sources and passes --workflow-source-trusted-local-root /workspace. The source resolver rejects local paths outside that explicit development root and gives Git short-lived, repository-scoped safe.directory entries only for each validated local source. The recording worker uses the generated local SPKI fingerprint from dev/certs/cert-fingerprint.txt through the gateway's --recording-worker-cert-spki-file setting, so run ./deploy/gen-dev-cert.sh dev/certs before starting compose after certificate rotations. The recording worker forces the SDK render backend to Canvas2D for reliable headless Docker capture. Interactive admin and embedded browser clients keep the default auto backend, so GPU/WebGL rendering remains available for end-user sessions when the browser environment supports it.

The local MCP bridge uses the package-installed @playwright/mcp executable from its own dependencies. It should not download @playwright/mcp@latest on first connect; run npm ci in code/integrations/mcp-bridge or rebuild the image if that local executable is missing.

The gateway supports four runtime backends:

• static_single: one shared host worker
• docker_single: one start-on-demand runtime container with idle shutdown
• docker_pool: multiple start-on-demand runtime containers with explicit max_active_runtimes and max_starting_runtimes
• broker_pool: production-like Docker-host path that preserves the Docker pool state machine while routing browser, workflow-worker, recording-worker, session data, and browser-context storage operations through the authenticated runtime broker

deploy/compose.yml now defaults to docker_pool, but you can still switch backends explicitly when you need a compatibility check:

BPANE_GATEWAY_RUNTIME_BACKEND=docker_pool \
BPANE_GATEWAY_MAX_ACTIVE_RUNTIMES=2 \
docker compose -f deploy/compose.yml up --build

deploy/compose.yml mounts the host Docker socket only into an internal, digest-pinned docker-proxy. The gateway has no socket mount; its Docker CLI uses DOCKER_HOST=tcp://docker-proxy:2375. The proxy publishes no host port and allows only the container, volume, daemon-info, ping, and version API families needed by current local runtime operations. Validate the static manifest and live API denials with:

node scripts/validate-docker-runtime-boundary.mjs

This proxy is defense-in-depth for the local direct compatibility path, not a complete production authorization boundary. The required container and volume APIs can still expose unrelated daemon resources, and a generic proxy does not validate image, mount, network, capability, or privileged-mode fields inside create requests. Production deployments must put runtime launch behind a purpose-specific broker or an orchestrator adapter with typed policy.

The compose stack includes the runtime-broker foundation on two isolated internal networks: only the gateway can reach its operation API, and only the broker can reach Keycloak on its auth network. The broker accepts the versioned BrowserPane runtime-operation media type and audience-bound OAuth2 service credentials. Base Compose leaves its executor fail-closed and gives it no Docker network or socket access. Validate that foundation and its live authentication denials with:

node scripts/validate-runtime-broker-foundation.mjs
node scripts/smoke-runtime-broker-foundation.mjs

To exercise the production-like broker-owned Docker-host topology without changing the direct local default, start the dedicated overlay:

./scripts/start-runtime-broker-browser-overlay.sh

The wrapper builds the host, workflow-worker, and recording-worker images, resolves immutable image IDs, starts the broker with read-only browser and worker policy inputs plus the host image as its isolated storage-helper image, and selects broker_pool in the gateway. In this mode the gateway sends typed storage intents for session-data initialization, approved file destinations, and browser-context lifecycle; it retains workspace artifact reads and binding state in the control plane. The gateway has no Docker endpoint variable, socket mount, proxy dependency, or docker-control network membership in this topology. Only the broker and proxy share Docker control. Validate the overlay topology with:

node scripts/validate-runtime-broker-browser-overlay.mjs
./scripts/smoke-runtime-broker-isolation.sh
./scripts/smoke-runtime-broker-storage.sh
cd code/web/bpane-client
npm run smoke:runtime-broker-restart -- --headless

The storage smoke requires the running overlay and exercises authenticated context import/measure/clone/export/delete plus session-data initialization, typed materialization, a realistic multi-megabyte archive transfer, digest verification, and helper/staging/owned-volume cleanup.

Broker /readyz checks the selected adapter dependency without creating an audited runtime operation. Browser and worker lifecycle requests remain typed and audited. The broker overlay is the current production-like Docker-host authorization boundary; this does not make the complete BrowserPane deployment production-ready without the remaining observability, packaging, HA/DR, capacity, and release-governance gates documented under docs/.

Compose also forwards a shared host-worker env profile automatically. If your compose project name is not the default deploy, override these defaults too:

• BPANE_GATEWAY_DOCKER_RUNTIME_IMAGE
• BPANE_GATEWAY_DOCKER_RUNTIME_NETWORK
• BPANE_GATEWAY_DOCKER_RUNTIME_SOCKET_VOLUME
• BPANE_GATEWAY_DOCKER_RUNTIME_SESSION_DATA_VOLUME_PREFIX
• BPANE_RECORDING_WORKER_NETWORK
• BPANE_RECORDING_WORKER_OUTPUT_VOLUME
• BPANE_RECORDING_WORKER_IMAGE

The default local auth and session flow is OIDC-based:

• opening /admin-new/ automatically redirects unauthenticated users to the local Keycloak realm; there is no separate landing-page login action
• the session creation form can bind a project, session template, reusable browser context, egress profile, capabilities, recording policy, labels, network identity, viewport, and optional idle timeout before persistence
• creating a session does not start its runtime; Connect or Start and connect opens the separate preview and starts/reconnects that exact session resource
• when a session omits idle_timeout_sec, local compose uses the gateway's 300-second runtime idle-stop default
• reconnecting a stopped or released session reuses the same session resource; after a runtime stop it restores from the persisted Chromium profile rather than a suspended process image
• Docker-backed sessions keep Chromium profile, upload, and download data in session-specific storage, and runtime assignments are persisted in Postgres for gateway restart reconciliation
• the session detail view shows MCP authorization/default-session state and the immutable session-scoped endpoint for direct MCP clients

The admin consoles fetch /auth-config.json and use the shared @browserpane/admin-auth package for Authorization Code + PKCE. Its provider-neutral protocol core is oauth4webapi; BrowserPane only owns runtime configuration, the bounded login transaction, auth snapshots, redirects, and application recovery. Access, ID, and refresh tokens stay in memory. Only the short-lived PKCE verifier, state, nonce, redirect URI, and creation time enter per-tab sessionStorage; reloading performs a normal OIDC redirect and normally recovers through the existing provider SSO session. Before WebTransport connect, the console mints a short-lived session-scoped connect ticket from the session API and uses that ticket on the transport URL instead of the long-lived bearer token. The legacy development harness remains available at /test-embed.html for smoke tests that still exercise harness-specific hooks.

For Chromium, WebTransport still needs trusted TLS on localhost. The current runtime SPKI fingerprint is served at:

http://localhost:8080/cert-fingerprint
http://localhost:8080/cert-hash

./deploy/gen-dev-cert.sh dev/certs also refreshes dev/certs/cert-fingerprint.txt and dev/certs/cert-hash.txt from the same cert.pem for CLI and WebTransport certificate-hash use. The admin app and browser client request these local certificate metadata endpoints without browser cache reuse so certificate rotations can be picked up after reload.

If a manually launched local Chromium reports Opening handshake failed when joining a session, start it with the local QUIC origin and SPKI trust flags:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --origin-to-force-quic-on=localhost:4433 \
  --ignore-certificate-errors-spki-list="$(cat dev/certs/cert-fingerprint.txt)" \
  http://localhost:8080/admin-new/

Hardened Single-Node Baseline

deploy/single-node/compose.yml is the independent deployment profile for one dedicated Linux Docker host. It requires immutable image digests, protected secret files, external OIDC/Postgres/Vault, trusted HTTPS and WebTransport ingress, and operator-owned backup, monitoring, firewall, and host controls. It does not inherit the local demo services or source mounts.

Validate and start it with the same operator-owned environment file:

node scripts/check-single-node-deployment.mjs \
  --env-file /etc/browserpane/browserpane.env
docker compose --project-name browserpane \
  --env-file /etc/browserpane/browserpane.env \
  -f deploy/single-node/compose.yml up -d

See docs/SINGLE_NODE_DEPLOYMENT.md for the support boundary, configuration, ingress, diagnostics, backup/restore, upgrade/rollback, and qualification procedure.

Remote / Self-Hosted Testing

The checked-in compose stack is a local development and regression environment, not a production deployment guide. Remote testing needs HTTPS for the web UI, a browser-trusted WebTransport gateway certificate, aligned OIDC issuer and redirect settings, and private handling for dev-only services such as Postgres, Vault, Keycloak admin surfaces, gateway internals, and the MCP bridge.

See REMOTE_DEPLOYMENT.md for the current remote deployment assumptions and compose override notes.

Control Plane

bpane-gateway exposes the frozen v1 control-plane contract used by the admin applications, CLI, integrations, and workers.

Canonical contract:

• openapi/bpane-control-v1.yaml
• control API compatibility policy

Selected resource and diagnostics routes:

• POST /api/v1/sessions
• GET /api/v1/sessions
• GET /api/v1/sessions/{id}
• DELETE /api/v1/sessions/{id}
• GET /api/v1/identity/me
• GET /api/v1/identity/access-review
• POST /api/v1/service-principals
• GET /api/v1/service-principals
• GET /api/v1/service-principals/{id}
• PUT /api/v1/service-principals/{id}
• POST /api/v1/identity-mappings
• GET /api/v1/identity-mappings
• GET /api/v1/identity-mappings/{id}
• PUT /api/v1/identity-mappings/{id}
• POST /api/v1/browser-contexts
• GET /api/v1/browser-contexts
• GET /api/v1/browser-contexts/{id}
• POST /api/v1/browser-contexts/{id}/clone
• GET /api/v1/browser-contexts/{id}/export
• POST /api/v1/browser-contexts/import
• DELETE /api/v1/browser-contexts/{id}
• POST /api/v1/session-templates
• GET /api/v1/session-templates
• GET /api/v1/session-templates/{id}
• PUT /api/v1/session-templates/{id}
• POST /api/v1/projects
• GET /api/v1/projects
• GET /api/v1/projects/{id}
• PUT /api/v1/projects/{id}
• GET /api/v1/projects/{id}/usage
• POST /api/v1/egress-profiles
• GET /api/v1/egress-profiles
• GET /api/v1/egress-profiles/{id}
• PUT /api/v1/egress-profiles/{id}
• GET /api/v1/egress-profiles/{id}/diagnostics
• GET /api/v1/sessions/{id}/egress-diagnostics
• POST /api/v1/sessions/{id}/egress-diagnostics
• POST /api/v1/sessions/{id}/egress-usage

Owner-facing resources are bearer-protected, owner-scoped, and stored in Postgres. Explicit worker, recorder, bridge, and observer operations use the narrower bearer or session-automation credentials defined per operation. The OpenAPI file is canonical; the route lists below are selected local-development surfaces, not an exhaustive duplicate of the contract.

Resources And Policy

• Session templates provide reusable defaults for ownership, viewport, timeout, labels, network identity, and recording. Explicit session fields override template defaults.
• Projects group sessions and workflow runs under a customer, case, tenant, or environment boundary. They define resource allow-lists, transfer and recording policy, concurrency limits, usage budgets, and retained-storage quotas.
• File workspaces, credential bindings, and approved extensions provide governed inputs without embedding file paths, secrets, or extension payloads in session and workflow definitions. Operators can manage these catalogs with ./scripts/bpane file-workspace, ./scripts/bpane credential-binding, and ./scripts/bpane extension.
• Identity and access-review resources expose the current principal, registered service principals, and explicit identity-to-project mappings without returning raw bearer-token payloads. Disabled service principals cannot receive new automation delegation. These operations are available through the API, CLI, and /admin-new/identity. The unified route supports service-principal and identity-mapping create, edit, disable, and re-enable while keeping registry metadata distinct from enforced RBAC grants.
• Network identity and egress profiles define locale, timezone, browser identity, proxy routing, proxy authentication, and optional custom CA policy. Project-scoped profiles and credentials cannot cross project boundaries.
• Browser contexts preserve reusable Chromium profile state independently from session-scoped uploads, downloads, and file bindings. A reusable context permits one active runtime writer, can enforce retention and storage limits, and project-owned contexts cannot cross project boundaries.

Project policy is enforced before runtime launch. Work that exceeds an active capacity limit remains visible as queued and can be promoted when capacity opens. Disallowed resource bindings are rejected, retained-storage limits block new artifacts, and budget enforcement can block new session creation without stopping sessions that are already running.

BrowserPane keeps egress evidence sanitized: it stores effective configuration, runtime correlation, probe results, and reported byte totals. Requested URLs, headers, payloads, credentials, CA material, and decrypted traffic remain with the configured proxy or secure web gateway. TLS interception is opt-in and requires a proxy, custom CA, and approved sensitive-log sink.

The unified admin supports context catalog, create, detail, delete, clone, export, and import flows. Clone and export expose active-writer blockers before submission, while import preserves the selected archive and metadata after bounded validation or capacity errors so the operator can correct or retry. The API, CLI, compatibility console, and unified admin use the same lifecycle contract tracked in issue #160.

Session Runtime And Delegation

The gateway also exposes an owner-scoped realtime WebSocket for snapshot updates:

• POST /api/v1/admin/events/access-tokens
• GET /api/v1/admin/events

The browser mints a short-lived admin_event_access_token through the bearer-authenticated POST, opens the WebSocket without URL credentials, and sends the scoped token in its first message. Each reconnect mints a fresh token. Both admin consoles consume the same validated event contract and reconnect behavior. /admin-new/sessions/{id}/observability projects the owner-scoped snapshots into current session evidence and a bounded local timeline; it is operational context, not a durable audit log. The adjacent /automation and /policy routes expose session-bound MCP/workflow associations and effective restriction evidence.

The same frozen API surface also includes session-scoped runtime routes:

• POST /api/v1/sessions/{id}/access-tokens
• POST /api/v1/sessions/{id}/automation-access
• GET /api/v1/sessions/{id}/status
• `POST /ap