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

Lifecycle and recovery

App lifecycle is centralized in AppSupervisor. Ingress adapters cannot partially install an App, and candidate JavaScript cannot decide when it becomes live.

Fresh install state machine

receive complete package
  → stage outside live App root
  → validate archive + manifest + source
  → reserve one review slot
  → human confirms
  → initialize candidate Data
  → evaluate Actions + View
  → store credentials natively
  → move one release into place
  → register Tools + schedules
  → active

Any failure before activation removes incomplete candidate state. HTTP/UART never writes the live App root, Tool catalog or credentials directly.

Update state machine

receive candidate for existing id
  → reject credentials / permission changes / schema downgrade
  → review current vs candidate version/schema
  → human confirms
  → wait for quiescent App boundary
  → copy SQLite
  → rehearse migrations + Actions + View
  → write .update/release recovery signal
  → migrate live DB in one transaction
  → swap single source release
  → replace routes, schedules and cached Guests
  → remove temporary old source

Power-loss recovery

The presence of .update/release means a person already approved a complete candidate and activation did not finish. On boot, the runtime re-runs any uncommitted migration and completes the source swap before loading the installed App index.

SQLite transaction semantics keep a partially applied migration from becoming the durable shape. Candidate source is complete before the recovery signal exists.

Recovery is not rollback

  • There is one active release, not a retained version history.
  • Recovery finishes an approved forward update; it does not choose an older version.
  • Schema downgrade is rejected.
  • An App cannot request its own update through an Agent Tool today.

Uninstall is the reverse ownership operation

After explicit destructive UI intent, the same supervisor removes every resource owned by the ordinary App: routes, schedules, cached runtimes, native credentials/session state, release source and full data root. A restart must not rediscover the App.

Back up or export domain data before uninstall if the product needs retention. The current runtime intentionally does not keep orphaned App data or offer undelete.