PocketPi
Browse documentation

Start here

OverviewGetting startedThe mental model

Use the runtime

Run the simulatorPi Agent and workspaceInstall and manage AppsESP32-P4 reference targetESP32-S3 supported target

Build Apps

App developer guideBuild your first AppApp source and packageData and migrationsActions and ToolsView and interactionNetworking and native servicesApp resourcesSchedulesPackage and updateTesting and debugging

Understand the runtime

Runtime flowGuests and lifecycleLayers and ownershipHarness boundary

Security

Trust and capabilitiesData isolationLifecycle and recovery

Reference

App manifestPocketPi APIView APICLI referenceLimits and compatibility

Examples

Exa App walkthroughRobinhood App walkthrough

Project

Current boundariesValidation status

App developer guide

An ordinary PocketPi App is a small source package, not a firmware module. You write raw JavaScript and SQL, package it into one .pocketapp, install it through the product review flow, and iterate without rebuilding PocketJS or flashing the device.

The developer loop

Define the App boundary
        ↓
Design SQLite as durable product truth
        ↓
Implement actor-neutral Actions
        ↓
Project bounded Data into a fixed View
        ↓
Package → upload → review → install
        ↓
Exercise through Agent Tool + UI + schedule
        ↓
Change source → package update → preserve Data

One responsibility per file

FileOwnsMust not own
app.jsonIdentity, versions, capabilities, Tools, schedules, service policy and resourcesExecutable product behavior or secret values
schema.sqlFinal SQLite shape for a fresh installHistorical migration sequence or runtime transaction control
actions.jsValidation, native service calls, normalization, SQLite writes and domain resultsForeground layout or actor-specific duplicate logic
view.jsBounded Projections, presentation state, interaction and fixed UIProvider calls, credentials or direct SQLite writes
assets/*.jsonManifest-declared frozen source dataSecrets, executable modules or undeclared files
migrations/N.sqlOne forward SQLite step from N−1 to NBEGIN, COMMIT or PRAGMA user_version

Design from product state outward

Start by asking what a person should still see after the device restarts. Those facts belong in App-owned SQLite. Next, list every way that state changes. Each change becomes a named Action. Expose only the Actions the Agent needs as public Tools. Finally, bind bounded queries to a fixed View.

This order prevents two common mistakes: turning the View into the business runtime, and treating the Agent as a workflow interpreter for deterministic product behavior.

Choose the right trigger

NeedUseWhy
The Agent may decide whether/when to actPublic Tool → ActionReasoning selects a deterministic capability
A person directly requests behaviorUI event → same ActionNo duplicate business path
Periodic deterministic workApp schedule → same ActionNo model turn or foreground View required
Reasoned follow-up across AppsAgent wake scheduleRuns a prompt through the resident Agent loop

Development sequence

  1. Complete Build your first App without adding networking.
  2. Read App source and package before changing file layout.
  3. Model durable state with Data and migrations.
  4. Define behavior through Actions and Tools.
  5. Build the human surface with View and interaction.
  6. Add external access only through Networking and native services.
  7. Exercise install, restart, update and failure paths in Testing and debugging.

Ordinary App packaging has no Bun, TypeScript, JSX or PocketJS compile step today. The device evaluates actions.js and view.js as source inside bounded Guests.