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
    • 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 icon​

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. You can use it to:

  • Enable or disable Start on login
  • Show or hide the ToolHive application window
  • Quit ToolHive, which stops all running MCP servers

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.

From the settings screen, you can also view version information and download the application log file for troubleshooting.

Upgrade ToolHive​

ToolHive automatically checks for updates. When a new version is available, you'll see a notification in the application. During the upgrade, ToolHive stops all running MCP servers, updates the application, and then restarts itself and the MCP servers.

You can also manually install updates by downloading the latest installer for your operating system from the ToolHive UI releases page and running it. The installer will upgrade your existing ToolHive installation to the latest version. 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.

Troubleshooting​

Connection Refused error on startup

If you see a "Connection Refused" error when starting ToolHive, your container runtime (Docker or Podman) is likely not installed, not running, or not 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 that the Docker daemon is active.

If the retry button doesn't work, restart ToolHive.

No system tray icon on Linux

Recent versions of Fedora Linux and other distributions have removed the AppIndicator extension from their default installations. ToolHive requires this extension for the system tray icon to work properly.

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

sudo dnf install gnome-shell-extension-appindicator

You'll need to log out and log back in to activate the extension.

Alternatively, install the Extension Manager app. It's available as a native package in many distributions, or you can install it from Flathub. Then, use Extension Manager to install the AppIndicator extension (listed as "AppIndicator and KStatusNotifierItem Support").

The ToolHive icon should now appear in your system tray.

Other issues​

For other installation issues, check the GitHub issues page or join the Discord community.