Electron Desktop App

The Superagent desktop app is the simplest way to get started. It packages the full Superagent server, web UI, and container runtime management into a single native application for macOS and Windows.

When to choose this option

• You are a single user running Superagent on your own machine.
• You want the quickest path from download to working agents.
• You prefer a native app experience with system tray, notifications, and auto-updates.
• You do not need remote access or multi-user authentication.

System requirements

A container runtime must be installed and running before you launch Superagent. Each agent runs inside its own isolated container, so the runtime is required for agent execution.

Download and install

Download the latest release from the GitHub Releases page.

macOS: Download the .dmg file for your architecture. Open the disk image and drag Superagent to your Applications folder. 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 the Superagent-Setup.exe installer. Run the installer -- it will guide you through choosing an installation directory and creating shortcuts. The installer creates both a desktop shortcut and a Start Menu entry.

What is included

The desktop app bundles:

• API server -- The Hono-based API server starts automatically on port 47891 (or the next available port) when the app launches.
• Web UI -- The React frontend is served from the built-in server and rendered in the Electron window.
• Container management -- On macOS, the app embeds a Lima virtual machine for lightweight container management alongside Docker/OrbStack/Podman support. On Windows, it uses WSL 2.
• Database -- A SQLite database stored in the app's data directory.

Data directory

Superagent stores its database, agent workspaces, and configuration in a platform-specific data directory:

This directory contains:

• 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 desktop app checks for updates automatically. On launch, it checks the GitHub releases feed after a 30-second delay, then rechecks every 4 hours. It also checks immediately when your machine wakes from sleep.

When an update is available, the app displays a notification in the UI. Updates are not downloaded automatically -- you choose when to download and install. Once downloaded, the update is applied the next time you quit and relaunch the app.

You can also check for updates manually from the app's settings page.

Pre-release updates: If you opt into pre-release updates in settings, the updater checks both the pre-release and stable channels and offers whichever version is newer.

System tray

On macOS and Windows, Superagent places an icon in the system tray (menu bar on macOS, notification area on Windows). The tray menu shows:

• Open Superagent -- Bring the main window to the front.
• Agent status -- A grouped list of your agents organized 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 on or off in the app settings. When the tray is active, closing the main window keeps the app running in the background so agents can 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 your input.
• Scheduled session -- A scheduled task has started.

Notifications work even when the main window is closed. Clicking a notification opens the app and navigates directly to the relevant agent and session. On macOS, notifications include action buttons (such as Approve/Deny for API request reviews).

Each notification type can be individually enabled or disabled in settings.

Keep awake (macOS)

On macOS, you can enable "Keep Awake" to prevent your machine from sleeping while agents are running. This uses macOS's 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://) for deep linking:

• superagent://agent/{slug} -- Open the app and navigate to 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 Superagent as a Docker container for headless or remote access.
• Auth Mode (Multi-User) -- Deploy Superagent for a team with authentication and access control.