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

Trust and capabilities

PocketPi does not trust App source to define its own authority. Apps declare intent; native code validates the package, mounts scoped capabilities, retains credentials and enforces exact transport and lifecycle boundaries.

Trust zones

ZoneTrusted forNot trusted for
Native host/runtimecapability enforcement, credential storage, storage roots, deadlines, package lifecycleApp domain meaning or provider response mapping
Resident System Apptop-level workspace UI, narrow system commands, Agent interactionraw native secrets or arbitrary host calls
Ordinary App sourcedeclared domain behavior and fixed Viewother Apps, top-level workspace, undeclared endpoints/operations
Agent/model outputintent, reasoning and selection among advertised Toolscredentials, direct database writes or bypassing confirmation
Package transportmoving one complete candidate artifactactivating it or writing live App/runtime state

Capability declaration

"capabilities": ["data.sqlite", "net.http"]

The current manifest accepts:

  • data.sqlite for the App-owned database contract;
  • data.fs as a recognized App-local filesystem capability;
  • net.http for the bounded Action fetch() surface.

Duplicate or unknown capabilities reject the App. A declaration does not override native enforcement: the host still decides which module/service surface is mounted and which App id owns it.

Network policy is more specific than a capability

net.http allows the HTTP mechanism, while nativeServices.http declares exact methods, URLs, request headers and optional credential binding. MCP connections declare exact connection URLs, credential binding and a separate operation allowlist. App JavaScript cannot turn those into an unrestricted proxy.

Credential lifecycle

  1. The manifest declares stable credential ids and how native transport consumes them.
  2. A first-install credentials.json carries exactly those values.
  3. The Installer strips the file before App activation and writes values to native storage.
  4. At request time, native code applies the value only to an allowlisted operation.
  5. Update packages omit credentials and preserve installed native values.
  6. Uninstall removes credentials owned by that App.

A raw credential never needs to enter App source, App SQLite, the Agent workspace, Tool arguments, the fixed View or model context.

Human review

Both HTTP and UART ingress stop at one review screen. Review makes the candidate identity, version, Tools, schedules and network/credential needs visible before lifecycle mutation. It is an installation boundary, not blanket approval for every future real-world action an App Tool might perform.

Product-level safety still belongs to the App

An allowlisted provider operation is necessary but not sufficient for high-impact behavior. The App must describe side effects accurately, validate arguments, use idempotency identifiers where offered, avoid unsafe retries after ambiguous responses and introduce explicit product confirmation where the domain requires it.