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

Current boundaries

These statements describe upstream/main at commit8b3866f after PRs #17 through #20. Implemented behavior, validated evidence and future design are intentionally kept separate.

Implemented

  • Implemented Pi Agent is the firmware-embedded resident System App and owns the top-level workspace.
  • Implemented ESP32-P4 is the reference host and ESP32-S3 is a supported second physical host; macOS provides their shared product-contract simulator.
  • Implemented Ordinary Apps execute raw app.json, SQL and JavaScript source.
  • Implemented Ordinary Apps install through HTTP or UART after one shared product review.
  • Implemented Apps update source while preserving compatible SQLite data and native credentials.
  • Implemented Forward SQL migrations rehearse before live mutation and approved interrupted updates recover at boot.
  • Implemented Uninstall removes App routes, schedules, Guests, credentials, native session state, source and data.
  • Implemented Agent Tools, UI events and App schedules route to the same named Actions.
  • Implemented View and Action Guests use independent three-entry LRUs around one resident System Guest.
  • Implemented App commits drive revision-coalesced, bounded foreground Projections.
  • Implemented The shared View SDK exposes one host-provided viewport and composes responsive App interfaces from JavaScript Row, Column and shared components.
  • Implemented Pi Agent can checkout and edit an installed ordinary App, then submit it to the existing physically confirmed update path.

Not implemented

  • a replaceable resident Harness; Pi Agent is the only shipped Harness;
  • conversation/session persistence across reboot;
  • independent System App or System Framework update;
  • release history, persistent rollback, downgrade or undelete;
  • multi-file executable ES modules or on-device TypeScript/TSX/JSX transformation;
  • a package dependency graph, third-party App plugin framework or marketplace;
  • an Agent-exposed App install/update API that bypasses physical review;
  • a generic desktop Agent OS product, CPU/peripheral emulator or web Playground.

Near-term design direction

  1. Research target Make the resident Harness build-time replaceable between Pi Agent and DeepSeek Harness.
  2. Reach product-experience parity before adopting DeepSeek Harness plugins or new session semantics.
  3. Keep App/runtime/host contracts stable while the guest-side adapter changes.
  4. After another real hardware/platform need exists, consider extracting the Pi Agent and DeepSeek Harness compatibility layers into independently reusable packages.
  5. Add a web Playground later by moving the macOS product simulator contract to the web, not by redefining the core App model.

See Harness boundary for the parity contract and explicit deferrals.

Product non-goals that protect focus

  • Do not turn the native host into the place where each App's product logic lives.
  • Do not make the model a required runtime for deterministic refresh, cleanup or rendering.
  • Do not expose raw credentials or private App databases to the Agent for convenience.
  • Do not call simulator or cross-build success physical-device acceptance.
  • Do not add a broad plugin/dependency system before a concrete App proves the small contract insufficient.

The website uses “PocketPi” as the product name and “Agent-native runtime for embedded devices” as the technical category. It does not claim a kernel or RTOS replacement.