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

PocketPi API

The platform-owned System Framework installs one frozen globalThis.PocketPi in every App Guest before evaluating App source. Native mounts remain authoritative underneath it.

Compatibility

PocketPi.frameworkApi // 1

An ordinary App declares the same value in app.json.

Action registration

PocketPi.defineActions({
  refresh,
  search,
  cleanup,
});

Call once in actions.js. Every property must be a non-empty name mapped to a function. Candidate installation compares the registered names with Tool and schedule routes.

Action and command events

APIReturnsUse
PocketPi.action(name, args = ){ type: "action", action, args }Return from View input to request a local Action
PocketPi.navigate(app)apps.open command eventReturn from View input to open another App, normally pi-agent
PocketPi.command(name, args = ){ type: "command", command, args }Narrow host command event; native authorization still applies

Ordinary Apps cannot gain System privilege by emitting a command string. Installer, device and Agent commands are accepted only from the resident System App where required.

Data

PocketPi.data.query(sql, params)
PocketPi.data.exec(sql)
PocketPi.data.transaction(callback)
  • query returns rows as plain objects keyed by column name.
  • exec executes SQL without parameters and returns no domain value.
  • transaction is available only in writable Action Guests, rolls back on throw and publishes one revision after commit.
  • View Guests may query through Projections but do not receive writable database operations.

Projections

const binding = PocketPi.projection.one(sql, paramsOrFunction, apply)
const binding = PocketPi.projection.many(sql, paramsOrFunction, apply)

binding.refresh()

A binding refreshes immediately when declared. one applies the first row or null;many applies all rows. The returned frozen binding exposes refresh()for App-controlled pagination in addition to revision-driven refresh.

Resources

const value = PocketPi.resources.get("toolCatalog");

Unknown names throw. Returned JSON is recursively frozen inside that Guest.

Native services and deadline

PocketPi.services.call(service, operation, args = {})
PocketPi.actionContext.remainingMs()

services.call is valid only during an admitted Action and throws the native error when the operation fails. remainingMs() reports the remainder of the one absolute Action deadline and should bound downstream work.

View registration

PocketPi.defineView(definition)

The public View SDK calls this from View.mount(). Ordinary Apps should normally mount through View rather than hand-author the lower-level tick/input definition.

System-only API

PocketPi.defineSystem({ update, telemetryVisible })

This is accepted only for App id pi-agent. It binds native SystemFactsto the Root View; ordinary Apps use SQLite Projections instead.

Private ABI

globalThis.PocketPiSystem is the native-facing ABI for configuring a Guest, beginning/polling Actions, refreshing bindings and dispatching input. App source must not call it. Its shape may change with runtime internals even while frameworkApi remains stable.

Authoritative source: system/framework.js ↗.