Skip to main content
This page documents the Palyra protocol architecture, focusing on the Protobuf schemas, the multi-language stub generation pipeline, and the validation mechanisms that ensure cross-component compatibility.

​
Protocol Architecture

Palyra uses Protocol Buffers (proto3) as the source of truth for all structured communication between the daemon (palyrad), CLI (palyra), browser daemon (palyra-browserd), and mobile/desktop clients. The protocol is versioned via a major version constant PROTOCOL_MAJOR_VERSION schemas/generated/rust/protocol_stubs.rs#5-5.

​
Core Service Definitions

The system is partitioned into functional gRPC services defined in schemas/proto/palyra/v1/.
ServiceFilePrimary Responsibility
GatewayServiceschemas/proto/palyra/v1/gateway.proto#7-29Run orchestration, session management, and agent routing.
ApprovalsServiceschemas/proto/palyra/v1/gateway.proto#31-35Management of tool and action approval records.
VaultServiceschemas/proto/palyra/v1/gateway.proto#37-42Secret storage and retrieval operations.
CanvasServiceschemas/proto/palyra/v1/gateway.proto#44-51State synchronization for A2UI (Agent-to-UI) components.
BrowserServiceschemas/proto/palyra/v1/browser.proto#7-42Headless Chromium automation and session control.
AuthServiceClientschemas/generated/rust/protocol_stubs.rs#52-58Identity and credential profile management.

​
Data Flow and Envelope Structure

Most streaming interactions occur via the RunStream, which uses a request/event pattern schemas/proto/palyra/v1/gateway.proto#9-10.

​
Entity Relationship Diagram: Protocol Space

This diagram maps the logical protocol entities to their generated code representations. Sources: schemas/proto/palyra/v1/gateway.proto#7-106, schemas/proto/palyra/v1/browser.proto#132-159, schemas/proto/palyra/v1/gateway.proto#255-267

​
Multi-Language Stubs

To ensure type safety across the Rust daemon, Swift (iOS/macOS), and Kotlin (Android) applications, a generation pipeline produces stubs from the .proto files.

​
Generated Stub Locations

The generation logic is contained in scripts/protocol/generate-stubs.ps1. It parses the proto files for package, message, service, and rpc declarations to build language-specific constructs scripts/protocol/generate-stubs.ps1#103-143.

​
Mapping Logic

The generator applies specific naming conventions for each target:
  1. Rust: Packages become modules (e.g., palyra.auth.v1 -> palyra_auth_v1) scripts/protocol/generate-stubs.ps1#154-157.
  2. Swift: Packages become Enums used as namespaces schemas/generated/swift/ProtocolStubs.swift#3-3, and RPCs use lowerCamelCase scripts/protocol/generate-stubs.ps1#201-201.
  3. Kotlin: Packages become Objects, and messages become data class entities schemas/generated/kotlin/ProtocolStubs.kt#4-5.

​
Protocol Validation Pipeline

The repository enforces protocol integrity through a multi-stage validation pipeline executed during CI.

​
1. Schema Validation

The validate-proto.ps1 script uses protoc to ensure that all .proto files are syntactically correct and that imports (like common.proto) resolve correctly scripts/protocol/validate-proto.ps1#57-66.

​
2. Stub Coherence Check

The check-generated-stubs.ps1 script regenerates the stubs and performs a git diff. If the generated code in schemas/generated/ does not match the source schemas, the build fails scripts/protocol/check-generated-stubs.ps1#9-21.

​
3. Compilation Validation

Each language’s stubs are compiled to ensure they are valid source code:

​
Pipeline Sequence Diagram

Sources: scripts/protocol/validate-proto.ps1#57-66, scripts/protocol/generate-stubs.ps1#22-44, scripts/protocol/validate-rust-stubs.ps1#26-29

​
Key Message Definitions

​
Approval and Security

The protocol defines strict enums for decisions and subjects to maintain a consistent security posture across UIs.

​
Browser Automation

The BrowserService utilizes a SessionBudget to enforce resource constraints on headless instances, preventing memory exhaustion or runaway processes.

​
Sources: