flowbaton

module

v0.2.0-beta.2 Latest Latest Go to latest Published: Sep 4, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/larchwave/flowbaton

Links

Open Source Insights

README ¶

FlowBaton

Mobile UI automation for Android and iOS. One Go binary: CLI, MCP, and optional explore with your own key. No telemetry.

A hand holding a written flow passes a baton to a robotic arm reaching out of a phone screen, which taps another device

The usual way to drive a device is a YAML flow:

appId: com.example.app
---
- launchApp
- tapOn: "Log in"
- inputText: "demo@example.com"
- tapOn: "Continue"
- assertVisible: "Welcome back"

flowbaton test -p ios --device <simulator-udid> login.yaml

The same file is valid on Android. Unsupported commands fail in preflight, before the device is touched.

Install

brew tap larchwave/flowbaton
brew trust larchwave/flowbaton
brew install flowbaton

brew trust is required for third-party casks on current Homebrew.

Go, archives, and Windows

From source. A source build reports its version as dev:

go install github.com/larchwave/flowbaton/cmd/flowbaton@latest

Archives for macOS, Linux, and Windows are on the releases page. Each archive ships SLSA provenance:

gh attestation verify flowbaton_*_darwin_arm64.tar.gz --repo larchwave/flowbaton

On Windows, download flowbaton_<version>_windows_amd64.zip, extract it, and put that folder on PATH.

Quick start

Parse a flow with no device attached:

printf 'appId: com.example.app\n---\n- tapOn: "Continue"\n' | flowbaton check-syntax -

Prepare a driver once, then run flows:

flowbaton driver-setup -p android
flowbaton test -p android --device emulator-5554 path/to/flow.yaml

iOS Simulator

Needs Xcode and an installed Simulator runtime.

flowbaton driver-setup -p ios
flowbaton test -p ios --device <simulator-udid> path/to/flow.yaml

A booted Simulator's UDID: xcrun simctl list devices booted.

Physical iPhone or iPad (iOS 17+)

The hardware driver is in this tree and still hardening. Build the device runner once (Xcode, signed-in Apple ID; a free account works, with 7-day profiles), then run over USB. No sudo.

export FLOWBATON_IOS_TEAM=<your team id>   # Xcode > Settings > Accounts
scripts/build-ios-device-runner.sh
flowbaton test -p ios --device <device-udid> path/to/flow.yaml

flowbaton list-devices -p ios lists attached hardware next to Simulators. -p ios picks the driver from the UDID.

clearKeychain and addMedia are unsupported on hardware (Apple). They fail before mutation. Details in the support matrix.

Sample flows against stock Android Settings, nothing to build: flowbaton-samples.

A FlowBaton flow driving the Android Settings app on an emulator
_{One of those samples, captured with flowbaton record.}

Explore

With a provider key, explore drives the app:

export OPENAI_API_KEY=...   # or ANTHROPIC_API_KEY with FLOWBATON_AI_PROVIDER=anthropic
flowbaton explore --app com.example.app -p ios --device <simulator-udid>

It maps screens, plans scenarios, taps through them on the device, writes a report, and exports every passing run as flow YAML. Without a key, explore refuses to start.

--max-tests and --max-steps cap a session. --pilot adds a supervisor model. --record adds video. Per-app memory keeps screen maps, plans, and operator hints for the next session.

MCP

flowbaton mcp

Point an agent's MCP config at that command. Tools: check_syntax, list_devices, start_device, hierarchy, query, run_flow, screenshot, explore. AGENTS.md is the short tour for agents.

Serve

flowbaton serve runs the same flows as a multi-node runtime. PostgreSQL holds leases, tokens, and work claims. Device sessions survive reconnects and cancel cleanly.

flowbaton db apply-schema --database-url "$FLOWBATON_DATABASE_URL"

A node then serves Integration v1 and DeviceSession v1 over mutual TLS. Flags, certificates, and inventory: Remote DeviceSession runtime.

Flow commands

Group	Commands
App	`launchApp` `stopApp` `killApp` `clearState` `clearKeychain` `setPermissions`
Touch	`tapOn` `doubleTapOn` `longPressOn` `swipe` `scroll` `scrollUntilVisible` `back` `pressKey` `waitForAnimationToEnd`
Text	`inputText` `eraseText` `pasteText` `hideKeyboard` `copyTextFrom` `setClipboard`
Random text	`inputRandomText` `inputRandomNumber` `inputRandomEmail` `inputRandomPersonName` `inputRandomCityName` `inputRandomCountryName` `inputRandomColorName`
Assertions	`assertVisible` `assertNotVisible` `assertTrue` `assertScreenshot`
AI assertions	`assertWithAI` `assertNoDefectsWithAI` `extractTextWithAI`
Device	`setLocation` `travel` `setOrientation` `setAirplaneMode` `toggleAirplaneMode` `openLink` `openBrowser` `addMedia`
Capture	`takeScreenshot` `startRecording` `stopRecording`
Control	`runFlow` `repeat` `retry` `extendedWaitUntil` `action`
Scripting	`runScript` `evalScript`

Text typed into a secure field is exported as a ${FLOWBATON_…SECRET…} placeholder. The engine fails the flow when that variable is unset, and keeps the placeholder, never the resolved value, in recordings, artifacts, and replays.

CLI

Command	What it does
`check-syntax`	Parse a flow and print source diagnostics. No device.
`test`	Run flows on a device, emulator, or Simulator.
`record`	Run one flow and render a video of it.
`explore`	Autonomous AI session; exports passing runs as YAML.
`list-devices`	Inventory devices and Simulators. Reads only.
`start-device`	Boot an emulator or Simulator, optionally creating it.
`hierarchy`	Dump what is on screen. Taps nothing.
`query`	Match a selector against the live screen.
`bugreport`	Collect a device diagnostic bundle.
`driver-setup`	Install the signed, version-matched platform driver.
`mcp`	Serve the MCP tool surface over stdio.
`serve`	Multi-node DeviceSession runtime (PostgreSQL).
`db`	Apply the `serve` runtime schema.
`auth`	Keys and certificate mapping for `serve`.
`generate-completion`	bash or zsh completion script.

flowbaton with no arguments prints the command summary.

Platforms

Host	Android	iOS Simulator	iOS device (17+)
macOS arm64 / amd64	works	works	in tree, hardening
Linux amd64	works	unavailable	hardening¹
Windows amd64	pre-alpha²	unavailable	hardening¹

¹ Needs usbmuxd (macOS ships it). The device runner is built once on macOS with Xcode; an already-built runner can run from any host. ² Flow parsing and syntax checks work. Android execution has not passed the release gates.

Full detail: support matrix.

Status

FlowBaton is pre-alpha. Android devices, emulators, and iOS Simulators work today. Physical iOS, explore, and serve are in this tree and still hardening.

The Homebrew bottle is v0.1.1. Until the next tag, explore, the start_device / run_flow / screenshot MCP tools, and the physical-iOS driver need a source build (go install above).

Beta readiness tracks candidate fixes, validation, and the remaining publication gates. No beta has been published yet.

Command surface and contracts are versioned. Breaking changes are likely before 1.0.

Documentation


Roadmap	v1 target and what is still open
Support matrix	What runs where
Remote DeviceSession runtime	`flowbaton serve`
Release policy	Versioning and release gates
Dependency policy	What may enter the build
Security policy	Reporting a vulnerability
Contributing	Build from source, platform checks
Agent guide	CLI and flow shape for coding agents

Machine-readable contracts live in contracts/. Product behavior is specified in specs/.

Questions: Discussions. Bugs: issues.

License

Apache License 2.0. Third-party components: THIRD_PARTY_NOTICES.md.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
flowbaton command
contracts
device-session/v1 Package devicesessionv1 implements the normative semantic checks that JSON Schema cannot express across authenticated context, lease fencing, and time.	Package devicesessionv1 implements the normative semantic checks that JSON Schema cannot express across authenticated context, lease fencing, and time.
integration/v1 Package integrationv1 implements the normative cross-field checks for the public FlowBaton Integration v1 handshake.	Package integrationv1 implements the normative cross-field checks for the public FlowBaton Integration v1 handshake.
internal
aiengine Package aiengine implements engine.AIPredictionEngine on top of langchaingo's provider-agnostic llms.Model.	Package aiengine implements engine.AIPredictionEngine on top of langchaingo's provider-agnostic llms.Model.
android
android/grpcwire Package grpcwire is a minimal gRPC-over-h2c client for the Android agent.	Package grpcwire is a minimal gRPC-over-h2c client for the Android agent.
android/pbwire Package pbwire is a hand-rolled proto3 codec for exactly the messages of proto/flowbaton_android.proto.	Package pbwire is a hand-rolled proto3 codec for exactly the messages of proto/flowbaton_android.proto.
assets The fixtures in this package are representative, non-installable payloads.	The fixtures in this package are representative, non-installable payloads.
auth Package auth issues and verifies FlowBaton's channel-bound Ed25519 session tokens.	Package auth issues and verifies FlowBaton's channel-bound Ed25519 session tokens.
capability Package capability owns FlowBaton's executable support classifications and graph-wide fail-closed analysis.	Package capability owns FlowBaton's executable support classifications and graph-wide fail-closed analysis.
capability/cmd/export-registry command
cli Package cli contains side-effect-free command orchestration for FlowBaton.	Package cli contains side-effect-free command orchestration for FlowBaton.
device Package device defines the platform-neutral device contract.	Package device defines the platform-neutral device contract.
drivercontract Package drivercontract owns the immutable, side-effect-free capability documents shared by selected-platform preflight and production drivers.	Package drivercontract owns the immutable, side-effect-free capability documents shared by selected-platform preflight and production drivers.
engine Package engine owns the deterministic host execution foundation.	Package engine owns the deterministic host execution foundation.
enginetest Package enginetest provides deterministic host-side test doubles for the execution engine and other callers of the frozen device contract.	Package enginetest provides deterministic host-side test doubles for the execution engine and other callers of the frozen device contract.
explore Package explore implements autonomous AI-driven exploratory testing of mobile applications on top of the platform-neutral device driver surface.	Package explore implements autonomous AI-driven exploratory testing of mobile applications on top of the platform-neutral device driver surface.
explore/export Package export turns finished exploration runs into runnable two-document flow YAML, validated through the flow parser before it is returned.	Package export turns finished exploration runs into runnable two-document flow YAML, validated through the flow parser before it is returned.
explore/memory Package memory implements the filesystem stores of the per-app explore state directory: learned per-screen recipes, operator-authored hints, saved plans, and cached research maps.	Package memory implements the filesystem stores of the per-app explore state directory: learned per-screen recipes, operator-authored hints, saved plans, and cached research maps.
explore/planning Package planning turns researched UI maps into prioritized, deduplicated test scenarios through one model conversation per iteration.	Package planning turns researched UI maps into prioritized, deduplicated test scenarios through one model conversation per iteration.
explore/report Package report renders a finished exploration session into a markdown summary and aggregates token spend across the session.	Package report renders a finished exploration session into a markdown summary and aggregates token spend across the session.
explore/research Package research implements the Observer and Researcher exploration roles: capturing one settled screen of the app through the device driver and turning that capture into a validated UI map for planning and testing conversations.	Package research implements the Observer and Researcher exploration roles: capturing one settled screen of the app through the device driver and turning that capture into a validated UI map for planning and testing conversations.
explore/run Package run implements the execution roles of exploration mode: the Tester tool loop, the Pilot supervisor conversation, and the Navigator that brings the app to a usable screen.	Package run implements the execution roles of exploration mode: the Tester tool loop, the Pilot supervisor conversation, and the Navigator that brings the app to a usable screen.
flow Package flow parses FlowBaton's isolated YAML contracts into model nodes.	Package flow parses FlowBaton's isolated YAML contracts into model nodes.
hierarchy Package hierarchy provides platform-neutral geometry and normalized tree helpers over the frozen device DTOs.	Package hierarchy provides platform-neutral geometry and normalized tree helpers over the frozen device DTOs.
imagecheck Package imagecheck provides deterministic, host-side encoded image inspection without external dependencies.	Package imagecheck provides deterministic, host-side encoded image inspection without external dependencies.
ios Package ios is the host-side client for the iOS XCTest runner's HTTP API.	Package ios is the host-side client for the iOS XCTest runner's HTTP API.
iosdevice Package iosdevice owns the physical-iOS half of the driver surface: every import of go-ios lives here, so the usbmuxd/tunnel dependency has exactly one boundary package.	Package iosdevice owns the physical-iOS half of the driver surface: every import of go-ios lives here, so the usbmuxd/tunnel dependency has exactly one boundary package.
js
matching Package matching implements exact platform-neutral selector matching over a normalized hierarchy.	Package matching implements exact platform-neutral selector matching over a normalized hierarchy.
model Package model defines FlowBaton's versioned, device-independent flow contract.	Package model defines FlowBaton's versioned, device-independent flow contract.
report
server Package server exposes the authenticated Integration and DeviceSession v1 runtime.	Package server exposes the authenticated Integration and DeviceSession v1 runtime.
sessionstore Package sessionstore persists the fenced DeviceSession state machine.	Package sessionstore persists the fenced DeviceSession state machine.
strictjson Package strictjson decodes untrusted JSON without accepting ambiguous duplicate object keys, unknown fields, or trailing values.	Package strictjson decodes untrusted JSON without accepting ambiguous duplicate object keys, unknown fields, or trailing values.
transport Package transport contains authenticated transport identity primitives.	Package transport contains authenticated transport identity primitives.
version Package version owns the host binary's release version string.	Package version owns the host binary's release version string.
web Package web is the Chrome DevTools Protocol execution surface.	Package web is the Chrome DevTools Protocol execution surface.
workspace Package workspace turns operator input — files, directories, CLI tag filters — into the ordered set of flows a run will execute.	Package workspace turns operator input — files, directories, CLI tag filters — into the ordered set of flows a run will execute.