Quickstart

A first run on Android

From nothing to a run in your workspace on an Android phone. iPhones need one more step, in iPhone setup.

1. Install the hub

curl -fsSL https://proofsheet.dev/install.sh | sh

The script checks for an Apple Silicon Mac on macOS 26 or later, downloads the latest release, checks its checksum and its signature, and installs proofsheet, proofsheet-capture and Proofsheet.app into ~/.local/bin. Proofsheet.app keeps the hub running and starts again when you log in. The script also adds the proofsheet MCP server to the agent CLIs it finds.

If ~/.local/bin is not on your PATH, the script says so. Add this line to ~/.zshrc, then open a new terminal:

export PATH="$HOME/.local/bin:$PATH"

2. Get the phone ready

  • Install adb: brew install --cask android-platform-tools.
  • On the phone, turn on Developer options and USB debugging. The menu path varies by maker; on most phones, tap Build number seven times in Settings > About phone.
  • Plug the phone in by USB and allow USB debugging for this Mac when the phone asks.

3. Sign in to your workspace

proofsheet portal login

It opens your browser to sign in and pick the workspace. If you belong to several, preselect one with --workspace yourteam. Only admins of a workspace can upload runs to it.

4. Set up your app repo

cd your-app
proofsheet init --android com.example.app

Use your app's package in place of com.example.app; add --ios <bundle id> if you test iPhones too. In one go, proofsheet init:

  • makes the repo a project, named after its folder (--name picks another);
  • writes e2e/proofsheet/config.toml and an example flow, e2e/proofsheet/flows/example-settings.md, which opens the phone's Settings app, so it runs on any phone;
  • adds the proofsheet skill to the repo, in .agents/skills and linked into .claude/skills, with npx skills (it needs Node.js);
  • adds the proofsheet MCP server for your user to Claude Code, Codex and Antigravity;
  • runs proofsheet doctor.

Run it again any time: what is already set up stays as it is. Commit e2e/proofsheet/ so your team shares the flows.

5. Check the setup

proofsheet doctor

One line per check. A good setup for an Android-only repo looks like this:

ok   project  your-app (/Users/you/your-app/e2e/proofsheet/config.toml)
ok   hub      http://127.0.0.1:8765 (hub 0.1.2)
ok   devices  Pixel 8 (android)
ok   android  Android Debug Bridge version 1.0.41 (/opt/homebrew/bin/adb)
skip ios      this project has no iOS app
skip web      this project has no web app
ok   portal   yourteam (https://yourteam.proofsheet.dev) as you@example.com
doctor: all checks pass

A line that fails shows its fix under it. Troubleshooting lists them all.

6. Record the example flow

In the repo, ask your agent:

Author the example-settings flow on my Pixel

The agent works through each numbered item on the phone and records the steps into flows/example-settings.steps.yaml. Recording runs are not uploaded.

7. Run it on every phone

proofsheet e2e run example-settings --all

Or ask your agent to run the example flow on every free phone. A replay uses the recorded steps only, with no AI. When the run finishes it uploads to your workspace, where it starts as a draft that only admins see. Publish it on the run page to show it to members and clients.