> ## Documentation Index
> Fetch the complete documentation index at: https://yoqa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/Aris-ngoy/qa-agent/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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/docs/cli) and [CLI for agents](/guide/cli-for-agents).

<CardGroup cols={2}>
  <Card title="Device preparation" icon="mobile" href="/docs/device-preparation">
    Xcode, adb, and WDA readiness
  </Card>

  <Card title="AI Providers" icon="key" href="/docs/providers">
    Configure vision models
  </Card>
</CardGroup>