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 stays 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

Run ToolHive on login​

You can configure ToolHive to start automatically when you log in to your system. This is useful if you want your MCP servers to be available without manually starting ToolHive each time.

To enable this feature, turn on the Start on login option in the system tray icon menu or in the settings menu (⚙️) in the application.

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.

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 menu (⚙️) 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, it's likely because your container runtime (Docker or Podman) is not installed, not running, or not configured correctly.

Follow the instructions on the error message to install or start your container runtime. For example, if you're using Docker Desktop, make sure it is running and that the Docker daemon is active.

If the retry button doesn't work, try restarting 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.