---
description: Run and test the macOS desktop app locally
---

## Test Desktop App (macOS)

### Prerequisites

- Backend running on port 8000 (`./run-local-all-services.sh start`)
- Python 3.12+ with venv
- Azure Speech SDK credentials in `~/.LysnrAI/.env`

---

### Step 1 — Set up environment

```bash
python3 -m venv .venv 2>/dev/null  # create venv if it doesn't exist
source .venv/bin/activate
pip install -e ".[dev]" --quiet
```

### Step 2 — Run automated quality checks

// turbo

```bash
source .venv/bin/activate && python -m ruff check src/ --select E,F,W --no-fix 2>&1 | tail -10
```

```bash
source .venv/bin/activate && python -m pytest tests/ -v --tb=short -q 2>&1 | tail -20
```

### Step 3 — Verify env file exists

// turbo

```bash
ls ~/.LysnrAI/.env && echo "OK: env file found" || echo "ERROR: create ~/.LysnrAI/.env with Azure credentials"
```

### Step 4 — Run the desktop app

```bash
source .venv/bin/activate && python3 -m src.main
```

### Step 5 — Manual verification

- **App window**: Appears with LysnrAI branding
- **System tray**: Menu bar icon shows
- **License activation**: Enter a valid LYSNR-XXXX-XXXX-XXXX key
- **Dictation**: Hold Fn (Globe key), speak, release → text should paste into active app
- **History**: Cmd+Shift+H shows dictation history
- **Error handling**: Unplug mic → should show graceful error, not crash

### Key Files

| File                              | Purpose                                       |
| --------------------------------- | --------------------------------------------- |
| `src/main.py`                     | App entry point, LysnrEngine, license restore |
| `src/licensing/license_client.py` | License activation via backend API            |
| `src/hotkey/fn_listener.py`       | macOS Fn/Globe key listener                   |
| `src/cloud/`                      | Azure Speech SDK integration                  |
| `src/audio/`                      | Audio recording + processing                  |
| `src/paste/`                      | Clipboard paste into active app               |

### Important Notes

- macOS: Set System Settings → Keyboard → Press Globe key → "Do Nothing"
- Corporate proxy: Backend must be started with proxy bypass (run-local script handles this)
- The app connects to `http://localhost:8000/api` for license activation
