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

Limits and compatibility

PocketPi uses explicit bounds because the reference target is a constrained device. Some values are public App contracts; others describe the current implementation and may move with measured hardware evidence.

Public App/package contract

LimitCurrent valueBehavior
Package format1Other formats rejected
Framework API1Must equal installed System Framework
.pocketapp size2 MiBRejected at ingress/staging when exceeded
One JSON resource256 KiBRejected before candidate evaluation
All JSON resources512 KiBSum of declared files
Asset archive path100 bytes maximumSafe assets/ components only
Credential count16 maximumFirst-install transport file only
One credential value4096 bytes maximum; non-emptyStored natively after validation
Schema version1 to signed 32-bit maximumForward-only updates
Supported capability names3data.fs, data.sqlite, net.http

Current runtime bounds

BoundCurrent valueDesign consequence
Ordinary View Guest cache3-entry LRUView heap is evictable
Ordinary Action Guest cache3-entry LRUAction initialization must be repeatable
Resident System Guests1Pi Agent stays outside ordinary LRUs
Maximum simultaneous Guests71 + 3 View + 3 Action
Ordinary Action executionone at a timeNo assumed App concurrency
Action admission queue8Do not use Actions as an unbounded job system
Tool Action deadline80 seconds absoluteQueueing, JS and native transport share it
App-local View FS mount quota2 MiBPrefer SQLite for structured durable state
Logical viewport720×1280All View coordinates and layout use this space

HTTP body bounds

App fetch() defaults to a 30-second request timeout and 128 KiBmaxBytes, but the request is also capped by the remaining App Action deadline. Set both values explicitly for the operation. The ESP32 MCP host currently bounds one response at 160 KiB; that is a host implementation limit rather than a generic App HTTP promise.

Source compatibility

  • One classic-script actions.js and one view.js; no imports.
  • No TypeScript/TSX/JSX transform in ordinary App packaging or on device.
  • JSON resources only; no arbitrary binary resource contract.
  • No dependency solver, package graph or App plugin loader.
  • System App/Harness and System Framework update with firmware today.

Treat public format/API/size validation as compatibility constraints. Treat cache counts, queues and worker sizes as current implementation bounds that should change only with profiling and physical-target evidence.