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 forks a local AgentGem core on a private 127.0.0.1 port and points a window at it. That core runs in client mode — it serves the console and every local feature (introspect, build, recall, run) but bundles no auth stack and no database; anything hosted (the shared benchmark) is reached over the network through a same-origin proxy to the hosted marketplace. Every local 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):

Platform File
macOS (Apple Silicon / Intel) AgentGem-<version>-arm64.dmg · AgentGem-<version>.dmg
Windows AgentGem-Setup-<version>.exe (AgentGem.Setup.<version>.exe in 0.4.1 and earlier)
Linux AgentGem-<version>.AppImage

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

Everything else — building, publishing, and merging 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). The bundle is built from the client entry (src/client.ts), which pulls in no better-auth and no PGlite/pg, so it stays lean; the build even fails if any of those symbols leak in.

The Electron main process forks that core as an out-of-process child (not an in-process import() — a blocking core once froze the window and stalled every request), waits for it to report the port it bound, then points the window at the local URL. The window loads the same console you get over npx; hosted data (the benchmark) is proxied to the hosted marketplace. So the desktop app is never a fork of the web UI — it's the same core, run locally in client mode.

Troubleshooting