Poki README

Poki uses your iPhone like you do

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español
poki.bot

Quick start

Poki on your iPhone

Tell your agent:

Install Poki on my iPhone from https://github.com/JosssphZhou/poki

The agent follows the install-poki skill and runs bin/install-iphone.mjs, which does every step it can by itself. You only do what iOS asks of you: type your Apple Account into a Poki Setup window on the Mac, tap Trust and turn on Developer Mode on the iPhone, trust the developer, and open Poki. When Poki first opens it asks for Automation Mode: tap Continue and enter the iPhone passcode. If you cancel, turn Poki on again to be asked again. The agent tells you each one in a sentence when it comes up. A free Apple Account works.

Requires macOS 14+, Node.js 24+, iOS 18+, a USB data cable, an Apple Account, and a VPN app on the iPhone that routes 10.7.0.1 back to it. The free LocalDevVPN from the App Store works, and so do Karing and Shadowrocket set up through Poki's Setup instructions. On iOS 27 and later Poki controls the iPhone through its native services by default. On iOS 18 to 26 it uses the XCTest session instead, as Alpha 0.2.9 did; this release was not tested on a physical iPhone below iOS 27. Xcode is not required. Free Apple Account signing lasts 7 days and needs renewal. Enable UI Automation in the iPhone's Developer settings. Poki also needs your own model account. Signing in with a ChatGPT Plus or Pro plan is the easiest start; you can also paste an API key from Anthropic, OpenAI, Gemini, DeepSeek or OpenRouter, or use your own OpenAI-compatible server. A Claude subscription cannot sign in, so use an Anthropic API key instead. With an older Poki Setup and no Xcode, the agent asks you to finish model-key and connection setup manually and reports those checks as unverified until you confirm them.

No Node.js 24, or on Windows? The same prompt works once Poki Setup is installed: the agent then uses the command line tool inside Poki Setup. Poki Setup's own menu also copies a prompt for your agent (Poki > Copy Prompt for Your Agent on a Mac, Settings > Use an agent on Windows).

Prefer clicking through it yourself? Download Poki Setup for macOS or Windows (contributed by @ZhehanZhang) from the Alpha release and follow its window.

Poki MCP for your agent

Let your agent install it. Copy this to your agent:

Install https://github.com/JosssphZhou/poki following its root AGENTS.md, including the MCP skill, and stop whenever you need me to act.

Poki MCP. Already using Claude Code, Codex, or another MCP client? Connect Poki MCP and use your own subscription. No extra model account needed.

Start the server and keep it running:

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

Requires macOS 15 or later, full Xcode, Rust, Node.js 24+, and ffmpeg. ./bin/setup checks for missing dependencies. The initial build takes a few minutes.

Poki targets macOS. For Linux, see the community port poki-for-linux (#16), maintained outside this repo.

Poki MCP on Windows: community port at scy7796/poki-for-windows (maintained by its author, not tested by us).

Prebuilt macOS arm64 package

Download poki-v0.1.1-macos-arm64.tar.gz from the release and run:

tar -xzf poki-v0.1.1-macos-arm64.tar.gz
cd poki-v0.1.1
npm ci --no-audit --no-fund
npm start

The package includes the native bridge and idevice tools. You do not need Rust or ./bin/setup. You still need macOS on Apple Silicon, full Xcode, Node.js 24+, Python 3, and ffmpeg. Register your MCP client and install the optional Agent as described below.

In another terminal, from the same directory, register the MCP server:

claude mcp add --scope user poki-mcp -- node "$PWD/src/stdio.mjs"   # Claude Code
codex mcp add poki-mcp -- node "$PWD/src/stdio.mjs"                 # Codex

Poki Agent. For Poki's standalone terminal agent or messaging channels, keep npm start running and open another terminal in the same directory. Install the agent, add its command to this terminal's path, and sign in:

npm ci --prefix agent
export PATH="$PWD/bin:$PATH"
poki login
poki status

Poki Agent uses GPT-6.1 Terra (gpt-6.1-terra) with low reasoning by default. We recommend keeping it: it is the fastest setup we have tested for phone tasks. Override it with POKI_AGENT_MODEL; see Run Poki Agent.

For a physical iPhone, pair it with your Mac over USB first. See Physical iPhone setup.

Update with ./bin/poki update. Set POKI_NO_UPDATE_CHECK=1 to disable the daily anonymous GitHub release check. See Update for the request URL, restart steps, and prebuilt packages.

Try a task

With Poki Agent, one connected iPhone is selected automatically. With multiple devices, add --device '<device UUID>'.

node bin/call.mjs list_devices   # Find your device UUID
poki "Search esp32 in Chrome and summarize the top result"

Note: Poki controls your real iPhone. If you ask it to send messages or make payments, it will. Screen contents are sent to your configured model service.

Gets faster with use: Poki Agent remembers past tasks and runs them faster on repeat.

Channels: After configuring an authorized channel, start it with poki imessage or poki telegram. See Poki Agent for setup.

MCP clients: Claude Code, Codex, and any client supporting mcpServers JSON.

Physical iPhone support has been verified only on iPhones using the Chinese interface. Physical devices support portrait orientation only. App container export and direct links to Settings subpages are unavailable. See verification and known limits.

Docs

Roadmap

Star History

Poki keyboard

On the native path Poki types through its own keyboard panel at a person's pace, without reading the screen while it types. The panel has no keys and is not a keyboard for people: it shows while Poki types and has a Take Over button. Nothing is pasted unless you choose Paste in Advanced. See docs/poki-keyboard.md.

Core contributors

makirqi-alt Filed Poki's first issue, #1, on iOS 18.6.2: screenshots worked, accessibility and touch did not, and the clear split made it easy to follow.	ZhehanZhang The great co-creator of Poki.	edge369 Made Poki run on a router in #14, so Telegram can drive the iPhone with the Mac powered off; #15, #17 and #19 followed.
mawenhao1028 Reported in #6 that usbmuxd listed no iPhone on macOS 27.2; Poki now says so plainly and why a helper stops early (#59).	igc110 Found why taps on a physical iPhone were slow in #10; the fix that followed made them about a third faster.	carrotciallo Ported Poki to Linux and tested it on a physical iPhone over USB, LAN and Tailscale in #16; the README now points to it.
guangtouge82 Traced failing touches on a physical iPhone to a missing display service in #18; Poki now says nothing was sent and points to prepare-device.	Dreaminmaster Fixed a corrupt cached route that aborted unrelated Agent tasks (#21, #22), then let the Agent reuse its post-action screen read in #37.	PeterKingXu1s Reported in #25 that a natural-language stop request did not interrupt an iMessage task; Poki now replies to mid-task messages and points to /stop.
ScottH1122 Reproduced two Agent bugs in #27 and #28, then merged seven fixes and test repairs, from cancelled input locks (#102) to invalid touch coordinates (#136).	jiahuipaung Fixed in #34 a RemotePairing connection that died when the iPhone's LAN address changed (#30); a real iPhone reconnected in 768 ms.	Zeno6898 Field-tested the iPhone app over cellular and from Windows in #35 and #40, which led to the Wi-Fi setup note (#138); reported #162.
scy7796 Fixed taps that failed every time over RemotePairing from a Windows host in #39; 5 of 5 taps then worked.	foshanfm Ran an insurance-terms check on a real iPhone over Tailscale in #42; the report shaped clearer USB errors and a per-session transport switch.	xiaweiyi713 Recorded demo videos of Poki driving a real iPhone, so new visitors can see what it does before installing anything.
f******* Added OpenCode Go as a model account in the iPhone app in #68, with its own Keychain credential and independent model choice.	owensn951954688 Posted a full timeline of Runner pairing failing after 25 idle minutes in #69; Setup now points to Loopback and Pairing (#70).	kira-ariaki Made batch calls report an ambiguous device instead of crashing (#74), added POKI_MCP_DEVICE (#75) and an optional per-task approval gate (#77).
Purelite Fixed pairing setup sending people to the wrong Settings page, so the Developer Mode and UI Automation steps now open the right one (#137).	heyallencao Fixed screen reads that ran past their call deadline in #139, with a regression test for consistently slow runner responses.

Thanks

Thanks to everyone who opened an issue or pull request. Your feedback and fixes make Poki better.

ZhehanZhang	carrotciallo	Dreaminmaster	edge369	foshanfm
f*******	guangtouge82	heyallencao	htx996	igc110
iTry	jiahuipaung	kilingzhang	kira-ariaki	lunar-me
makirqi-alt	mawenhao1028	oasis979559-alt	owensn951954688	PeterKingXu1s
Purelite	ScottH1122	scy7796	wanghao-SunSky	windywendyday
xiaweiyi713	zcyoung2000	Zeno6898	zqy5608

Disclaimer

Poki is an independent open source project. It is not affiliated with, or endorsed by, Apple, OpenAI, or the makers of any app or website it operates. iPhone is a trademark of Apple Inc.

Automating third-party apps and websites may violate their terms of service. Decide for yourself whether to use Poki with a given service. You are responsible for what it does on your device and accounts, including messages it sends, changes it makes, and any account restrictions that result.

Poki is provided "as is", without warranty, as set out in the AGPL-3.0 license.

License

Poki's code is open source under the AGPL-3.0-only license.

The Poki bear, the app icon and Poki's other artwork are not covered by that license. You can use screenshots to write about Poki; a fork needs its own name and artwork. See BRAND.md.

Copyright (c) 2026 Joseph Zhou (周瑟夫) and contributors. Open-source dependencies and third-party assets retain their respective licenses; see THIRD_PARTY_NOTICES.md. To contribute, see CONTRIBUTING.md.

Acknowledgments

_{Open source acknowledgments: pi | idevice | idb | BlueBubbles | Hermes Agent | MCP SDK | sharp | FFmpeg}