Features · Safety · Siri · Getting started · Development · Contributing
FlipperHero is an iPhone app that connects to your Flipper Zero over Bluetooth and lets you run it in plain language. Ask what is on the SD card, find a TV remote, emulate your office badge, send the garage signal, install an app or update the firmware. An AI agent does the work, and every action that matters waits for your approval. The rules for that live in code, not in the model.
Everything the interface can do, the agent can do too. Everything the agent does is shown, checked and logged.
Prefer your terminal? The companion flipper CLI drives
the same device over USB and Bluetooth on macOS, Linux, Windows and FreeBSD — human-readable by
default, one JSON document with --json, and built so your local AI agents can use it too. It
speaks the exact RPC this app speaks.
|
Tool-calling models through OpenRouter, 2342.ai, Blackbit, OrcaRouter, Z.ai, Kimi, Qwen Cloud or MiniMax, with a searchable model catalog and connection check. Files, device info, battery, renaming, restarting, firmware updates, the official app catalog, remotes from GitHub, generated Flipper files, and Sub-GHz, Infrared, NFC, RFID, iButton and Bad KB. |
Risk is computed from the parsed action. Changes ask, physical actions need a press and hold, and some things are never allowed. See Safety first. |
|
A live mirror of the Flipper's screen with its D-pad. Tap for a short press, hold for a long one. The agent can look at the screen and press buttons too. |
Firmware, installed apps and saved signals are read on connect, cached per Flipper and handed to the agent, so it does not go looking every turn. |
|
Recognises Momentum, Unleashed, RogueMaster, Xtreme and official firmware, tells you when a release is out, and installs it over Bluetooth with battery and space checks. |
Speak instead of typing, hear answers in the language they were written in, or show the agent a remote or a label. |
|
Ask the agent, check the battery, emulate a card, send a signal or stop the running app, with your saved files offered by name. |
A running emulation, firmware update or armed engagement stays on the Lock Screen and in the Dynamic Island, with a button to stop it. |
An agent that can transmit radio and type keystrokes into computers needs guard rails that do not depend on the model behaving.
| Risk comes from code | Every tool call is parsed and classified by RiskAssessor. Reading runs directly, changes ask, and deleting, transmitting, emulating or anything that can run code is high risk and needs a deliberate press and hold. The model never supplies the risk level. |
| Hard limits | Internal storage, key and secret files, .. paths and recursive deletes of top-level folders are blocked, in every mode. The only way past the path guards is rpc_raw, which stays locked until you arm engagement mode with raw commands, in a dialog of its own. |
| Untrusted input is fenced | File contents, file names, search results and the device inventory are wrapped with a per-session marker and cleaned. Reading any of it taints the turn, and until your next message every change asks again. |
| No self-promotion | The agent can explain YOLO mode or engagement mode and offer either, but switching them on always shows you a permission dialog. Turning things off is free. |
| What you approve is what runs | Generated files and downloads are shown in full during approval and written exactly as shown. |
| Siri follows the same rules | Shortcuts run the same tools with the same checks; where the app would ask, the system confirmation asks. |
| Everything is audited | An append-only log in Settings, readable by you and by the agent. |
YOLO mode is there if you want it: no prompts for the rest of the session, transmissions included. Blocked paths stay blocked, by default it still asks right after reading content from the Flipper, and it resets when the app restarts.
For an authorized engagement, confirming every step gets in the way. Engagement mode is the answer: you arm the session once, in Settings or by approving the agent's request in chat, and pick the capabilities you want.
| Capability | What it unlocks |
|---|---|
| Run actions without prompts | Changes, transmissions and emulations run without a dialog for the rest of the session. Blocked paths stay blocked. |
| Bad KB auto-run | badusb_execute starts a DuckyScript on the Flipper itself over RPC: no one has to press Run. Keystrokes go to whatever machine the Flipper is plugged into. |
| Raw device commands | rpc_raw sends any command from the device's protobuf surface and returns the JSON answer, including commands that bypass the normal path protections. |
Everything else is on the agent already, armed or not: it can operate any app on the Flipper
closed-loop, by looking at the screen and pressing its buttons, edit .sub/.ir/.txt signal and
script files directly, drive the GPIO pins on the expansion header, and pull files from GitHub
or the app catalog.
With a Marauder board on the GPIO header, the open-source edition can use the
marauder agent tool for access-point and station scans, bounded sniffer runs,
and short deauth, probe, beacon or Rickroll radio tests. Deauth requires one AP
index and probe requires one SSID index from the Marauder lists. Every
transmitting test asks for approval, even in YOLO or engagement mode. Install
the allowlisted marauder_bridge.fap from the
CLI repository
at /ext/apps/GPIO/marauder_bridge.fap on the Flipper first. Only test networks
and devices you are authorized to use.
What stays, in every mode:
- Only you can arm engagement mode. The agent can request it; the hold-to-arm dialog is yours.
- Arming is session-only: it disarms on disconnect or app restart.
- The scope note you write is shown on the banner and the Lock Screen and given to the agent.
- Every action is still audited, and one tap compiles the audit log into a timestamped markdown engagement report: what was done, when, and how it was authorized.
- Reading device content still fences it as untrusted, because a prompt-injected agent is an opsec problem, not a safety checkbox.
Two editions. This repository is the full edition. The App Store edition is built from the
same sources with FLIPPERHERO_STORE, which compiles the red team capabilities out entirely:
no Bad KB auto-run, no raw device commands, no GPIO, no Marauder bridge, no engagement mode, and a neutral assistant
prompt. Nothing is hidden behind a switch in the store binary; the capabilities are not in it.
Build it with scripts/build-store.sh, see AGENTS.md.
- Wi-Fi Marauder PoC: RPC-to-UART bridge and bounded agent tools in the open-source edition. The attached board has been verified with the Rust CLI.
| Say | What happens |
|---|---|
| “Ask FlipperHero” | Opens the chat with your request and reads the answer back |
| “FlipperHero battery” | Battery level and charging state, without opening the app |
| “Emulate Office Badge with FlipperHero” | Emulates a saved NFC, 125 kHz or iButton file until you stop it |
| “Send Garage with FlipperHero” | Sends a saved Sub-GHz signal or infrared button once |
| “Stop the Flipper app with FlipperHero” | Ends the running emulation or app |
Actions that need approval ask for confirmation in Siri, and the audit log marks them as coming from Shortcuts. All phrases are localized.
English, Deutsch, Français, Español, Português (Brasil), Italiano, Русский, Українська, Polski, Türkçe, العربية, हिन्दी, 简体中文, 日本語 and 한국어. The approval dialogs, risk explanations, Siri phrases and permission prompts are translated too, because safety text you cannot read does not protect you. The agent answers in whatever language you write in.
Translations were drafted with AI assistance and checked for completeness and placeholders by the test suite. Corrections from native speakers are very welcome.
You need Xcode 26 or newer, an iPhone on iOS 17 or newer (Bluetooth does not work in the simulator), XcodeGen and an API key for a supported provider.
git clone https://github.com/flipper-hero/ios-app.git
cd ios-app
cp Config/Local.xcconfig.example Config/Local.xcconfig # your team id and bundle id prefix
xcodegen generate
open FlipperHero.xcodeprojRun it on your iPhone, then:
- Turn on Bluetooth on the Flipper (Settings > Bluetooth).
- In the Device tab, pick your Flipper and confirm the PIN on both devices the first time.
- Choose your provider in Settings and enter its API key. Choose a model from the live catalog or enter its ID. Test and save sends a short prompt before storing the key in the iOS Keychain. Provider usage charges are separate from the app price.
The default OpenRouter model is anthropic/claude-sonnet-4.5. Keys, model IDs and API
base URLs are remembered separately for every provider. The API base URL field supports
regional access and coding-plan endpoints on the selected provider's domains. For Qwen
Cloud, use the URL matching your key's region and workspace from Alibaba Cloud's documentation.
2342.ai model IDs are selected from its authenticated live catalog. If a provider does
not expose a model list, enter an ID from its documentation instead. Choose a model
with tool calling; vision-capable models can also use the camera and look at the Flipper's screen.
swift test # FlipperKit and AgentKit: no device, no network
xcodegen generate
xcodebuild test -project FlipperHero.xcodeproj -scheme FlipperHero \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' CODE_SIGNING_ALLOWED=NO # app and UI tests| Layer | Tested how |
|---|---|
| FlipperKit | Against a simulated Flipper that answers real protobuf messages: framing, RPC client, file transfer, app control, screen stream, buttons, updates |
| AgentKit | Every agent tool runs once through the real executor, and a new tool without a test fails the build. Denied actions provably change nothing. Risk levels, untrusted-content fencing, permissions, firmware packages, catalogs, audit log |
| Localization | Every string catalog is checked for all 15 languages and matching placeholders |
| App | UI tests click through every screen in demo mode, including the rename limit, the YOLO confirmation and the hold-to-allow dialog |
Bluetooth itself (BLETransport) needs an iPhone and a Flipper and is tested by hand.
Demo mode. Debug builds launched with FH_DEMO=1 show sample data without a Flipper or a key.
Add FH_TAB=0..4, FH_DEMO_APPROVAL=1, FH_DEMO_YOLO=1, FH_DEMO_ACTIVITY=1,
FH_DEMO_ENGAGED=1 or -noSplash as needed. The screenshots above and docs/banner.png
(scripts/make-banner.py) come from it.
flowchart LR
UI["SwiftUI app<br/>Siri · Live Activity"] --> Agent["AgentKit<br/>agent loop · tools · risk · audit"]
Agent <--> LLM["Selected AI provider"]
Agent --> Kit["FlipperKit<br/>RPC client · device API"]
UI --> Kit
Kit <-->|"Bluetooth LE<br/>protobuf RPC"| Flipper["Flipper Zero"]
| Path | What |
|---|---|
Sources/FlipperProto |
Generated protobuf types for the Flipper RPC (scripts/gen-proto.sh) |
Sources/FlipperKit |
Framing, RPC client, device API, CoreBluetooth transport |
Sources/AgentKit |
Tools, risk model, approvals, executor, agent loop, provider APIs, catalogs |
App |
SwiftUI app, Siri and Shortcuts; project.yml generates the Xcode project |
Widgets |
Widget extension with the Live Activity |
Shared |
Live Activity types and intents compiled into both the app and the extension |
Read AGENTS.md first. It holds the parity rule (anything the UI can do, the agent can do), the safety rules that are not up for negotiation, the localization workflow, and hardware details that took time to discover. Pull requests need green tests.
Security issues go through private reporting, see SECURITY.md.
The Bluetooth layer was written against the Momentum firmware sources and the MIT-licensed Flipper iOS app, which served as a protocol reference. Protobuf definitions come from flipperzero-protobuf; only the generated Swift is in this repository.
Use FlipperHero with your own devices and with systems you are allowed to test. Engagement mode exists for authorized security work: armed sessions are logged end to end, and the report is meant to be shown to whoever authorized the engagement. What the Flipper may transmit is governed by its firmware and your local regulations; FlipperHero does not bypass either.
Flipper Zero is a trademark of Flipper Devices Inc. This project is not affiliated with them.
MIT licensed, see LICENSE.