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

Package and update

Packaging is intentionally mechanical; installation is intentionally strict. The packager gathers the declared source. The Installer is the authority that validates, reviews, rehearses and activates it.

Package commands

# First install without credentials
cargo xtask package app counter

# First install with every declared credential
cargo xtask package app exa path/to/exa-credentials.json

# Update: never carry credentials
cargo xtask package app exa

Inspect the artifact

tar -tf target/pocketapps/exa.pocketapp

Expect only the four required source files, declared assets, valid migrations and optionallycredentials.json for first install. The output file is permission-restricted on Unix.

Version decisions

You changed…versionschemaVersionMigration
View copy or layoutAdvanceKeepNo
Action validation/provider mappingAdvanceKeepNo
SQLite table/index shapeAdvanceAdvanceEvery forward step
Credential id, endpoint or native permissionNew release is not eligible for ordinary updateAs neededInstall contract must be reconsidered

Fresh activation

  1. Stage and validate the package.
  2. Show one product review and wait for human confirmation.
  3. Initialize a new database from schema.sql.
  4. Evaluate Actions and View against the candidate App boundary.
  5. Store credentials natively and remove their transport file.
  6. Move the release into place and register Tools/schedules.

Update activation

  1. Reject credentials, native permission changes, schema downgrade or missing steps.
  2. Wait for a quiescent App service boundary.
  3. Copy SQLite and rehearse migrations plus candidate Actions/View on the copy.
  4. Apply migrations in one live transaction.
  5. Swap the single source release and replace Tools, schedules and cached Guests.
  6. Remove temporary old source after the new App is active.

State that is preserved

  • App SQLite rows and App data files;
  • native credential values already installed;
  • the stable App id and private data root;
  • schedule state that remains compatible with the new declarations.

State that is replaced

  • app.json, actions.js, view.js and declared resources;
  • public Tool routes and schedule declarations;
  • cached ordinary View and Action Guests.

The runtime retains one active ordinary App release. There is recovery for an approved interrupted update, but no release history, automatic rollback or downgrade path.