Desktop application

Set up and run Yoqa in local mode on macOS.

macOS application

The Yoqa desktop app is the local host for Appium sessions, device browsing, apps/cases/runs, Manual Inspector, and Settings.

Install the Mac app

Download the latest Apple Silicon DMG from GitHub Releases, open it, and drag yoqa.app to /Applications.

The DMG is unsigned, so macOS Gatekeeper flags it on first launch. Recent macOS versions show “yoqa” is damaged and can’t be opened instead of the older unidentified-developer dialog. Clear the quarantine attribute before opening the app:

xattr -cr /Applications/yoqa.app
open /Applications/yoqa.app

You only need to do this once per install.

The runner is bundled inside the app, so launching yoqa.app starts the local Hono API on http://127.0.0.1:7420 automatically. You do not need a monorepo checkout.

Verify:

curl -s http://127.0.0.1:7420/health

Run from source (contributors)

If you’re hacking on Yoqa from the monorepo, start the runner and UI processes yourself:

bun run runner
bun run desktop

Keep the runner process up while you use the UI or CLI — the CLI talks to it locally.

Why local

• Your own devices — specific hardware and OS versions you care about.
• Simulator support — iOS Simulator and Android Emulator without a device farm.
• Fast iteration — watch agent steps, thoughts, and screenshots in real time.
• BYO models — your provider keys stay on your machine.

Main surfaces

Area	What it does
Apps / Cases	Catalog of apps, natural-language cases, flows, tags
Runs	Live and historical runs, cancel, thoughts, report export
Manual Inspector	Script-first explore: select elements, build a shell script, run / save
Settings → iOS toolchain	Xcode / WebDriverAgent readiness
Settings → CLI & Agents	Install yoqa CLI + yoqa-testing skill
Settings → Providers	AI providers for vision decide + grounding

CLI & skill install

Open Settings → CLI & Agents:

1. Install CLI — links yoqa into ~/.local/bin (restart the terminal afterward).
2. Install skill — copies yoqa-testing for Cursor / Claude / Codex / Standard skill dirs.
3. Verify with yoqa health and yoqa status.

See CLI and CLI for agents.

Device preparation

Xcode, adb, and WDA readiness

AI Providers

Configure vision models