Self-Hosting
Electron Desktop App
Install Gamut as a native desktop app on macOS or Windows. The simplest way to get started, with the server, web UI, and container management in one application.
When to choose this option
- A single user running Gamut on their own machine.
- The quickest path from download to working agents.
- A native app experience: system tray, notifications, and auto-updates.
- No need for remote access or multi-user authentication.
System requirements
| macOS | Windows | |
|---|---|---|
| OS version | macOS 12 (Monterey) or later | Windows 10 or later |
| Architecture | Intel (x64) or Apple Silicon (arm64) | x64 or arm64 |
| Container runtime | Docker Desktop or Podman; OrbStack works via its Docker-compatible socket | Docker Desktop (WSL 2 backend) |
Each agent runs inside its own isolated container, so a runtime must be installed and running before Gamut launches.
Download and install
Download the latest release from the GitHub Releases page. Installer filenames include the version and architecture.
macOS: Download the .dmg for your architecture (Gamut-0.4.8-arm64.dmg for Apple Silicon, Gamut-0.4.8-x64.dmg for Intel). Open the disk image and drag Gamut to Applications. On first launch, macOS may show a security prompt; click Open to allow it. The app is code-signed and notarized by Apple.
Windows: Download and run the installer (Gamut-0.4.8-Setup.exe) to choose an installation directory. It creates a desktop shortcut and a Start Menu entry.
What is included
The desktop app bundles:
- API server: the Hono-based server starts automatically on port 47891 (or the next available port) when the app launches.
- Web UI: the React frontend, served from the built-in server and rendered in the Electron window.
- Container management: on macOS, an embedded Lima virtual machine for lightweight container management alongside Docker and Podman support. On Windows, WSL 2.
- Database: a SQLite database stored in the app's data directory.
Data directory
Gamut stores its database, agent workspaces, and configuration in a platform-specific data directory:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Superagent/ |
| Windows | %APPDATA%\Superagent\ |
The directory is deliberately named Superagent (the legacy product name) so existing installs keep their data across the rename to Gamut.
Contents:
superagent.db: the SQLite database (agents, sessions, settings, audit logs).agents/: per-agent workspace directories with files, downloads, and message history.settings.json: application and API key configuration.
Auto-updates
The app checks the GitHub releases feed 30 seconds after launch, then every 4 hours, and immediately when the machine wakes from sleep.
When an update is available, the app shows a notification in the UI. Updates are not downloaded automatically: choose when to download, and the update applies the next time the app quits and relaunches. Updates can also be checked manually from the settings page.
Pre-release updates: opting in makes the updater check both the pre-release and stable channels and offer whichever version is newer.
System tray
On macOS and Windows, Gamut places an icon in the system tray (menu bar on macOS, notification area on Windows). The tray menu shows:
- Open Gamut: bring the main window to the front.
- Agent status: agents grouped by status (Needs Input, Working, Idle, Sleeping). Click any agent to navigate directly to it.
- Quit: shut down all agents and exit the application.
The tray icon can be toggled in the app settings. With the tray active, closing the main window keeps the app running in the background so agents continue working. On Linux, closing all windows quits the application.
Notifications
The desktop app supports native OS notifications for agent events:
- Session complete: an agent finished its task.
- Session waiting: an agent needs input.
- Scheduled session: a scheduled task has started.
Notifications work even when the main window is closed. Clicking one opens the app and navigates to the relevant agent and session. On macOS, notifications include action buttons (such as Approve/Deny for API request reviews). Each type can be enabled or disabled individually in settings.
Keep awake (macOS)
On macOS, Keep Awake prevents the machine from sleeping while agents are running. It uses the pmset disablesleep command and requires a one-time administrator password prompt to install a passwordless sudoers rule.
Deep links
The desktop app registers a custom URL scheme (superagent://):
superagent://agent/{slug}: open the app at a specific agent.superagent://dashboard/{agent}/{dashboard}: open a dashboard in a standalone window.
Dashboards can be added to the macOS Dock as standalone app shortcuts through the dashboard context menu.
Next steps
- Quickstart: Create your first agent.
- Single-User Docker: Run Gamut headless or on a remote server.
- Auth Mode (Multi-User): Deploy Gamut for a team with authentication and access control.