Skip to main content

Install ToolHive

This guide walks you through installing, upgrading, and managing the ToolHive CLI (thv).

Latest version Release date

Prerequisites​

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

  • Operating systems: macOS, Linux, or Windows
  • 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​

You can install ToolHive using several methods:

Homebrew is the easiest installation method on macOS or Linux:

brew tap stacklok/tap
brew install thv

Verify your installation​

To verify that ToolHive is installed correctly:

thv version

You should see output showing the version number, build date, and Git commit:

ToolHive version output
ToolHive v0.1.1
Commit: 18956ca1710e11c9952d13a8dde039d5d1d147d6
Built: 2025-06-30 13:59:34 UTC
Go version: go1.24.1
Platform: darwin/arm64
Privacy: Anonymous usage metrics

ToolHive collects anonymous usage metrics (tool call counts only) to help improve the product. No personal information or sensitive data is collected. You can disable this at any time using thv config usage-metrics disable. For more information, see the FAQ.

CLI conflict resolution​

If you have the ToolHive UI installed, it automatically manages the CLI for version compatibility. ToolHive UI creates a symlink to its bundled CLI and configures your shell's PATH, so you don't need to install the CLI separately.

Running a standalone CLI binary (installed via Homebrew, WinGet, or manually) while ToolHive UI is installed shows a conflict error:

CLI conflict error
Error: CLI conflict detected

The ToolHive Desktop application manages a CLI installation at:
  /Applications/ToolHive.app/Contents/Resources/bin/darwin-arm64/thv

You are running a different CLI binary at:
  /usr/local/bin/thv

To avoid conflicts, please use the desktop-managed CLI or uninstall
the ToolHive Desktop application.

To use the desktop-managed CLI, ensure your PATH includes:
  ~/.toolhive/bin

Or run the desktop CLI directly:
  ~/.toolhive/bin/thv [command]

Desktop version: 0.8.3

Resolving the conflict​

If you see this error, you have two options:

  1. Use the UI-managed CLI (recommended): Open a new terminal window to pick up the PATH changes. The thv command should now use the UI-managed CLI.

  2. Uninstall the standalone CLI: If you want to use only the UI-managed CLI, uninstall the standalone version:

    • Homebrew: brew uninstall thv
    • WinGet: winget uninstall stacklok.thv
    • Manual: Remove the binary from your PATH
Debugging override

For debugging purposes, you can bypass the conflict check by setting TOOLHIVE_SKIP_DESKTOP_CHECK=1. This is not recommended for normal use as it may cause version compatibility issues.

Upgrade ToolHive​

ToolHive automatically checks for updates and notifies you when a new version is available. When you run a ToolHive command, it displays a message if an update exists.

To upgrade ToolHive:

If you installed ToolHive via Homebrew, upgrade it with:

brew upgrade thv

Get help with ToolHive commands​

ToolHive has built-in help for all commands:

# General help
thv --help

# Help for a specific command
thv <COMMAND> --help

For detailed documentation on each command, see the CLI reference documentation.

Enable shell completion​

ToolHive can generate auto-completion scripts for your shell to make it easier to use. The thv completion command generates scripts for bash, zsh, fish, and PowerShell.

Each shell has different requirements for where to store completion scripts and how to enable them. The help output for each shell provides specific instructions:

# Get help on completion options
thv completion --help

# Get specific instructions for your shell
thv completion bash --help
thv completion zsh --help
thv completion fish --help
thv completion powershell --help

Uninstall ToolHive​

To uninstall ToolHive:

  1. First, remove any MCP servers managed by ToolHive:

    # List running servers
    thv list
    # Stop and remove each server
    thv stop --all
    thv rm <SERVER_NAME>

  2. Remove all ToolHive configuration and log files:

    # Remove the secrets encryption password entry from your OS keyring
    thv secret reset-keyring

    # Delete the ToolHive configuration and log files
    # macOS:
    rm -rf ~/Library/Application\ Support/toolhive/

    # Linux:
    rm -rf ~/.config/toolhive/
    rm -rf ~/.local/share/toolhive/
    rm -rf ~/.local/state/toolhive/

    # Windows:
    Remove-Item "$env:LOCALAPPDATA\toolhive" -Recurse -Force

  3. Remove the ToolHive CLI:

If you installed ToolHive via Homebrew, uninstall it with:

brew uninstall thv

Next steps​

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

Troubleshooting​

Permission denied errors

If you see "permission denied" errors when running ToolHive:

  1. Make sure the binary is executable:

    chmod +x /path/to/thv

  2. If you're using Docker on Linux, make sure your user has permission to access the Docker socket:

    sudo usermod -aG docker $USER

    Log out and back in (or run newgrp docker) for the change to take effect. See Docker's post-installation steps for more details.

Upgrade error on Windows

On Windows, the thv.exe binary is locked while any MCP server proxy is running. If you try to upgrade with servers still running, you'll see an error like this:

Error example
An unexpected error occurred while executing the command:
remove: Access is denied.: "C:\Users\USERNAME\AppData\Local\Microsoft\WinGet\Packages\stacklok.thv_Microsoft.Winget.Source_8wekyb3d8bbwe\thv.exe"
Uninstall failed with exit code: 0x8a150003 : Executing command failed

To resolve this:

  1. Stop all running MCP servers:

    thv stop --all

  2. Re-run the upgrade:

    winget upgrade stacklok.thv

  3. If the error persists, end any lingering thv.exe processes in Task Manager, then re-run the upgrade.

  4. After the upgrade completes, restart your MCP servers:

    thv list --all
    thv restart <SERVER_NAME>
    # repeat for each server

If you encounter a different installation issue, check the GitHub issues page or join the Discord community.