Installing the Desktop Bundle

The desktop bundle runs Agent Mesh as a single application on your laptop. It packages the runtime, an in-memory broker, and the Agent Mesh UI into one process, so there is no separate event broker to provision and no configuration required beyond connecting a large language model (LLM) provider. For what the in-memory broker does and does not provide versus a production Solace event broker, see The Broker in Production and on the Desktop.

For the prerequisites that apply before any installation, see Before You Begin. When you are ready to carry production traffic, you move to a supported deployment using the same declarative configuration you build here. See Moving to Production.

Supported Environments

The desktop bundle runs on these platforms:

Platform	Supported architectures
macOS	Apple Silicon (`arm64`), Intel (`amd64`)
Windows	x86_64 (`amd64`)
Linux (Experimental)	x86_64 (`amd64`), aarch64 (`arm64`)

No fixed CPU, memory, or disk minimum applies beyond a supported operating system. The footprint depends on the models and tools you run.

Prerequisites

To install the desktop bundle, you require an API key for a supported LLM provider before you launch the application. The desktop bundle includes its own in-memory event broker, so you do not procure one. You connect your provider in the model configuration UI the first time you launch the application. To obtain a key and confirm your provider is reachable, see LLM Provider in Before You Begin.

Install the Desktop Bundle

Download the installer for your platform from the Desktop/ folder of the Agent Mesh release. For the download procedure, see Before You Begin.

On macOS:

Download the .dmg installer that matches your Mac: solace-agent-mesh-<version>-desktop-macos-apple-silicon.dmg for Apple Silicon or solace-agent-mesh-<version>-desktop-macos-intel.dmg for Intel. The installer file appears in your Downloads folder.
Open the .dmg, then drag the Agent Mesh application to your Applications folder. The application appears in Applications.
Open Agent Mesh from Applications. The application window opens and prompts you to connect an LLM provider.

Installing without administrator privileges — Dragging to the system /Applications folder can prompt for an administrator password because that folder is shared across all accounts. To install without administrator privileges, drag the application to a folder your account owns instead, such as your own Desktop (~/Desktop). Agent Mesh runs the same from either location.

On Windows:

Download the .exe installer (solace-agent-mesh-<version>-desktop-windows-x64.exe). The installer file appears in your Downloads folder.
Run the installer. It installs Agent Mesh for the current user under %LOCALAPPDATA%\Programs\Solace Agent Mesh without requiring administrator privileges, then adds it to your Start menu. The installation is per-account, so each user on a shared machine installs Agent Mesh separately.
Open Agent Mesh from the Start menu. The application window opens and prompts you to connect an LLM provider.

Windows SmartScreen warning — On first run, Windows SmartScreen may show a "Windows protected your PC" warning. This warning is expected: SmartScreen builds trust from how widely an installer has been downloaded, so newly published releases are flagged until they accumulate reputation, even though the installer is signed. To continue, select "More info", then "Run anyway".

On Linux (Experimental):

Linux support for the desktop bundle is in the Experimental stage and under active development. Its packaging and behavior are subject to change.

Agent Mesh ships a Debian package (.deb), an RPM package (.rpm), and a portable archive (.tar.gz). Each comes in two builds, one for each version of WebKitGTK that current distributions provide. The Desktop/Linux (Experimental)/ folder holds one folder per build. Find your distribution in the following table, then open the folder it names:

Your distribution	Folder	File to download
Ubuntu 24.04 and later, Debian 13 and later	`modern-distros`	`.deb`
Ubuntu 22.04, Debian 12	`legacy-distros`	`.deb`
Fedora 44 and later	`modern-distros`	`.rpm`
Fedora 43 and earlier	`modern-distros`	`.tar.gz`
RHEL 9, Rocky Linux 9, AlmaLinux 9	`legacy-distros`	`.rpm`

modern-distros contains the WebKitGTK 4.1 build, and legacy-distros contains the WebKitGTK 4.0 build. Each folder holds an amd64/ and an arm64/ subfolder. Open the folder listed for your release, then download the file for your CPU architecture.

If your distribution is not listed, check which WebKitGTK version it provides before you download:

# Debian and Ubuntu
apt-cache policy libwebkit2gtk-4.1-0 libwebkit2gtk-4.0-37

# Fedora, RHEL, Rocky Linux, and AlmaLinux
dnf list webkit2gtk4.1 webkit2gtk3

If the WebKitGTK 4.1 library is available, use modern-distros. If only the 4.0 library is available, use legacy-distros. If neither library is available, your distribution does not package WebKitGTK. Install it before you run the application, then use the folder that matches the version you installed.

Installing a .deb or .rpm requires administrator (sudo) privileges. From your Downloads folder, install the package that matches your architecture and WebKitGTK build. The package manager also installs the WebKitGTK, GTK 3, and OpenSSL 3 libraries the application requires. In the following commands, <arch> is amd64 or arm64, and <abi> is 4.0 or 4.1:

# Debian and Ubuntu
sudo apt install ./solace-agent-mesh-<version>-desktop-linux-<arch>-webkit2gtk-<abi>.deb

# Fedora, RHEL, Rocky Linux, and AlmaLinux
sudo dnf install ./solace-agent-mesh-<version>-desktop-linux-<arch>-webkit2gtk-<abi>.rpm

Then open Agent Mesh from your applications menu. The application window opens and prompts you to connect an LLM provider.

To install without administrator privileges, use the portable archive instead of a package. It runs from a folder your account owns and does not require sudo. The archive does not install dependencies, so the matching runtime libraries must already be present on the system:

Debian and Ubuntu, 4.0 build: libwebkit2gtk-4.0-37, libgtk-3-0, and libssl3
Debian and Ubuntu, 4.1 build: libwebkit2gtk-4.1-0, libgtk-3-0, and libssl3
RHEL 9, Rocky Linux 9, and AlmaLinux 9, 4.0 build: webkit2gtk3, gtk3, and openssl-libs
Fedora, 4.1 build: webkit2gtk4.1, gtk3, and openssl-libs

Extract the archive and run the application:

tar -xzf solace-agent-mesh-<version>-desktop-linux-<arch>-webkit2gtk-<abi>.tar.gz
./solace-agent-mesh-desktop/solace-agent-mesh

To add an applications-menu entry for your account, also without sudo, run ./solace-agent-mesh-desktop/install.sh.

Configuration

The desktop bundle runs with bundled default settings. The only setup it requires is your LLM provider, which you connect in the model configuration UI on first launch. The built-in agents then use it.

The desktop bundle does not expose the infrastructure configuration that a production deployment requires, such as a connection to a separate, production-grade Solace event broker, persistent artifact storage, and authentication. Those settings apply when you deploy Agent Mesh for production. See Moving to Production.

Advanced Configuration with Environment Variables

The desktop bundle runs with bundled defaults, but you can override its settings with environment variables to evaluate features that the defaults leave off, such as connecting to a separate Solace event broker or enabling role-based access control (RBAC). On startup, the desktop bundle reads a .env file from the home folder and applies every variable it defines:

macOS: ~/Library/Application Support/sam/.env
Windows: %AppData%\sam\.env
Linux: ~/.config/sam/.env

Restart the application after you edit the file so the new values take effect.

As an example, the following .env connects the desktop bundle to a separate Solace event broker instead of the in-memory one, which is what enables broker-backed features such as the event mesh gateway and event mesh connector:

SOLACE_DEV_MODE=false
SOLACE_BROKER_URL=wss://your-broker.messaging.solace.cloud:443
SOLACE_BROKER_VPN=your-vpn
SOLACE_BROKER_USERNAME=your-username
SOLACE_BROKER_PASSWORD=your-password

You must set SOLACE_DEV_MODE=false: the desktop bundle uses its in-memory broker by default, so setting SOLACE_BROKER_URL alone is not enough. To return to the in-memory broker, remove these variables (or set SOLACE_DEV_MODE=true) and restart. Because a .env file can hold credentials, keep it readable only by your own account.

Tool Availability

A few built-in agent tools rely on external engines that the desktop bundle does not include, so those specific tools do not work in the desktop bundle until you install the engine yourself:

Tool	Engine it requires
`render_document_to_images`	LibreOffice, poppler, ImageMagick
`html_to_pdf`	Chromium
`mermaid_diagram_generator`	Chromium
`image_magick`	ImageMagick
`ffmpeg`	ffmpeg
`ffprobe`	ffmpeg

The Agent Mesh UI still renders Mermaid diagrams inline in chat with no engine. Only the mermaid_diagram_generator tool, which saves a diagram as an artifact, requires Chromium. A tool whose required engine is missing fails with a clear message rather than affecting the rest of the application.

To enable one of these tools, install the engine it requires so it is on your PATH, then restart the application (for Chromium, you can instead point the bundle at an existing browser with the SAM_CHROMIUM_PATH environment variable). A full Kubernetes deployment includes these engines, so the tools work there with no per-machine setup. For what each tool does, see Built-In Tools.

Verify the Installation

Confirm the LLM connection by sending a message to a built-in agent.

In the application window, start a new chat.
Ensure Orchestrator is selected in the agent picker. The Orchestrator is a built-in agent that coordinates work across Agent Mesh.
Send a message such as "What can you do?" The Orchestrator replies and its response streams back token by token, which confirms the LLM connection is working.

Data and Logs

The desktop bundle keeps all of its state in a single home folder:

macOS: ~/Library/Application Support/sam
Windows: %AppData%\sam (for example, C:\Users\<user>\AppData\Roaming\sam)
Linux: ~/.config/sam

This folder holds your configuration, the local database where the application stores the agents, models, and sessions you create, and the application log at data/desktop.log.

To start fresh, quit the application and delete this folder. The next launch recreates it with bundled defaults.

Deleting the folder permanently removes all of your local data.

Moving to Production

The desktop bundle runs everything in one process with the in-memory broker and does not use production-grade storage, so it is not supported for team or production workloads.

What you build while evaluating carries forward. Agent Mesh uses one declarative configuration model across every environment. The agents, models, entrypoints, and tools you define in the desktop bundle are expressed as the same configuration a production deployment applies, so the definitions you validate here carry forward rather than being rebuilt for production. For how Agent Mesh manages this configuration, see Managing Configuration as Code (Early Access).

Agent Mesh offers these production paths:

Agent Mesh Cloud is a managed service that Solace hosts and operates. See Agent Mesh Cloud.
A Kubernetes deployment runs Agent Mesh in your own cluster with a separate, production-grade Solace event broker, persistent storage, and authentication. See Deploying with Kubernetes.

Next Steps

Now that Agent Mesh is running, the most common next step is to build an agent of your own. See Create Your First Agent.

Provide feedback