Desktop app

AgentGem ships as a native desktop app (macOS, Windows, Linux) in addition to the npx CLI. It's the same Gem Builder — the desktop app just hosts the local AgentGem server for you and opens it in its own window, so there's no terminal and no localhost URL to manage.

Under the hood it's a thin Electron host: the app's main process starts the normal AgentGem server on a private 127.0.0.1 port and points a window at it. Every REST endpoint, the MCP surface, and the web UI work exactly as they do over npx — secrets still never leave your machine.

Download#

Grab the latest build from the Releases page (look for a desktop-v* release):

macOS builds are signed and notarized (as of desktop-v0.4.0). Gatekeeper opens the .dmg and the app normally — the "AgentGem is damaged and can't be opened" message from the unsigned 0.1.1 builds is gone. Windows and Linux builds are still unsigned, so on the SmartScreen prompt choose More info → Run anyway.

Upgrading from 0.1.1: because 0.1.1 shipped unsigned and this build is signed, macOS auto-update (Squirrel.Mac) won't apply over an installed 0.1.1. Download this release once by hand; auto-update works normally from there on.

What you get#

• Native folder picker — choose your agent project with the OS folder dialog instead of typing a path.
• App menu & shortcuts — standard menu bar with Cmd/Ctrl+R reload and native copy/paste.
• System tray — closing the window hides the app to the tray and keeps the server running; reopen or quit from the tray icon.
• Auto-update — signed macOS builds update themselves over GitHub Releases (see the 0.1.1 upgrade caveat under Download); Windows and Linux update once those platforms are signed.

Everything else — building, publishing, merging, and deploying Gems — is identical to the web UI.

Run from source#

The desktop app lives in desktop/ as a self-contained package:

git clone https://github.com/ninemindai/agentgem.git
cd agentgem
pnpm -C desktop install
pnpm -C desktop dev      # builds the core + desktop, launches the app

pnpm -C desktop test runs the desktop unit tests. See the desktop/ README for the full developer workflow.

Build an installer#

pnpm -C desktop dist     # unsigned installers under desktop/release/

This bundles the core into a self-contained file, ships the app's assets and its runtime dependencies, and packages a .dmg/.zip (macOS), .exe (Windows), or .AppImage (Linux) with electron-builder. To produce signed builds, set the signing environment variables (CSC_LINK, APPLE_ID, …) documented in the desktop/ README; absent them the build is unsigned.

How it works#

The packaged app can't ship the loose server dist/ — it's an ES module with its own dependency tree — so the build bundles the core into a single self-contained file (with its runtime peers alongside) that the Electron main process loads on startup. The window then loads the local server's URL. This means the desktop app is never a fork of the web UI: it's the same server, hosted.

Troubleshooting#

• Windows SmartScreen warning — expected; the Windows build is still unsigned. Choose More info → Run anyway. (macOS builds are signed and notarized, so Gatekeeper no longer warns.)
• Window is blank or the app won't start — the app shows the underlying error in a dialog. Rebuild from source (pnpm -C desktop dev) to see the full logs.
• A second launch focuses the existing window — that's intentional; AgentGem is single-instance so you never run two servers at once.