Skip to main content
The palyra-browserd service provides a high-level gRPC interface for controlling headless Chromium instances. It abstracts complex browser automation tasks—such as session persistence, multi-tab management, and secure network egress—into a simplified protocol used by the Palyra daemon and CLI.

​
gRPC Service Architecture

The core of the browser service is BrowserServiceImpl, which implements the palyra.v1.browser gRPC contract. It manages the lifecycle of browser sessions, profiles, and tabs while enforcing security boundaries.

​
Key Components & Data Flow

ComponentRole
BrowserServiceImplEntry point for gRPC requests; handles authorization and request routing. crates/palyra-browserd/src/transport/grpc/service.rs#9-11
BrowserRuntimeStateShared state holding active sessions, profile registries, and configuration. crates/palyra-browserd/src/support/tests.rs#80-101
HeadlessBrowserIntegration with the headless_chrome crate to drive the Chromium process. crates/palyra-browserd/src/lib.rs#36-40
ChromiumSessionProxyA per-session SOCKS5 proxy that intercepts and validates all browser network traffic. crates/palyra-browserd/src/engine/chromium.rs#71-75
Browser Service Entity Map Sources: crates/palyra-browserd/src/transport/grpc/service.rs#9-14, crates/palyra-browserd/src/engine/chromium.rs#71-78, crates/palyra-browserd/src/lib.rs#36-40

​
Session Lifecycle & Persistence

Sessions in palyra-browserd are ephemeral by default but can be associated with a BrowserProfileRecord for persistence.

​
Session Creation

When create_session is called, the service:
  1. Authorizes the request using the x-palyra-principal header and an optional Bearer token. crates/palyra-browserd/src/transport/grpc/service.rs#33-35
  2. Resolves Profiles: If a profile_id is provided, it loads the encrypted profile state. crates/palyra-browserd/src/transport/grpc/service.rs#42-48
  3. Initializes Egress: Spawns a ChromiumSessionProxy to gate all network requests for that session. crates/palyra-browserd/src/engine/chromium.rs#78-96
  4. Enforces Budgets: Applies SessionBudget limits such as max_navigation_timeout_ms and max_screenshot_bytes. crates/palyra-browserd/src/transport/grpc/service.rs#107-125

​
Persistence Engine

State persistence (cookies, localStorage) is handled by the PersistedStateStore. Blobs are encrypted using CHACHA20_POLY1305 before being written to disk. crates/palyra-browserd/src/lib.rs#47-49, crates/palyra-browserd/src/support/tests.rs#2-7 Sources: crates/palyra-browserd/src/transport/grpc/service.rs#29-93, crates/palyra-browserd/src/persistence/mod.rs#1-10

​
Download Management & Sandbox

palyra-browserd implements a secure download pipeline to prevent headless instances from writing arbitrary files to the host filesystem.
  1. Sandbox Allocation: Each session with downloads enabled gets a DownloadSandboxSession located in a temporary directory. crates/palyra-browserd/src/domain/downloads.rs#20-32
  2. Validation: Files are checked against DOWNLOAD_ALLOWED_EXTENSIONS (e.g., .pdf, .csv, .txt) and DOWNLOAD_ALLOWED_MIME_TYPES. crates/palyra-browserd/src/lib.rs#153-162
  3. Quarantine: If a file fails validation (e.g., unknown MIME type), it is moved to a quarantine directory rather than the allowlist directory. crates/palyra-browserd/src/domain/downloads.rs#147-152
  4. Resource Limits: Total download size is capped by DOWNLOAD_MAX_TOTAL_BYTES_PER_SESSION (default 32MB). crates/palyra-browserd/src/lib.rs#147
Sources: crates/palyra-browserd/src/domain/downloads.rs#20-44, crates/palyra-browserd/src/domain/downloads.rs#105-118, crates/palyra-browserd/src/lib.rs#147-162

​
Security: Target URL Validation

To prevent Server-Side Request Forgery (SSRF) and unauthorized access to internal infrastructure, palyra-browserd employs a multi-stage validation process for every URL navigation.

​
Validation Pipeline

The function validate_target_url_blocking performs the following checks:
  1. Protocol Guard: Only http, https, and about:blank are permitted. crates/palyra-browserd/src/security/target_validation.rs#188-191
  2. DNS Resolution: Resolves the host to IP addresses. crates/palyra-browserd/src/security/target_validation.rs#201
  3. Netguard Check: If allow_private_targets is false, the service blocks any IP in the private or local ranges (e.g., 127.0.0.1, 192.168.x.x, 169.254.x.x). crates/palyra-browserd/src/security/target_validation.rs#14-16
  4. SOCKS5 Interception: The ChromiumSessionProxy ensures that even if the browser is subverted, the underlying TCP stream cannot reach blocked IPs. crates/palyra-browserd/src/engine/chromium.rs#198-201
Egress Security Flow Sources: crates/palyra-browserd/src/security/target_validation.rs#184-206, crates/palyra-browserd/src/engine/chromium.rs#198-210

​
CLI Integration & Relay Tokens

The Palyra CLI provides a comprehensive command suite for interacting with browserd. It manages the background lifecycle of the daemon via palyra browser start and palyra browser stop. crates/palyra-cli/src/commands/browser.rs#170-173

​
Relay Security

When the browser extension (Relay Companion) interacts with the daemon, it uses “Relay Tokens” to secure the loopback communication. Sources: crates/palyra-cli/src/commands/browser.rs#160-200, crates/palyra-browserd/src/support/tests.rs#128-140