Skip to main content

Install ToolHive

This guide walks you through installing, upgrading, and managing the ToolHive desktop application.

Latest version Release date

Prerequisites​

Before installing ToolHive, make sure your system meets these requirements:

  • Operating systems:
    • macOS (Apple silicon or Intel)
    • Windows 10/11 (x64)
    • Linux (x86_64/amd64)
  • Container runtime:
    • Docker / Docker Desktop
    • Podman / Podman Desktop
    • Colima with Docker runtime
    • Rancher Desktop with the dockerd/moby runtime (experimental)

ToolHive requires minimal CPU, memory, and disk space. The exact requirements depend on how many MCP servers you run and the resources they use.

Install ToolHive​

Select your operating system to see the installation instructions.

Download the latest ToolHive installer for Apple silicon or Intel-based Macs and open the DMG file.

Copy the ToolHive app to your Applications folder. You can then open it from your Applications folder, Launchpad, or using Spotlight search.

System tray​

When you close the ToolHive application window, it continues running in the background so your MCP servers remain available. ToolHive installs a system tray icon for quick access. The tray menu includes:

  • A status indicator showing whether ToolHive is running or stopped
  • The current application version
  • Check for Updates... to find and install available updates
  • Start on login toggle to launch ToolHive when you log in to your system
  • Show Window and Hide Window to control the application window
  • Quit ToolHive to stop all running MCP servers and exit the application

Application settings​

Open the ToolHive settings screen from the gear icon (⚙️) in the application window. The settings screen allows you to configure various options:

  • Display theme: Choose between light and dark themes for the application. ToolHive matches your system theme by default.
  • Start on login: Automatically start ToolHive when you log in to your system. MCP servers that were running when you quit ToolHive are restarted automatically.
  • Error reporting: Enable or disable error reporting and telemetry data collection.
  • Skip quit confirmation: Skip the MCP server shutdown confirmation dialog when quitting ToolHive.

The settings screen also includes a Version tab and a Logs tab:

  • Version tab: Displays the Desktop UI version and ToolHive binary version. A green Latest badge appears next to each component when you are running the current version. The Downloads toggle controls whether ToolHive automatically downloads and installs updates when a new release is available (enabled by default). If you disable auto-updates, an alert appears when a new version is available with a Download button so you can update manually. A blue indicator icon on the Version tab signals that an update is ready.
  • Logs tab: Download the application log file for troubleshooting.

Upgrade ToolHive​

ToolHive checks for updates automatically. By default, it downloads and installs new versions in the background. During the upgrade, ToolHive stops all running MCP servers, updates the application, and then restarts itself and the MCP servers.

You can also trigger an update manually:

  • From Settings: Open Settings > Version tab and click Download when an update is available.
  • From the system tray: Click Check for Updates... in the system tray menu to check for and install the latest version.
Linux

On Linux, the Download button in the Version tab opens the ToolHive UI releases page in your browser instead of downloading the update in-app. Download the appropriate package and install it using your package manager.

If you prefer, you can disable auto-updates in Settings > Version and download the latest installer manually from the ToolHive UI releases page. See the Install ToolHive section for direct download links.

File locations​

ToolHive stores its configuration and data files in several locations depending on your operating system:

  • The ~/Library/Application Support/ToolHive directory contains:
    • Configuration files and application data for the ToolHive UI
    • MCP server logs and configurations (logs/ and runconfigs/ directories)
    • Your encrypted secrets store (secrets_encrypted file)
    • ToolHive CLI/API configuration file (config.yaml)
  • The main UI application log is located at ~/Library/Logs/ToolHive/main.log

Since macOS is not case sensitive, the ~/Library/Application Support/ToolHive directory is shared by the UI and CLI if you have both installed.

You can also download the application log file from the Settings screen (⚙️) in the ToolHive UI.

Telemetry and error reporting​

ToolHive uses Sentry for error tracking and performance monitoring to help us identify and fix issues, improve stability, and enhance the user experience. This telemetry is enabled by default. You can disable this by turning off the Error reporting option in the settings screen (⚙️) if you prefer not to share this data.

ToolHive collects the following information:

  • Error reports and crash logs
  • Performance metrics
  • Usage patterns

This data is anonymized and does not include any personally identifiable information. It helps us understand how ToolHive is used and identify areas for improvement. Review the Stacklok privacy policy and Terms of Service for more details.

Next steps​

Now that you have ToolHive installed, you can start using it to run and manage MCP servers. See Run MCP servers to get started.

CLI access for advanced users

ToolHive UI includes the CLI for terminal access and advanced features. See Access the CLI from ToolHive UI to learn more.

Troubleshooting​

"Connection Refused" error on startup

A "Connection Refused" error on startup usually means your container runtime (Docker, Podman, or Colima) isn't installed, isn't running, or isn't configured correctly.

Follow the instructions in the error message to install or start your container runtime. For example, if you're using Docker Desktop, make sure it's running and the Docker daemon is active. If the retry button doesn't work, restart ToolHive.

No system tray icon on Linux

Recent versions of Fedora and some other distributions ship without the AppIndicator GNOME extension that ToolHive needs to render its system tray icon.

On Fedora, install the gnome-shell-extension-appindicator package:

sudo dnf install gnome-shell-extension-appindicator

Log out and log back in to activate the extension.

Alternatively, install the Extension Manager app from your distribution or Flathub and use it to install the AppIndicator and KStatusNotifierItem Support extension. The ToolHive icon should then appear in your system tray.

For other installation issues, check the ToolHive UI issues on GitHub or join the Discord community.