PocketPi documentation

Build with the Agent-native runtime

Start the runtime, develop an App, operate physical hardware, or trace the system from an actor request to a rendered View. Every page below has one explicit job.

35 focused pages

Documentation map

Start here

Build the right mental model and reach a working runtime.

Overview Getting started The mental model

Use the runtime

Run, configure and operate PocketPi.

Run the simulator Pi Agent and workspace Install and manage Apps ESP32-P4 reference target ESP32-S3 supported target

Build Apps

Author, test, package and evolve an ordinary App.

App developer guide Build your first App App source and package Data and migrations Actions and Tools View and interaction Networking and native services App resources Schedules Package and update Testing and debugging

Understand the runtime

Trace ownership, execution, Guests and Harness boundaries.

Runtime flow Guests and lifecycle Layers and ownership Harness boundary

Security

Review capabilities, credentials, isolation and recovery.

Trust and capabilities Data isolation Lifecycle and recovery

Reference

Look up exact source, API, CLI and limit contracts.

App manifest PocketPi API View API CLI reference Limits and compatibility

Examples

Learn from complete Apps with real product boundaries.

Exa App walkthrough Robinhood App walkthrough

Project

Separate implemented behavior, evidence and future direction.

Current boundaries Validation status

Product overview

PocketPi is an Agent-native runtime for embedded and dedicated devices. It keeps an Agent resident on the product and gives it a durable workspace, native capabilities, schedules, and installable Apps with local Data, shared Actions and fixed human-facing Views.

The shortest useful definition

PocketPi = resident Agent + durable workspace + native capabilities + Apps

App = Data + Actions + View

The Agent is not launched for one request and then discarded. It shares the device lifecycle, owns its top-level /workspace, and can reason across the capabilities that are currently installed. An App is not just a Tool and not just a screen: it combines durable product state, deterministic behavior, and a fixed interface for people.

One concrete device story

The device boots and restores the resident Pi Agent and its /workspace.
The Agent sees native Tools plus the public Tools of installed Apps.
A person asks the Agent to refresh a portfolio, or taps the App's refresh button.
Both requests route to the same named App Action.
The Action calls an allowed native service and commits normalized data to App-owned SQLite.
The successful transaction increments one App revision.
If the App View is visible, its bounded Projection re-queries SQLite and the fixed View refreshes.
If the View is closed, the data still commits; the View projects the latest state when opened later.

Agent Tool ─┐
UI event   ─┼─→ Action → native capability → SQLite → revision → Projection → View
Schedule   ─┘

The four things to keep separate

Part	Responsibility	Durable state
Pi Agent	Resident reasoning, cross-App coordination and workspace Tools	`/workspace`
Ordinary App	Domain Tools, Actions, schedules, local Data and fixed View	Its private SQLite/files
PocketJS	Bounded JavaScript Guests, UI tree, layout and rendering contracts	None by itself
Native Host	Hardware, transport, credentials, enforcement and lifecycle	NVS/LittleFS or host equivalents

PocketPi is the product name

The precise technical category is Agent-native runtime. PocketPi is broader than the embedded Pi Agent loop: it owns the Agent/App lifecycle, capability boundary, schedules, workspace, foreground selection and recovery model. Pi Agent remains the current resident Harness; a replaceable Harness boundary is a staged target, not a shipped claim.

Product name: PocketPi. Technical category: an Agent-native runtime for embedded devices.

Choose your path

Your goal	Start with	You will finish with
See the product running	Getting started	A persistent simulator workspace and resident Agent
Build an App	App developer guide	A packaged App installed through the real review path
Operate physical hardware	ESP32-P4 or ESP32-S3	A provisioned standalone target and an explicit validation boundary
Understand internals	Runtime flow	Ownership and lifecycle traced from actor to display
Integrate a different Harness	Harness boundary	A clear view of current Pi coupling and the planned replaceable seam

Current product surface

ESP32-P4 is the reference target, and ESP32-S3 is a supported second physical target. The macOS esp32-sim runs their shared AgentOS, App source, Tool catalog, workspace and View contracts with development adapters. It is the normal development loop, not a second desktop product and not a CPU/peripheral emulator.

The current resident Harness is Pi Agent. Ordinary source Apps can already be installed, updated and uninstalled independently. Harness replacement is a planned runtime boundary, not an implemented claim. See Current boundariesfor the fact/target split.