Skip to main content
This page documents the gRPC service definitions and message schemas used for communication between Palyra components. These definitions form the backbone of the system’s inter-process communication (IPC), defining how the daemon interacts with the browser engine, plugins, nodes, and external clients. The protocol is versioned via a major version constant and uses palyra.v1 namespaces for all services schemas/generated/rust/protocol_stubs.rs#5-7.

​
Service Architecture Overview

The Palyra protocol is divided into several specialized services, each responsible for a specific domain of the agentic runtime. The daemon acts as the central hub, implementing the GatewayService, ApprovalsService, and VaultService, while delegating browser-specific tasks to palyra-browserd via the BrowserService.

​
Code Entity Mapping

The following diagram bridges the natural language service names to their specific Protobuf definitions and generated implementation traits. Diagram: Protocol Service to Code Entity Mapping Sources: schemas/proto/palyra/v1/gateway.proto#7-29, schemas/proto/palyra/v1/browser.proto#7-42, schemas/generated/rust/protocol_stubs.rs#52-58.

​
1. GatewayService

The GatewayService is the primary entry point for agent orchestration and session management. It handles the lifecycle of “Runs” and manages the binding of Agents to specific execution contexts.
RPC MethodDescription
RunStreamA bidirectional stream for executing agent instructions and receiving real-time events (logs, tool calls, status).
AppendEventManually appends events to a session’s journal for state synchronization.
RouteMessageRoutes incoming messages from channel connectors to the appropriate agent session.
BindAgentForContextAssociates a specific Agent ID with a principal/channel context.
Sources: schemas/proto/palyra/v1/gateway.proto#7-29

​
2. ApprovalsService

Manages human-in-the-loop (HITL) workflows. It allows external interfaces (like the Web Console) to list, inspect, and export security-sensitive actions requiring explicit authorization. Sources: schemas/proto/palyra/v1/gateway.proto#31-35

​
3. BrowserService

Implemented by palyra-browserd, this service provides a high-level API for headless browser automation. It abstracts complex Chromium operations into discrete agent-friendly actions.

​
Browser Interaction Flow

This diagram illustrates how a NavigateRequest is handled across the protocol boundary. Diagram: Browser Action Data Flow Sources: schemas/proto/palyra/v1/browser.proto#19, crates/palyra-daemon/src/app/runtime.rs#86-98, crates/palyra-daemon/src/lib.rs#141-144.

​
Key RPCs:

​
4. VaultService

Provides secure storage for sensitive credentials. It uses a scoped key-value model where secrets are isolated by VaultScope (e.g., Global, Workspace, or Agent-specific). Sources: schemas/proto/palyra/v1/gateway.proto#37-42

​
5. CanvasService

Manages the Canvas subsystem, which allows agents to push dynamic, interactive UI surfaces to the user. Sources: schemas/proto/palyra/v1/gateway.proto#44-51

​
Cross-Language Stub Generation

To ensure type safety across the monorepo, Protobuf definitions are compiled into native stubs for multiple languages. This process is governed by generate-stubs.sh schemas/generated/rust/protocol_stubs.rs#1.

​
Generated Artifacts

Each language-specific stub includes:
  1. Data Classes/Structs: Representation of all message types (e.g., AuthProfile, BrowserSessionDetail).
  2. Service Interfaces: Traits or protocols defining the RPC methods (e.g., AuthServiceClient).
ServiceProtocol Stub ModuleImplementation Location
AuthServicepalyra_auth_v1crates/palyra-daemon/src/application/auth.rs
BrowserServicepalyra_browser_v1crates/palyra-browserd/src/service.rs
GatewayServicepalyra_gateway_v1crates/palyra-daemon/src/gateway/mod.rs
Sources: schemas/generated/rust/protocol_stubs.rs#7-61, crates/palyra-daemon/src/lib.rs#168-171