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

Guests and lifecycle

PocketJS/QuickJS is one execution substrate, but each Guest is an isolated runtime and context with its own globals, objects, promises, job queue and heap. A Guest is not a thread and not a second framework.

Maximum resident Guest shape

1 resident Pi Agent System Guest
+ up to 3 ordinary View Guests       independent LRU
+ up to 3 ordinary Action Guests     independent LRU
= up to 7 QuickJS Guests

The platform links one PocketJS/QuickJS implementation into firmware. Every Guest creation allocates an isolated runtime/context on that substrate. The System Framework is evaluated inside a Guest; it does not consume its own cache slot.

System Guest

  • created once during AppSupervisor boot;
  • contains the Pi Agent loop, conversation heap, Tool registry and Root View;
  • outside both ordinary-App LRU caches;
  • advanced even when an ordinary App is foreground;
  • destroyed only by shutdown or explicit System restart, not by navigation.

Ordinary View Guest

  • loads platform Framework, shared View SDK, declared JSON resources and view.js;
  • receives a read-only mount of the App's shared native SQLite owner;
  • owns View state, retained UI nodes, hit testing and Projection bindings;
  • ticks and renders only when foreground;
  • may remain cached after navigation, but must tolerate eviction.

Ordinary Action Guest

  • loads platform Framework, net SDK when allowed, resources and actions.js;
  • receives writable App SQLite operations and scoped native services;
  • runs Tool, UI and schedule Actions through the same dispatch surface;
  • may exist while its View is closed or may not exist while its View is open;
  • executes one admitted Action at a time in v1.

Why two ordinary caches

View lifetime follows navigation; Action lifetime follows capability use. Combining them would keep provider promises and response objects alive with the UI, or force a long Action to block View lifecycle. Independent LRUs let each side be bounded by its actual usage while sharing one durable App boundary.

What is shared and what is not

Shared by an AppNot shared between Guests
native SQLite owner and database fileJavaScript objects, globals and closures
data root and installed release sourcepromises and job queues
atomic revision counterView reactive state
manifest capabilities/resourcesnetwork response objects and call stacks

Eviction contract

Eviction discards the entire ordinary Guest heap. The next use evaluates the Framework and App source again. SQLite/files, installed source and native schedule state remain. Therefore App initialization must be deterministic and must not assume an earlier JavaScript object still exists.

If losing an ordinary Guest loses important product information, that information was stored in the wrong place. Persist it in App Data, then rebuild bounded presentation state from a Projection.