Skip to content
paiOS Docs

OS & Infrastructure

This page documents the Operating System and Infrastructure environment that hosts the paiEngine process.

Unlike the engine itself, which follows a Hexagonal Architecture (Ports and Adapters), the infrastructure beneath it can be viewed as a classic stack from hardware up to the OS service manager.

For a zoomed-out view of how third-party applications and external clients integrate with the engine (REST, gRPC, MCP), see C4 Architecture: System Context and Container diagrams.

Deployment & Service Context

Section titled “Deployment & Service Context”
flowchart TD
  subgraph OS ["Debian-based OS"]
      direction TB
      Systemd["systemd (Service Manager)"]
      Engine["pai-engine (Daemon)"]
      Kernel["Radxa Vendor Kernel"]
      RAUC["RAUC Update Client"]
      Disk["RootFS A/B Partitions"]
      ThirdParty["3rd Party App"]
      API(("API"))
      
      Systemd -->|Lifecycle| Engine
      Engine -->|syscalls & dev nodes| Kernel
      RAUC -->|Updates| Disk
      ThirdParty -->|IPC: gRPC/UDS| Engine
      Engine -->|exposes| API
  end

  subgraph HW ["Rockchip RK3588S2"]
      direction LR
      NPU["NPU"] --- Camera["Camera"] --- Mic["Microphones"] --- USB["USB-C"]
  end

  Kernel -->|Drivers| HW
Diagram (Expanded View)

The diagram includes a minimal view of third-party integration: an app on the same device communicates with the engine via IPC (gRPC over UDS); the engine exposes an API (REST/gRPC) for custom UIs and integrations. For protocols, clients, and a full system view, see C4 Architecture.

Infrastructure Components

Section titled “Infrastructure Components”

🔧 Layer 0: Hardware

Section titled “🔧 Layer 0: Hardware”

The physical components of the paiOS device.

ComponentDescription
SoCRockchip RK3588S2 with 6 TOPS NPU + Mali-G610 GPU
MicrophoneUSB mic / 3-mic beamforming array
USB-CComposite device (HID + UAC + Mass Storage)
CameraRadxa Camera 4K2 (or generic UVC camera)
BatteryIntegrated battery for standalone operation

💾 Layer 1: Operating System

Section titled “💾 Layer 1: Operating System”

Custom Debian-based OS built with Debos (ADR-002 explains why we chose it).

ComponentTechnologyPurpose
KernelRadxa Vendor Kernel (via APT)Hardware support for RK3588S2
DriversNPU, GPU, USB Gadget, i2sHardware access for AI processing
systemdService ManagerManages pai-engine daemon and network startup
UpdatesRAUCA/B Update System for atomic OTA updates (Note: Assumed/pending ADR)

Hardware Abstraction & Security

Section titled “Hardware Abstraction & Security”

A core principle of the paiOS architecture is that only the pai-engine has direct access to hardware peripherals (such as the camera, microphone, and NPU).

This hardware abstraction provides a critical security advantage:

  • Exclusive Access: By design, third-party AIs and applications cannot read directly from hardware device nodes like /dev/video* or /dev/snd/*. They must request audio or vision data through the engine’s API or IPC interfaces.
  • Centralized Permissions: Because all hardware requests funnel through the engine, the engine’s PermissionManager (part of the Common domain, common) can reliably enforce access control. It verifies authorization tokens and user consents before routing data to the requesting app.
  • Implementation via udev Rules: To enforce this on the OS level, custom Linux udev rules must be configured. These rules alter the default behavior (where devices are typically assigned to generic video or audio groups) to assign ownership of critical device nodes exclusively to the pai-engine system daemon (e.g., via OWNER="pai-engine", MODE="0600"). This prevents any other OS process from bypassing the engine’s security layer.

Technology Stack

Section titled “Technology Stack”

The infrastructure technologies supporting the runtime environment:

LayerTechnologyLicense
OS EnvironmentDebian (customised via Debos)AGPL-3.0 (for build tools)
OS UpdatesRAUC (Pending ADR)LGPL-2.1
Service ManagersystemdLGPL-2.1

For detailed technology choices within the engine itself (Rust, NPU bindings, AI models), refer to the Engine Architecture ADR and Engine Domains.

Section titled “Related Documentation”