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

Getting started

This is the fastest path from a clean checkout to PocketPi running locally. You will use the macOS product-contract simulator, preserve one workspace between launches, and verify the resident Agent before writing an App.

Prerequisites

You want to…You need
Run the simulatormacOS, Rust stable, Bun and a logged-in codex CLI
Regenerate the shared View SDKA PocketJS checkout at the revision pinned by tools/xtask
Write/package an ordinary AppA text editor; packaging itself needs no PocketJS/Bun compile step
Build physical firmwareThe esp-rs/ESP-IDF toolchain, pinned Rust nightly and espflash

Install Rust with rustup and Bun before starting. Physical targets additionally need the ESP Rust toolchain and espflash.

1. Clone PocketPi

git clone https://github.com/pocket-stack/pocket-pi.git
cd pocket-pi

Normal simulator and firmware builds use the generated Pi Agent bundle and View SDK resources committed to this repository. You do not need a PocketJS checkout to start using PocketPi.

2. Start the simulator

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

This builds and starts the simulator with the committed Pi Agent and View SDK assets. Reuse the same --workspace path so Agent files, installed Apps and App SQLite state survive subsequent launches.

3. Verify the first successful boot

You should see:

  • a 720×1280 product surface scaled into a macOS window;
  • the Pi Agent Root View with Chat, Files, Apps and Settings;
  • Agent status moving from STARTING to IDLE;
  • an App installer listening at http://127.0.0.1:8080;
  • memory.md and notes.txt inside the chosen workspace.

Submit a small prompt such as “List the files in your workspace.” A complete answer proves that the resident Agent guest, model backend, Tool router and simulated workspace are connected.

4. Restart without losing the workspace

Stop the simulator and run the same command again. Workspace files persist because they live under the path you supplied. The conversation itself currently lives in the resident QuickJS heap and is not restored after reboot; that is a documented current boundary, not a workspace failure.

What this run proves

Proved by the simulatorStill requires hardware
AgentOS ownership, App source loading, Tools, workspace, schedules, fixed Views and macOS adaptersESP32 boot, PSRAM pressure, LittleFS, NVS, Wi-Fi, LCD scanout, touch controller and live board transport

Next, build and install a real source App in Build your first App. For the full simulator CLI and provider choices, see Run the simulator.

Regenerate System assets only when changing them

Rebuild the resident Pi Agent bundle independently. A PocketJS checkout is required only to regenerate the shared View SDK resource pack, and xtask verifies its exact pinned revision before writing the generated resource back into PocketPi.

cargo xtask build pi-agent

git clone https://github.com/pocket-stack/pocketjs.git ../pocketjs
git -C ../pocketjs checkout e12cf12f82cc60b636368119d49a06eb9ed2a3d5
POCKETJS_ROOT=../pocketjs cargo xtask build view-sdk