Poki Docs

Appearance

Install ​

Requirements ​

  • macOS with a full Xcode installation from the App Store, opened at least once to finish its first-launch setup (Command Line Tools alone are not enough). Xcode also provides Git and Python 3.
  • Git
  • Node.js 24+ and npm (required for both the daemon and the stdio client)
  • Rust / Cargo with Rust 2024 edition support, from rustup.rs. Setup always uses it to build the iPhone bridge, even if you use only the Simulator.
  • Python 3
  • ffmpeg and ffprobe, from brew install ffmpeg (required for recording; checked during ./bin/setup)
  • iOS Simulator runtime installed in Xcode (for simulator targets)
  • Apple developer support files already installed on the Mac (for physical-device developer services)

./bin/setup checks for these requirements and stops with an installation hint if any are missing. You do not need to set any environment variables. All settings in Configuration and sessions are optional.

Reference environment: Prepared on an Apple silicon Mac with macOS 27.3, Xcode 27.0 (27A5209h), Node 26.10.0, npm 11.19.1, Rust/Cargo 1.99.0, Python 3.13.0, and ffmpeg/ffprobe 9.0.2. These versions record the build environment rather than claiming that every tool and parameter works across all platform versions.

1. Build from Source and Start the Daemon ​

sh
git clone https://github.com/JosssphZhou/poki.git
cd poki
./bin/setup
npm start

./bin/setup takes a few minutes on a first build. What it does:

  • Fetches jkcoxson/idevice at commit 89702099f4d7552f704f93b4526756abda319ceb into .deps/idevice and verifies its revision and clean working tree (stopping without modifying .deps/idevice if mismatched or dirty).
  • Installs locked npm dependencies.
  • Builds the Rust physical-device bridge, Swift OCR helper, and Objective-C simulator bridge. (If you modify native code later, rebuild with npm run build:native.)

Setup does not install Xcode, developer disk images, device profiles, or signing identities.

Keep npm start running while using an MCP client:

  • The daemon listens only on 127.0.0.1:47825 (not exposed to external networks, and not registered as a login item).
  • Its endpoint and bearer token are written to ~/Library/Application Support/PokiMCP/mcp.json (0600) and removed on normal shutdown.
  • The stdio wrapper (src/stdio.mjs) connects to this running daemon; it does not auto-start the service.