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

Testing and debugging

A successful JavaScript evaluation is only the first evidence tier. An App must also prove routing, SQLite ownership, Projection refresh, restart restoration and update safety. When a path depends on hardware or live transport, also verify fresh physical behavior.

Use a fresh simulator workspace for clean-install tests

cargo xtask run esp32-sim \
  --backend codex \
  --workspace target/app-test-workspace

A separate path gives you a genuinely fresh App catalog without destroying another development workspace. Keep a second persistent path for update/migration testing.

Minimum App test matrix

CaseWhat to verify
PackageOnly expected files; credential ids and resources match manifest
Fresh installReview → confirmation → Tool registration → App opens
UI ActionTap routes to Action; transaction commits; visible Projection refreshes
Agent ToolAgent sees namespaced Tool and receives the completed result
Headless scheduleAction runs with View closed; data appears when reopened
RestartInstalled source, SQLite and schedules restore; transient Guests do not matter
Code-only updateSource changes; schema/data and credentials remain
Schema updateEvery migration runs; existing rows survive
Rejected updateDowngrade/missing/failing migration leaves installed release and data intact
Uninstall/reinstallAll App-owned state disappears, then fresh install starts clean

Repository checks

cargo test --workspace
bun test apps/pi-agent/text.test.js
cargo clippy --workspace --all-targets -- -D warnings
cargo xtask build esp32-sim
cargo xtask build esp32-p4

These cover Rust runtime contracts, Pi Agent text helpers, linting and both host builds. They do not automatically prove a specific App's real provider behavior or physical UI.

Inspect a package before upload

tar -tf target/pocketapps/example.pocketapp
tar -xOf target/pocketapps/example.pocketapp app.json

Check that updates omit credentials.json, resource paths match declarations and every intended migration file is present.

Localize by lifecycle stage

Failure appears…Inspect first
During packagingDirectory id, manifest identity, credential ids, asset/migration filenames
Before reviewArchive shape, size, Framework API, capabilities and manifest policy
During candidate validationschema.sql, missing Action names, View evaluation and Projection SQL
When Action runsargument validation, remaining deadline, native policy, provider status and thrown error
After commit but View is staletransaction usage, bounded Projection registration, foreground App and revision path
Only after restartworkspace path, installed release, SQLite file, update recovery and schedule store
Only on the boardPSRAM, LittleFS, Wi-Fi/NVS, TLS, response bounds, touch/display and UART state

Evidence tiers

source inspection
  < unit / contract tests
  < simulator end-to-end
  < ESP32 cross-build
  < physical boot and UI
  < fresh physical provider end-to-end

Report the highest tier actually observed and name what remains. A green simulator does not prove Wi-Fi association; a boot does not prove a fresh provider response; an older physical result does not automatically validate a later Source App refactor.