​

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 or GitHub 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 dedicated myrmagent:// URLs (5 intent types: chat, agent, ask, oauth, install-skill), backed by a single-instance mutex that forwards hot-start parameters to the active window, eliminating scheme collisions and filtering out invalid path injections.

​

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 & Handoff Feedback — Tauri updater with public-key safety validation to prevent supply-chain attacks, paired with cold-boot handoff verification for instant update feedback and automatic rollback protection

​

Visual & Interaction

• System Tray & Dual-Layer Version Transparency — Displays both Desktop Shell: v1.0.0 and Engine Sidecar: v0.1.0 in the tray menu and WebUI About panel, eliminating version ambiguity across mixed environments; includes one-click diagnostic report export; native Rust tray supports in-place text updates and real-time upgrade progress delivery, paired with macOS monochrome template icons and Windows high-DPI icons.
• 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

• Single-instance mutex & second-launch focus — Native Rust process lock (< 15ms response) completely eliminates multi-instance Sidecar port conflicts; second launch automatically unminimizes, shows, and focuses the existing main window and hands deep links of the second launch (Windows/Linux) to the running instance
• 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
• Windows Process Tree Recursive Termination — Eliminates Windows survivor process file locking during OTA updates
• Survivor Diagnosis & Port Self-Healing — Automatically identifies old Myrm instances on port conflict, triggers intelligent Re-kill, and backs off until port is completely free
• 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
• 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, the status strip shows four honest states: verified (capture works), unverified (grants OK — not probed yet), capture unavailable (grants look OK but a live frame failed), or missing grants
• Granted ≠ Capturable — A green System Settings toggle is not enough; Recheck runs an on-demand capture probe so you do not start desktop tasks on a false-green
• One-Click Deep Link — Click “Open System Settings” to jump directly to the correct macOS Privacy panel
• Recheck Button — After granting access (or fixing a stale grant), 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

​

Target Window Auto-Heal & Restore (Zero-Token Architecture)

When operating target applications (such as Calculator, Excel, or WeChat), even if the window is minimized or suspended in the background:

• Transparent Awakening: The underlying SDC engine automatically perceives WindowVisualState.Minimized, negative coordinate bounding boxes (Windows), or AXMinimized attributes (macOS), atomically unminimizing and restoring the window.
• Rendering Settle Guard: Automatically waits 50ms for the XAML/Win32/Cocoa UI hierarchy to instantiate, completely eliminating empty tree crashes.
• Zero Token Overhead: Eliminates extra application management tools, saving 4,000+ tokens per session and preventing model confusion.

​

Permission System

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

​

Remote Connections

One desktop drives all your machines — your own computer, a self-hosted server (VPS, NAS, home server), or cloud hosting. Switch between them anytime. The first time you open Settings → System → Server Connection, the app asks where your assistant runs: this computer, a remote server, or cloud hosting. You can change this there at any time.

​

Remote server profiles

1. Go to Settings → System → Server Connection
2. Toggle from Local to Remote
3. Give the connection a name (e.g., Homelab), enter the server URL, and click Test Connection
4. Click Connect — the app reloads and all API calls now route to that server
5. Log in with your remote server credentials (Setup Token + password)

You can save multiple servers and switch between them with one click. Each entry has its own health check; if a server becomes unreachable, an inline alert offers a one-click Switch to Local Mode button. Dead servers are blocked before you switch — and if a connection drops right after switching, the app automatically returns to your last working connection. Your local auth token is backed up automatically and restored when you disconnect. While a switch is in progress, other connection controls are locked, and if you decline the running-session confirmation they unlock again — so double clicks or a second click on another server can never start two switches. While connected remotely, the local backend stays off to save ports, CPU, and battery — it restarts automatically when you switch back.

​

Cloud hosting

Prefer not to run a server yourself? In the same settings card, under Cloud hosting:

1. Enter your cloud address and click Check sign-in options
2. Sign in with your cloud account in the browser, then click Open in desktop app to hand the session back
3. Or, if you are already signed in, click Discover my sandbox — your hosted sandbox is added as a connection automatically

​

Good to know

• NavBar plug icon — visible while connected remotely; click to jump to connection settings.
• Scheduled tasks keep running on the remote server or cloud sandbox even when this desktop is offline or closed.
• Capabilities always come from the connected server — the desktop is a window into it, not a second copy of it.

​

Stack Update Panel

Settings → System → About hosts the update truth table: desktop updater state, server/engine versions with stale badges, cloud sandbox version (unknown until the control-plane contract lands), and FIXED / Other changelog groups with expand-all.

• Defer + quiet hours — postpone a version or silence nudges overnight; security updates cannot be deferred.
• EmptyChat nudge — when the stack falls behind, a banner links straight to the panel.
• Update checkup — one click verifies the release feed is reachable.

​

Pre-Update Snapshots

Before desktop updates, the app can snapshot your workspace automatically (enable it once in the Stack Update Panel): the local database plus session checkpoints, labeled pre-update:{from}->{to}, keeping the last five. If an update breaks your data, Doctor → Restore brings both back, then restart the app to apply. Vector indexes are excluded (rebuilt automatically).

​

Manual recovery (if the app cannot start)

Snapshots live under <data-dir>/snapshots/<snapshot-id>/ (~/.myrm by default), each holding data.db, checkpoints.db, and meta.json. After reinstalling: stop the app, copy both .db files back into the data directory, and restart.

​

Resource Pressure Banner

When memory runs critical or the data disk fills up, a banner appears in chat with the worst problem first (a full disk outranks everything — silent write failures are worse than a restart). Dismissals last for the session; any escalation re-opens immediately. Heavy scheduled tasks automatically defer while pressure is critical and resume after.

​

Trust Badge & Crash Recovery

Open Settings → System → About:

• Trust badge — shows whether this build’s updater signature verified cleanly (signed / dev build / unofficial / unknown). Unknown means unknown — the app never claims “safe” when it cannot verify.
• Recovery guide — if the backend stops or crashes, you get the failure reason plus a one-click retry; your chats and data are never touched by the retry. While following a remote server, the retry politely stands down instead of restarting the wrong backend.

​

Remote Access (Mobile Hub)

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)

​

Remote Spawn

Create new tasks directly from your phone without returning to the desktop:

1. Open the Mobile Hub and tap New Remote Task
2. Select an Agent and optionally a Project from the dropdowns
3. Type your task message and tap Send
4. The agent starts immediately — you are redirected to the Status Board to monitor progress

The backend issues a scoped pair token for the new session and rate-limits spawns to 30/min. Your initial message is delivered via autoStart (sessionStorage) so the agent begins working the moment the Status Board loads.

​

Mobile Artifact Delivery

When the agent finishes, generated files (documents, code, HTML pages, images, etc.) are displayed directly on your phone as Artifact cards in the Status Board:

• Icon + filename + type + size at a glance
• Tap the preview button to open the file in a new browser tab
• Tap the download button to save it locally

All 16 artifact types are supported. No backend changes are needed — the data is already present in the message stream. This means you can review, approve, or request changes to AI deliverables from your phone — no need to “go back to the desk.” 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 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.

​

What You See While Your Agent Works

A desktop agent that is busy should never look idle — and it should never look busy when it is not. Three things are guaranteed on your screen:

• You can see the work, not just the result. A horizontal swimlane strip for concurrently running subagents sits right in the chat (myrm-agent-frontend/src/components/features/chat-window/in-flight-steer/ActiveSubagentSwimlanesBar.tsx, mounted by ChatWindowSatellites.tsx:37), so you can steer a running subagent instead of guessing what it is doing. In the sidebar, pinned conversations are drag-sortable and time groups are collapsible — the conversations you care about stay one drag away.
• Your credentials stay in their lane. Anything the agent runs in a terminal starts from a deliberately narrow environment: credential-bearing variables are not inherited, so a login token cannot drift out of the app and into a shell that happens to record it.
• Desktop-only behaviour stays on the desktop. Desktop control instructions are injected only when desktop control is actually part of the task, so your agent behaves identically in the browser, in a scheduled job, and in a channel chat.