Skip to main content
The palyra-browserd service is a high-level headless browser automation engine that provides a secure, gRPC-based interface for interacting with web content. It encapsulates the headless_chrome engine, managing the lifecycle of Chromium instances, browser sessions, and persistent profiles.

​
Purpose and Scope

The browser daemon serves as the “eyes and hands” for Palyra agents in the web environment. It is designed to be decoupled from the core daemon (palyrad), allowing it to run in isolated environments or even on different hosts. It handles complex tasks such as DOM interaction, screenshot capture, PDF generation, and secure download management while enforcing strict security boundaries on target URLs and resource consumption.

​
System Architecture

The following diagram illustrates the relationship between the palyra-browserd service, its internal engine components, and the external interfaces.

​
Browser Daemon Entity Map

Sources: crates/palyra-browserd/src/transport/grpc/service.rs#9-11, crates/palyra-browserd/src/lib.rs#80-82

​
Core Components

​
1. Browser gRPC Service & Chromium Engine

The primary interface to the daemon is the palyra.v1.browser.BrowserService. This service handles session creation, navigation, and page manipulation. It uses the headless_chrome crate to drive a Chromium process in headless mode.
  • Session Management: Each session is isolated with its own temporary data directory and resource limits (budgets).
  • Security Validation: All target URLs are validated against a netguard policy to prevent access to private or local IP ranges unless explicitly allowed.
  • Resource Budgets: Sessions are constrained by SessionBudget, which limits screenshot sizes, navigation timeouts, and total action counts.
For details, see Browser gRPC Service & Chromium Engine. Sources: crates/palyra-browserd/src/transport/grpc/service.rs#14-32, crates/palyra-browserd/src/lib.rs#83-104, crates/palyra-browserd/src/security/target_validation.rs#184-193

​
2. Browser Extension (Relay Companion)

The “Relay Companion” is a Manifest V3 browser extension that allows palyra-browserd to bridge the gap between headless automation and user-driven browser sessions. It facilitates DOM capture and screenshot relaying back to the daemon via a secure token-based handshake. For details, see Browser Extension (Relay Companion). Sources: crates/palyra-browserd/src/lib.rs#163-165

​
Functional Workflow

The following diagram maps the high-level request flow from the CLI or Daemon through the internal code entities of palyra-browserd.

​
Request Execution Flow

Sources: crates/palyra-browserd/src/transport/grpc/service.rs#29-93, crates/palyra-browserd/src/security/target_validation.rs#184-193, crates/palyra-browserd/src/support/tests.rs#103-125

​
Integration and Tooling

​
CLI Integration

The palyra CLI provides a comprehensive suite of commands under the browser namespace to manage the daemon and interact with sessions.
  • Lifecycle: palyra browser start and palyra browser stop manage the background daemon process.
  • Interaction: Commands like click, type, fill, and snapshot allow manual or scripted control of headless sessions.
  • Inspection: storage and network commands provide visibility into the browser’s internal state and traffic.
Sources: crates/palyra-cli/src/commands/browser.rs#166-234, crates/palyra-cli/src/args/browser.rs#4-63

​
Download Management

The daemon includes a secure download sandbox (DownloadSandboxSession). Files are fetched into a quarantined environment, validated by MIME type and extension, and limited by total session-wide byte quotas. Sources: crates/palyra-browserd/src/domain/downloads.rs#20-44, crates/palyra-browserd/src/lib.rs#147-162

​
Persistence Layer

State can be persisted across sessions using a PersistedStateStore. This includes encrypted storage for browser profiles, cookies, and local storage data, keyed by a principal’s identity. Sources: crates/palyra-browserd/src/transport/grpc/service.rs#75-91, crates/palyra-browserd/src/lib.rs#131-140

​
Child Pages