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

# Desktop App

> Install the Myrm Tauri desktop client — a true Agent OS with 23+ native capabilities.

# Desktop App (Tauri)

The Tauri desktop client is more than a GUI shell — it's a true **Agent OS** with 23+ native system capabilities. All data stays on your machine, and three bundled sidecars (Python backend, Next.js frontend, Agent Runner) are packaged as standalone binaries with zero external dependencies.

## Download & Installation

The Myrm Desktop app features an intelligent cross-platform distribution system:

1. **Smart Hardware Matching**: WebGL sniffing bypasses browser limitations (like Safari spoofing Intel on M-series chips), ensuring the correct binary for your device with a single click.
2. **Race-Free Auto-Updates**: Map-Reduce CI/CD pipeline ensures reliable, silent background updates across all platforms without manifest conflicts.

Get the latest release from the [Myrm Website](https://myrmagent.ai) or [GitHub Releases](https://github.com/Pursue-LLL/myrm-agent/releases).

## Native OS Capabilities

The desktop app provides deep system integration that no browser-based AI tool can match:

### Screen & Input

* **Global Hotkeys** — Dynamically register system-wide shortcuts to toggle the window or trigger Appshot
* **Appshot** — Capture the active window screenshot + extract text via Accessibility API, all from a single hotkey
* **Clipboard Integration** — Agent can write to your real OS clipboard (not a sandbox clipboard)
* **Deep Link Protocol** — Open conversations or trigger actions via `myrmagent://` URLs (5 intent types: chat, agent, ask, oauth, install-skill)

### Power & Security

* **Smart Power Lock** — Automatically prevents system sleep while agent tasks are executing (macOS IOKit, Linux systemd-inhibit, Windows SetThreadExecutionState)
* **Screen Lock Management** — Detect lock state, unlock for Computer Use sessions, and store credentials securely in the system Keychain
* **Native Elevation** — Request admin privileges when needed (e.g., quarantine removal on macOS)
* **OTA Auto-Update** — Tauri updater with public-key safety validation to prevent supply-chain attacks

### Visual & Interaction

* **System Tray** — Dynamic tooltip status (idle/busy/error) + quick-access menu (New Chat, Settings, Workspace). Hover the tray icon to see today's token usage and cost at a glance. Budget overruns trigger native OS notifications so you never miss a spending alert
* **Taskbar Progress Bar** — When agents or background tasks are running, the taskbar/dock icon shows an indeterminate progress indicator. When a task completes while the app is minimized, the dock icon bounces to grab your attention
* **Full SubagentDashboard in Desktop** — The Tauri WebView renders the complete Next.js frontend, so every sub-agent monitoring feature (cancel, steer, Gantt, sort/filter, staleness alerts) works identically on desktop — zero extra code needed
* **Visual Approval Overlay** — OS-level transparent red frame overlay on the target monitor for tool approval, visible even when chat is covered
* **Desktop Pet Sprite** — Transparent topmost window with Canvas 2D rendering for the companion pet system
* **Close-to-Tray** — Minimize to system tray instead of quitting, with macOS ActivationPolicy management

### Startup Experience

* **Window position/size auto-restore** — Close and reopen — the window returns to its last position and size automatically, especially helpful for multi-monitor setups
* **Zero white-flash cold start** — Dark background pre-rendered so you never see a jarring white flash on startup
* **Tab route memory across restarts** — After a crash, update, or restart, the app automatically returns to the last page you were viewing (Chat/Work/Projects tabs remembered independently)

### Infrastructure

* **Python Sidecar** — Managed FastAPI backend process with health checks
* **Next.js Sidecar** — Managed standalone frontend server for WebUI mode
* **Agent Runner Sidecar** — Bun-compiled standalone binary for CLI agent integration
* **Port Conflict Detection** — Pre-launch checks to prevent port collisions
* **Out-of-the-box API alignment** — In default Desktop mode the UI talks to backend on `127.0.0.1:8080` automatically (no manual port hunting). Enable **WebUI mode** when you need remote access; the UI then reads your configured port (e.g. `25808`) from system config
* **Boot screen backend gate** — On cold start, the boot animation waits until the Python backend `/health` succeeds before entering the main UI, avoiding connection-error floods; Rust also polls health for up to 30s
* **Local dev browser parity** — When developing with `bun run dev` on `:3000`, API rewrites authenticate correctly even when the proxy connects via IPv4-mapped loopback (`::ffff:127.0.0.1` on macOS); no ConfigSync 401 on first load
* **Sidecar build CLI** — Maintainers run `./myrm desktop sidecar` to build release binaries; `./myrm desktop check-sidecar` fails on empty placeholders
* **Public Ingress** — Paste your own HTTPS tunnel URL (cpolar, NATAPP, frp, etc.); see [Tunnel Guide](/docs/guides/tunnel)
* **macOS Quarantine Fix** — Detect and auto-heal `com.apple.quarantine` attributes

## Global Screen AI (Appshot + FlowPad)

The desktop-exclusive Appshot feature lets you interact with AI without leaving your current application:

1. **Global Hotkey Capture**: Press a hotkey in any app — the system-level listener captures the active window
2. **Auto Text Extraction**: Accessibility API automatically extracts text content from the captured window
3. **Selected Text Priority Context**: Automatically captures your currently selected text (macOS via AXSelectedText, Windows via Ctrl+C clipboard) — the selection is injected as the highest-priority context for AI, displayed prominently as a Context Chip in FlowPad — AI precisely understands what you're focused on
4. **FlowPad Floating Panel**: An AI query panel appears after capture — type your question and send it to the conversation
5. **Quick Actions**: One-click preset buttons (Reply / Summarize / Translate / Explain) appear after capture — zero typing required for common tasks
6. **Multi-Capture Stacking**: Capture up to 10 windows in sequence and send them all to AI for analysis
7. **Image Preview & Management**: Preview captured images in FlowPad, delete individual captures, or click to enlarge
8. **Privacy Blacklist**: Protect sensitive apps (1Password, banking apps, etc.) — captures are blocked with a warning toast and optional "Capture Anyway" override
9. **Inline Input Mode (Option+I)**: A global shortcut triggers capture and enters Inline mode — AI results stream in real-time within FlowPad, then one-click Paste writes the result back to the original app and the window auto-hides — never leave your workflow
10. **Inline Agent Switcher + Profile Routing**: In Inline mode, you can switch the target Agent profile per message (for example Writer/Coder) without changing the main chat session's Agent configuration

Typical use cases: select a code snippet and press hotkey for AI to explain the selection, capture an email and click "Reply" for AI-drafted response, screenshot a foreign article and click "Translate", capture error logs and click "Explain" for diagnosis, press Option+I while writing a doc and Paste the AI result directly into your editor.

## Setup

1. Install the application for your platform
2. Launch Myrm from your applications menu
3. Configure at least one LLM API key in Settings

## macOS System Permissions (Computer Use)

Desktop automation (Computer Use) requires two macOS permissions: **Accessibility** and **Screen Recording**. Myrm automatically detects and guides you through the process:

* **Proactive Detection** — When you enable `computer_use` in an Agent's tool settings, a status card instantly shows which permissions are granted (green) or missing (amber)
* **One-Click Deep Link** — Click "Open System Settings" to jump directly to the correct macOS Privacy panel
* **Recheck Button** — After granting access in System Settings, click "Recheck" to verify instantly without restarting
* **Runtime Banner** — If permissions are revoked while using Desktop Inspector, a contextual banner appears with guidance

### Desktop Inspector: Numbered Overlay (SOM)

When you refresh the Desktop Inspector panel, Myrm overlays **numbered badges \[N]** on interactive controls in the live screenshot. The same indices appear in the accessibility tree and in approval cards — so you always know **which element** the agent is about to click.

* **Token-safe default** — Agent tool calls keep `include_screenshot=false` unless you need a visual turn; SOM runs on Inspector refresh and explicit screenshot requests only
* **Semantic-first** — `@dref` references remain the primary control path; numbers are a human-readable translation layer, not a replacement
* **Filtered labels** — Static text and non-interactive nodes are excluded so the overlay stays readable

<Note>
  **Deploy-aware behavior:** On **local/Tauri/WebUI local**, Computer Use controls your real Mac/PC/Linux desktop. On **SaaS sandbox**, it only mounts when the sandbox runs a **Visual Desktop** (noVNC) **and** your plan includes the VNC entitlement—headless sandboxes keep the toggle off so marketing matches reality.
</Note>

<Note>
  Screen Recording permission may require an app restart to take effect. Accessibility permission typically works immediately after granting.
</Note>

## Permission System

The desktop app enforces a three-tier permission model for agent actions:

| Mode        | Behavior                                                      |
| ----------- | ------------------------------------------------------------- |
| **Explore** | Agent can only read files and browse — no modifications       |
| **Ask**     | Agent requests approval before any write or system operation  |
| **Auto**    | Agent executes all approved tool categories without prompting |

## Remote Access

Enable remote access with your own tunnel tool, then control running agents from your phone:

1. Go to **Settings → System → Access**
2. Enable **WebUI mode** and **password protection**
3. Start a tunnel (Cloudflare Tunnel, cpolar, NATAPP, frp, etc.) against port `3000`
4. Paste the **HTTPS** URL into **Public Ingress** and run **Test connectivity**
5. Scan the **Mobile Hub QR** on your phone — pick an active session to open the **Status Board** (live progress, approvals, steer, **stop with confirmation toast**, **Browser/Desktop Live Preview** — real-time agent screen snapshots with Lightbox zoom and tab switching)

Pair tokens are scoped: the Hub list token cannot control chats until you open a session; control tokens bind to one `chat_id`. See [Tunnel Guide](/docs/guides/tunnel) for detailed configuration.

**Honest note:** You bring the tunnel; Myrm does not host your traffic. End-to-end encrypted relay (G2) is on the roadmap — today, security relies on HTTPS + scoped pair tokens + session binding.