V3SP3R

V3SP3R is an AI-driven controller for the Flipper Zero, packaged as an Android app.

V3SP3R turns the Flipper into something you talk to instead of something you click through: the phone runs a Bluetooth link to the Flipper, a large language model (reached through OpenRouter) plans the actions, and a strict on-device chokepoint decides whether each proposed action actually runs. Voice, chat, camera, and smart-glasses inputs all feed the same command loop.

See the upstream project at https://github.com/elder-plinius/V3SP3R

What V3SP3R is (and isn't)

What it is:

• An Android app (Kotlin, Jetpack Compose) that pairs to a Flipper Zero over BLE and drives the Flipper's stock Serial Service using its own flipper-protobuf RPC, with a text CLI fallback for older firmwares.
• An LLM-planned agent loop: the model emits a single tightly-typed execute_command tool call per turn, the phone classifies risk locally, and the user approves anything above LOW risk before the Kotlin side actually touches the Flipper.
• A multimodal front end: on-device speech recognition, photos preprocessed to text by a cheap vision model, optional TTS, and an optional bridge to Mentra smart glasses so the same command loop runs eyes-free.
• A collection of "labs" over the same execution substrate: an Ops Center for diagnostics and firmware compatibility, an Alchemy Lab for custom SubGHz signal synthesis, a Payload Lab for AI-generated BadUSB/IR/RF payloads, and a FapHub app browser.

What it is not:

• An autonomous exploit tool. The design principle baked into the system prompt (VesperPrompts.SYSTEM_PROMPT) is "You issue commands; Android enforces security." The model never touches BLE, the filesystem, or raw device primitives directly, and it cannot self-classify risk out of a restriction.
• A cloud service. All BLE traffic, raw Flipper responses, risk classification, permission decisions, approval UI state, and the audit log stay on the phone. Only the trimmed conversation, tool schema, and shaped CommandResult JSON go over the wire to OpenRouter.
• A general-purpose Flipper client. It's an agent-first controller. If you want a menu-driven mobile client, the official Flipper Mobile app is the right tool. V3SP3R is what you reach for when you want to describe what you want and have the model plan the file reads, edits, and transmissions to get there.

Hardware and account requirements:

• A Flipper Zero (any of the standard, black, or transparent case variants).
• An Android 8.0+ phone with Bluetooth. USB CDC-ACM is also supported as an alternate transport over the same protocol.
• An OpenRouter API key. Model selection is user-configurable; the tool-calling loop has been tested against Hermes 4, Claude Sonnet, and other tool-capable models on the OpenRouter catalog.
• Optional: Mentra-compatible smart glasses for the eyes-free path, and an ElevenLabs key if you want cloud TTS instead of Android's on-device voice.

Topics

Each topic below has its own sub-page.

Architecture

V3SP3R/Architecture

The overall system design and, in particular, the data-flow boundary between what stays on the phone and what gets sent to the AI. Covers the three-layer cloud/Android/Flipper split, the single execute_command funnel, the on-device RiskAssessor and PermissionService, the multimodal-to-text preprocessing trick that keeps sensitive image bytes off the primary reasoning model, and the justification + expected_effect fields on every command envelope. Ends with a checklist of design patterns worth copying if you want to build something similar for other hardware.

Phone-to-Flipper Control Interface

V3SP3R/Phone-to-Flipper Control Interface

The lower-half companion to the architecture page: how the Android app actually drives the Flipper. Covers the BLE GATT connection to Flipper's Serial Service (TX/RX/overflow/reset characteristics), the length-prefixed Flipper.Main protobuf framing over that virtual serial link, the RPC subsystems V3SP3R uses (PBStorage, PBSystem, Application, Gui, Desktop), the automatic fallback to Flipper's text CLI when RPC is unavailable, and the four-layer Kotlin stack (CommandExecutor → FlipperFileSystem → FlipperProtocol → FlipperBleService) sitting above the wire. Ends with the abstractions that transfer cleanly to other hardware targets.

The execute_command Envelope

V3SP3R/execute_command Envelope

Field-by-field reference for the JSON contract that every AI-issued action passes through.

Covers action, args, justification, and expected_effect, the enum of ~30 allowed actions, why V3SP3R uses one narrow funnel instead of many provider-side tools, the "max 1 command per response" and "read-verify-write" disciplines baked into VesperPrompts, and the local rate limit (30 req/min) and single-tool-call cap per response. Referenced by nearly every other page.

Audit Log and Session Replay

V3SP3R/Audit Log and Session Replay

The trust story for anyone considering the app for real ops work.

Covers the Room schema (VesperDatabase, ChatDao, AuditService), what gets written to disk before execution (the justification and expected effect) vs. after (the actual CommandResult), how sessions can be replayed offline, and how the audit trail interacts with the diff view and approval UI.

Payload Synthesis - Payload Lab, Alchemy Lab, Forge

V3SP3R/Payload Synthesis

How V3SP3R generates .sub, .ir, and BadUSB .txt files from a natural-language description instead of only replaying stored ones.

Covers which file formats have templates in VesperPrompts, what the model is allowed to fill in versus what the phone constrains (frequency ranges, protocol enums, RAW_Data legality), how ForgeEngine handles RF signal synthesis locally, and how a freshly synthesized payload flows through the same execute_command funnel and risk gates as a stored file.

Compatibility Probing (Ops Center)

V3SP3R/Compatibility Probing

How V3SP3R figures out what the attached Flipper actually supports and adapts to it.

Covers the on-connect probes (which RPC subsystems answer, which CLI commands parse, whether the firmware is stock or a variant like RogueMaster/Xtreme/Momentum, whether subghz tx accepts arbitrary frequencies, whether BadUSB is present, whether the Marauder ESP32 module is attached), the cached FirmwareCompatibilityProfile / CliCapabilityStatus, how the Ops Center surfaces this to the user, and how higher layers and the system prompt branch on the profile. The pattern generalizes to any agent talking to devices with varied firmwares.

MarauderBridge and WiFi Ops

V3SP3R/MarauderBridge and WiFi Ops

The state of ESP32 Marauder support - which, as of this writing, is scaffolding, not a wired-up feature. The MarauderBridge class exists in ble/ and implements a standalone BLE client for a separate ESP32 running Marauder firmware (WiFi scanning, deauth, beacon spam, Evil Portal, sniffing). But nothing in the app constructs it, no viewmodel or screen consumes its flows, and the execute_command enum has no Marauder-shaped actions. Sub-page covers what the class does, what it isn't yet connected to, why "Marauder over Flipper CLI" is a mischaracterization (it's a direct phone→ESP32 BLE link, not routed through the Flipper), how ble_spam is a different thing (that is wired up), and a recommended hookup path.

Prompt Engineering

V3SP3R/Prompt Engineering

Walk-through of the ~300-line system prompt that teaches the model how to be a V3SP3R agent.

Covers how the prompt encodes the Flipper path structure (/int, /ext/subghz, /ext/nfc, etc.), the file-format templates for SubGHz/IR/BadUSB, the risk-tier and safety boundaries the model is expected to respect, the required execute_command JSON envelope, and the SMARTGLASSES_ADDENDUM appended when the glasses bridge is active. The prompt is a significant piece of the design and worth reading on its own.

At a glance

Aspect	V3SP3R
Upstream	github.com/elder-plinius/V3SP3R
Author	elder-plinius (Pliny)
Target hardware	Flipper Zero (all case variants)
Host platform	Android 8.0+ (Kotlin, Jetpack Compose)
Phone-to-Flipper transport	BLE GATT (primary), USB CDC-ACM (alternate)
Phone-to-Flipper protocol	Flipper protobuf RPC, with text CLI fallback
LLM provider	OpenRouter (user-supplied key, user-selected model)
Vision handling	Preprocessed to text by a cheap vision model; primary reasoner sees text only
Input modalities	Voice (on-device STT), text chat, photos, Mentra smart glasses
Output modalities	Text, Android TTS, optional ElevenLabs TTS, glasses HUD