apps/android and future apps/ios scaffolds establish the “Mobile Convergence Contract” to ensure that mobile nodes maintain the same security, trust, and capability standards as the primary desktop node host.
Purpose and Scope
The mobile scaffolds serve as the integration point for non-desktop environments into the Palyra control plane. They define the mandatory execution posture and identity requirements for any device acting as a “Node Host.” This ensures that when a mobile client is introduced, it is not treated as a “lite” version but as a first-class, mTLS-authenticated participant in the agentic network apps/android/README.md#1-15.Mobile Convergence Contract
The convergence contract is a set of architectural rules designed to prevent divergence between desktop and mobile implementations. It ensures that thepalyrad gateway can interact with an Android or iOS device using the same protocols it uses for a desktop node_host apps/android/README.md#5-22.
1. Capability Namespace Alignment
Mobile clients must implement and register capabilities using the same namespace as the desktop node host. This ensures that theInventoryDeviceRecord and InventoryInstanceRecord managed by the ControlPlaneClient remain compatible across different OS architectures apps/android/README.md#10-11.
2. Execution Posture
Mobile scaffolds must preserve the distinction between two primary execution modes:- Automatic: Tasks that can be executed in the background without immediate user intervention.
- Local Mediation: Tasks that require the mobile user to explicitly approve or interact with the device (e.g., opening a specific URL or triggering a notification) apps/android/README.md#12-14.
3. Trust and Identity (mTLS)
Mobile clients are required to follow the fullpalyra-identity handshake. This includes:
- Generating Ed25519 keys and X.509 certificates.
- Completing the PIN/QR-based device pairing flow.
- Enforcing mTLS for all gRPC communication with the gateway.
- Policy: Android/iOS is not a “shortcut”; they must adhere to the same approval-bound device pairing as desktop nodes apps/android/README.md#15-16.
4. Offline Discipline
Mobile clients often experience intermittent connectivity. The scaffold requires that:- Offline states are surfaced explicitly to the gateway.
- Pending capability requests are not left in an “active” state if the device heartbeats timeout or the device disappears from the network apps/android/README.md#19-21.
| Requirement | Desktop Implementation | Mobile Contract Requirement |
|---|---|---|
| Identity | DeviceIdentity (Ed25519) | Identical; no exceptions for mobile |
| Transport | gRPC over QUIC/mTLS | Identical; must support palyra-transport-quic |
| Trust State | remote_trust_state | Must be tracked and verified via Gateway |
| Capabilities | Desktop Node Host | Mobile-safe equivalents (Notifications, URL Open) |
Alignment with Desktop Node Host Model
Future mobile clients are designed to align with theNode Host logic found in the desktop supervisor. The desktop ControlCenter monitors the node_host_process and reports its status, including certificate expiration and enrollment state apps/desktop/ui/src/components/HealthStrip.tsx#77-95. Mobile scaffolds are expected to eventually implement a similar internal supervisor for background services.
Node Host State Monitoring
The following diagram illustrates how the mobile scaffold is intended to report its state back to the Palyra ecosystem, mirroring the desktop’sQuickFactsCard and HealthStrip data flow.
Mobile Node State Alignment
Sources: apps/desktop/ui/src/components/QuickFactsCard.tsx#79-92, apps/desktop/ui/src/components/HealthStrip.tsx#77-95, apps/android/README.md#10-16
Technical Implementation Details
Linting and Quality Baselines
To ensure code quality from the outset, the Android scaffold includes a strict linting baseline using Detekt.- Config Path:
apps/android/config/detekt/detekt.ymlapps/android/README.md#25 - Execution: A dedicated shell script
apps/android/scripts/lint.shis provided to run these checks locally before CI integration apps/android/README.md#26-27.
Licensing and Governance
All mobile scaffold code is governed by the Palyra Community Source License (PCSL) v1.1.- Permitted: Personal use, internal company use, and modifications LICENSE#9-10.
- Prohibited: Commercial cloning or hosting as a competing standalone service LICENSE#11-12.
- Identification: The license is explicitly clarified for all crates and apps in the workspace
deny.tomldeny.toml#29-92.
Data Structures for Health Reporting
Mobile clients will eventually populate theControlCenterSnapshot fields used by the UI to display runtime health. Key fields that mobile nodes must support include:
node_host.installed: Boolean indicating if the device is enrolled apps/desktop/ui/src/components/HealthStrip.tsx#81.node_host.running: Boolean indicating background service status apps/desktop/ui/src/components/HealthStrip.tsx#82.node_host.cert_expires_at_unix_ms: Timestamp for mTLS certificate rotation apps/desktop/ui/src/components/QuickFactsCard.tsx#89.