Develop and debug FoloToy AI Passport firmware without the device.

Run unmodified ESP-IDF firmware in your browser or on your desktop.

Try it online: passportsim.bugs.cc, nothing to install.

English | 简体中文 | 日本語 | Français

What you can do

• Run firmware without a device. Drop a build onto the page; the screen, buttons, sound and
  serial console work as on the board.
• Debug it. Pause, step, save and restore state, read the console, the UI tree, tasks and
  memory.
• Try other people's firmware. Any merged .bin, idf.py build folder or .pebundle runs as
  is. Nothing is uploaded; everything stays in your browser.
• Automate it. A command line and an MCP server for scripts, CI and AI agents.

Quick start

The quickest way is the online version: open it and drop your
firmware on the page.

Install the CLI from the latest release:

curl -fsSL https://passportsim.bugs.cc/install.sh | sh      # macOS (Apple silicon)

irm https://passportsim.bugs.cc/install.ps1 | iex           # Windows x64 (PowerShell)

To build and run it from a checkout you need Rust, Bun and just
(or make).

just setup    # once
just run      # build and open the web UI at http://127.0.0.1:4173/

Other commands:

With make, pass arguments as variables: make run PORT=8080, make cli ARGS="start".

In the browser

• Simple mode opens first: the device, a place to drop your firmware, and a log.
• Advanced mode adds run control, the serial console, the UI tree, event recording, and
  cards for battery, USB, audio, NFC, Wi-Fi and Bluetooth.

The page is available in English, Chinese, Japanese and French, in light and dark themes.

_{Advanced mode: run control, the serial console (filtered to boot), and the cards for battery, USB, audio, Wi-Fi, Bluetooth, NFC and snapshots}

_{Loading your own firmware (here Passport Keys)}

From the command line

just package
cd target/package/passportsim-*-macos-arm64
./passportsim start                  # boot the demo
./passportsim start path/to/firmware.bin
./passportsim screenshot             # save the screen as a PNG
./passportsim serial read            # read the console
./passportsim stop

On Windows the binary is passportsim.exe. The quickstart covers first
launch on each system.

With AI agents

passportsim mcp is an MCP server. Add it to your MCP client:

{ "mcpServers": { "passportsim": { "command": "/path/to/passportsim", "args": ["mcp"] } } }

The agent can boot a build, press buttons, wait for a console line, read the UI tree and take
screenshots. Add the agent skill with
npx skills add BlackHole1/passportsim, or copy skills/passportsim/ into your agent's skills
directory.

_{The UI tree an agent reads, with the hovered widget outlined on the screen}

Supported systems

Learn more

Contributing and license

Contributions are welcome; see CONTRIBUTING.md and the
Code of Conduct. Report security issues as described in
SECURITY.md.

MIT, see LICENSE. Third-party material is listed in THIRD_PARTY.md.
FoloToy, AI Passport, Espressif and ESP32 are names of their respective owners.