You are reading Nightly documentation for 0.12.6.dev0+g563af09.

This documentation may describe behavior that differs from Stable.

Open Stable documentation

Documentation version

0.12.6.dev0+g563af09 · Nightly
Stable Beta Nightly

Desktop App

Desktop App

The desktop app wraps the local host in a native window with a system tray, native menus, OS notifications, and an auto-updater. It is the same web interface you would see in a browser — including all its screen-reader support — in a window that manages the agent's lifecycle for you.

Download and install

Download the installer for your platform from the project's GitHub Releases page (Windows NSIS/MSI, macOS app/dmg, Linux deb/AppImage). The app bundles the full agent host — no separate Python install is needed. It uses the platform's native webview (WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux) rather than shipping a browser engine. See Installation for the other install methods.

Attach or spawn

On startup the app probes http://127.0.0.1:8765 for a running Holaryn host:

  • A host is already running (an installed service, or holaryn serve in a terminal) — the app attaches as a viewer. It opens a window onto that host, and quitting the app leaves the host running, since the app did not start it.
  • Nothing is running — the app starts its bundled host itself, waits for it to be ready, and owns its lifecycle: quitting the app stops the agent.

So launching the app next to a running service is always safe — you get a window onto the existing agent, never a collision.

System tray, and what "close" means

The app lives in the system tray (tooltip "Holaryn Agent") and distinguishes hiding the window from stopping the agent:

  • Closing the window hides it to the tray — the agent keeps running. Bring it back by left-clicking the tray icon or choosing Show/Hide window from the tray menu.
  • Quit is the only thing that stops the agent (when the app owns the host). Quit from the tray menu, the app menu, or Ctrl+Q.
  • The tray menu also offers Open in browser (opens the UI in your default browser, without signing you in; see Links and email) and Check for updates….
  • Reaching the tray menu from the keyboard: on Windows press Win+B, move to the Holaryn icon with the arrow keys, and press Shift+F10; with VoiceOver on macOS press VO-M twice (VO-M-M) to reach the menu bar extras; on Linux it depends on your desktop.

Native menus

Saved-chat exports remain available after restarting the host. They use the retained journal,
preserve original event timestamps, and exclude superseded answers after a retry or edit.

  • Edit — standard clipboard operations: Undo/Redo, Cut/Copy/Paste, Select All.
  • Holaryn — Save Chat Transcript… (Ctrl+Shift+S) exports the active chat: every input and response with timestamps and the model that produced each reply, as one Markdown or JSON file (you pick the format, then choose where to save in a native dialog). Quit (Ctrl+Q).
  • View — Reload (Ctrl+R); Zoom In (Ctrl+=), Zoom Out (Ctrl+-), and Reset Zoom (Ctrl+Shift+0) for low-vision use — the level persists across launches and every change is announced to screen readers. The complete workspace menu follows the same order as the navigation rail: Chat (Ctrl+1), Code (Ctrl+2), Browser (Ctrl+3), Computer (Ctrl+4), Agents (Ctrl+5), Teams (Ctrl+6), Scheduler (Ctrl+7), Goals (Ctrl+8), Batches (Ctrl+9), Approvals (Ctrl+0), Packages, Training data, Workflows, Self-improvement, Annotations, and Settings (Ctrl+,).
  • Help — Keyboard Shortcuts (Ctrl+.), User Guide (F1), First-time Setup…, Report an Issue, Check for updates…, and About Holaryn.

All accelerators are defaults; rebind any of them in Settings → Keyboard Shortcuts, and the native menus update live to show the new combinations — no restart. On macOS, Ctrl reads as Cmd.

When the app is connected to a host on another computer, over https, or at an IPv6 address, the menu items that act inside the window do nothing: Keyboard Shortcuts, User Guide, Save Chat Transcript…, and Copy Last Response. Zoom still changes from the View menu, but the new level is not announced. To see every shortcut, open Settings → Keyboard Shortcuts; to open this guide, use a help button in Settings. Settings there also does not offer start at login, the close-button setting, guided encryption setup, or installing an update from the page; to update the app, choose Check for updates… in the Help or tray menu. An MCP server's browser sign-in cannot open its sign-in page there either: choose Copy sign-in link in its sign-in dialog and open the link in your web browser. If the link cannot be copied, the dialog says so; select the text in the Private sign-in link field, copy it by hand, and open it in your web browser.

The app window only ever shows Holaryn itself. Clicking, pressing Enter on, or activating with a screen reader a link to another website opens it in your web browser. Links that ask for a new window or tab open in your browser too. On Windows so do Ctrl- and Shift-clicked and middle-clicked links, and links you open with Ctrl+Enter or Shift+Enter; on macOS, Cmd-click and Cmd+Return do nothing. Clicking, pressing Enter on, or activating with a screen reader an email link opens a new message in your mail app when the link only fills in the recipients, subject, and body.

  • A link to another Holaryn page that asks for a new window or tab does not open one; the app says that Holaryn pages open only in this window. Reach that page through the app's own navigation instead.
  • When a link does not open, the app says so at once and lists it under Links that did not open: at the bottom of the window, or at the end of the page when the window is narrow (about 640 pixels wide or less, which includes 200% zoom in a 1280-pixel window), or at the end of the dialog the link is in. Each entry has Copy link, which copies the link's address so you can open it yourself (offered only for a website or email address), and Dismiss. If the clipboard refuses, the address appears in a Link address field after the button; select it and copy it by hand.
  • When a link opens, the app says so only if its window still has focus a moment later; when your browser or mail app comes to the front, it says nothing. In Chat and Code these messages are part of the status announcements and appear in the Status panel's recent list.
  • A link an MCP App asked to open, after you allowed it, and an MCP server's Open secure page report their own result, on the app's card or in the question dialog, not under Links that did not open. The question dialog tells the server you agreed only once the page has opened. Connected to a host on another computer, over https, or at an IPv6 address, the app cannot see the result, so it takes two presses: Open secure page asks your web browser to open the page and sends nothing, then focus moves to Confirm the page opened, which sends your agreement once the page is open in your browser. See MCP Apps.
  • The app opens up to eight links at once and then one more every two seconds; when several links do not open at once, it names the first and counts the others. A link opened twice in quick succession (a double click) opens only once. If no browser window opens, wait about ten seconds and try again. The same limit counts provider and MCP sign-in pages and the menu and tray items below.
  • Help → Report an Issue and the tray's Open in browser say nothing when your browser opens. When it cannot open the page, or your system does not answer within about 30 seconds, a system notification titled with the item's name says so, and you can find it again in the notification centre (Win+N on Windows). With notifications turned off you hear nothing. In an MCP server's browser sign-in dialog, Copy sign-in link is always offered in the desktop app. When you sign in to ChatGPT or GitHub Copilot, or an MCP server, and the app cannot confirm within about five seconds that your browser opened the sign-in page, or it did not open, the sign-in panel or dialog says so without moving focus; use Copy sign-in link and paste the link into your browser if the page is not there. These sentences need both the app and the host at this release. With an older host, the MCP dialog instead says "The desktop did not confirm the browser launch." after about five seconds, which means the app does not know whether the page opened: check your browser before pressing again, because the sign-in link works only once; and a provider sign-in page that did not open is not announced: use the link in step 1 or Open sign-in page.
  • When the app is connected to a host on another computer, over https, or at an IPv6 address, clicking, pressing Enter on, or activating with a screen reader a website link still opens your browser on Windows but does nothing on macOS and Linux, and email links do nothing on every system. Use Holaryn in your browser to follow them, signed in: for a host on this computer run holaryn open; for a host on another computer open its sign-in URL (holaryn open --print on that computer prints it). The tray menu's Open in browser opens the same page without signing you in.

Guided encryption setup

Open Settings → System → Encrypted local state → Set up encryption to protect an existing
plaintext installation. The desktop guides recovery-password and backup-folder selection, stops
its own local host, encrypts the records, and restarts it. A host managed by a service or another
process must use the manual procedure, and so must a host the app reaches on another computer,
over https, or at an IPv6 address: Settings does not offer guided setup there. See
Encrypted local state.

Notifications

The app raises a native OS notification when the agent needs you or finishes — approval needed, a question asked, task complete, or an error — even while the window is hidden in the tray. OS toasts are announced by screen readers such as JAWS and Orca.

Auto-updater

The installed app keeps itself current from GitHub Releases, on the channel you
pick under Settings → System → Software updates
(Stable, Beta, or Nightly). The whole flow is native — it works even when the
window is hidden in the tray:

  • On startup the app runs a quiet channel-aware check, and the background
    checker keeps watching at the interval you chose. Check for updates…
    (Help menu and tray) checks on demand and gives the same channel-aware
    answer as the Settings page.
  • When a newer build is found in the background, you first get an OS
    notification — "Holaryn Agent X.Y is available on the {channel} channel" — and
    the ask dialog waits for your next interaction with the app (clicking the
    tray icon, showing the window, or the next launch), so it never interrupts
    you mid-keystroke. The native dialog states your current version, the new
    version, and the channel, with Update Now and Not Now buttons.
  • Not Now waits until the next app start. To silence a specific build for
    good, use Skip this version under Settings → System → Software updates.
  • After installing, a native dialog offers Restart Now / Later and says
    the app will close and reopen. Nothing downloads, installs, or restarts
    without your consent, and every prompt is an OS-native dialog or toast a
    screen reader announces.
  • Every update is signature-verified before it installs, and one update
    refreshes both the window shell and the bundled agent host.
  • Update failures never crash the app; it just keeps running the current
    version.
← Previous Context references Next → Device capability nodes