palyra-browserd daemon provides a secure, high-fidelity browser automation environment for Palyra agents. It abstracts complex browser interactions into a gRPC service, offering two distinct execution modes: a high-fidelity Chromium engine and a lightweight Simulated engine.
System Architecture
The browser subsystem consists of three layers: the CLI/Console (user-facing control), the Daemon Tool Runtime (agent-facing broker), and the Browser Daemon (the execution engine).Data Flow: Agent to Browser
- An agent proposes a
palyra.browser.*tool call. - The
palyra-daemonvalidates the request and brokers it viaexecute_browser_toolcrates/palyra-daemon/src/application/tool_runtime/browser.rs#11. - The daemon calls the
BrowserServicegRPC interface onpalyra-browserdcrates/palyra-browserd/src/transport/grpc/service.rs#1. palyra-browserdexecutes the action in the requested engine (Chromium or Simulated).- Results are redacted, budgeted, and returned through the chain.
Code Entity Map: Browser Service
The following diagram maps the gRPC service implementation to its underlying domain and engine entities. Sources: crates/palyra-browserd/src/transport/grpc/service.rs#53-57, crates/palyra-browserd/src/domain/downloads.rs#44-50, crates/palyra-browserd/src/engine/chromium.rs#1-6Engine Modes
palyra-browserd supports two engines to balance resource usage and fidelity.
| Feature | Chromium Engine | Simulated Engine |
|---|---|---|
| Backend | Headless Chrome via CDP | reqwest HTTP Client |
| JS Execution | Full (V8) | None (Static HTML) |
| Isolation | Process-per-session | Shared async runtime |
| Best For | SPAs, Complex UI, Interaction | Fast scraping, Static content |
| Capability Tag | javascript_execution: true | javascript_execution: false |
BrowserRuntimeCapabilities struct is attached to every tool outcome to ensure agents do not mistake static HTML for a functional JS application crates/palyra-daemon/src/application/tool_runtime/browser.rs#113-121.
Sources: crates/palyra-browserd/src/engine/chromium.rs#1-6, crates/palyra-daemon/src/application/tool_runtime/browser.rs#108-121
Security and SSRF Protection
Browser automation is a high-risk vector for Server-Side Request Forgery (SSRF).palyra-browserd implements several layers of defense.
DNS Pinning and Validation
To prevent DNS rebinding attacks,palyra-browserd resolves hostnames and validates them against a private/local IP policy before the browser or HTTP client initiates a connection crates/palyra-browserd/src/security/target_validation.rs#3-7.
- ResolvedHostAddresses: Classifies IPs as public or private crates/palyra-browserd/src/security/target_validation.rs#13-16.
- DnsValidationCache: A bounded NXDOMAIN-only cache to prevent resolution flooding crates/palyra-browserd/src/security/target_validation.rs#51-56.
- Pinning: Validated IP addresses are passed directly to the transport layer to bypass secondary OS resolution.
Navigation Guards
Thenavigate_with_guards function enforces policies on every navigation and redirect crates/palyra-browserd/src/support/tests.rs#9.
- Relay Protection: Requests originating from the browser extension (Relay) are strictly forbidden from accessing private targets crates/palyra-browserd/src/transport/grpc/service.rs#12-18.
- SSRF Guard: Blocks
127.0.0.1,169.254.169.254, and other internal ranges unless explicitly permitted forlocal_desktopmodes crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#27-34.
Session and Profile Management
BrowserProfileRecord
Profiles provide durable storage for cookies, localStorage, and session state.- Persistence: Profiles are stored as encrypted blobs using ChaCha20-Poly1305 crates/palyra-browserd/src/app/config.rs#59-63.
- Isolation: Each profile is scoped to a
principal(e.g., a specific user or agent) crates/palyra-browserd/src/persistence/profile_registry.rs#74.
BrowserSessionRecord
A session represents a live instance of an engine.- Lifecycle: Managed by
BrowserRuntimeState. Sessions expire afterDEFAULT_SESSION_IDLE_TTL_MS(10 minutes) crates/palyra-browserd/src/app/config.rs#10. - Resource Limits: Caps are enforced for tabs per session (default 32) and actions per window crates/palyra-browserd/src/app/config.rs#20-31.
Diagnostics and Artifacts
Script Injection
For Chromium sessions,palyra-browserd injects the CHROMIUM_PAGE_DIAGNOSTICS_SCRIPT into every page crates/palyra-browserd/src/engine/chromium.rs#183. This hook:
- Wraps
console.log,fetch, andXMLHttpRequest. - Buffers entries in a global
window.__palyraDiagnosticsobject crates/palyra-browserd/src/engine/chromium.rs#185. - Allows the daemon to “drain” logs even if the page crashes or navigates.
Download Quarantine
Captured downloads are managed by theDownloadSandboxSession crates/palyra-browserd/src/domain/downloads.rs#44.
- Allowlist: Files with safe extensions (e.g.,
.pdf,.png,.json) are stored in theallowlistdirectory crates/palyra-browserd/src/app/config.rs#88-95. - Quarantine: Executables or unknown MIME types are moved to
quarantine. Their metadata is visible, but content retrieval is blocked crates/palyra-browserd/src/domain/downloads.rs#132-137.
Redaction and Budgeting
All data returned to the agent is sanitized:- URL Redaction: Query parameters and sensitive tokens are stripped crates/palyra-browserd/src/support/mod.rs#90.
- Byte Budgeting: Snapshots are truncated to prevent LLM context overflow crates/palyra-browserd/src/support/mod.rs#19-23.
Daemon-Side Tool Runtime
Thepalyra-daemon implements the palyra.browser.* tool family by proxying to browserd.
Sources: crates/palyra-daemon/src/application/tool_runtime/browser.rs#11-65, crates/palyra-browserd/src/engine/chromium.rs#1-6
Key Functions
execute_browser_tool: Main entry point for tool dispatch crates/palyra-daemon/src/application/tool_runtime/browser.rs#11.redact_text_for_export: Ensures sensitive page content (like session tokens in the DOM) doesn’t leak into the agent’s memory crates/palyra-daemon/src/application/tool_runtime/browser.rs#31.BrowserRuntimeCapabilities::from_health: Annotates tool results with engine metadata crates/palyra-daemon/src/application/tool_runtime/browser.rs#126.