Skip to content

install.mdx

Latest commit

 

History

History
474 lines (323 loc) · 11.6 KB

install.mdx

File metadata and controls

474 lines (323 loc) · 11.6 KB
title Install ToolHive
description Install, upgrade, and manage the ToolHive CLI on macOS, Linux, and Windows.

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

WinGet is available by default on Windows, making this the easiest installation method:

winget install stacklok.thv

Open a new terminal window after installation to ensure the thv command is available.

  1. Visit the ToolHive releases page

  2. Download the appropriate binary for your platform:

    • toolhive_<version>_darwin_amd64.tar.gz for macOS (Intel)
    • toolhive_<version>_darwin_arm64.tar.gz for macOS (Apple Silicon)
    • toolhive_<version>_linux_amd64.tar.gz for Linux (x86_64)
    • toolhive_<version>_linux_arm64.tar.gz for Linux (ARM64)
    • toolhive_<version>_windows_amd64.zip for Windows (x86_64)
    • toolhive_<version>_windows_arm64.zip for Linux (ARM64)

  3. Extract the archive and copy the binary to a directory in your PATH:

    macOS/Linux:

    tar -xzf toolhive_<version>_<platform>.tar.gz
sudo install -m 0755 thv /usr/local/bin/

    On Windows, extract the ZIP file to a folder and add that folder to your PATH environment variable.

Prerequisites for building from source

  • Go 1.24 or newer
  • Git
  • Your $GOPATH/bin directory should be in your PATH

Using Task (recommended)

:::note

The Task scripts currently only support macOS and Linux. Windows users should use the pre-compiled binaries or build from source using Go tools.

:::

If you have Task installed:

  1. Clone the repository:

    git clone https://github.com/stacklok/toolhive.git
cd toolhive

  2. Build and install the binary in your $GOPATH/bin:

    task install

Using Go tools

  1. Clone the repository:

    git clone https://github.com/stacklok/toolhive.git
cd toolhive

  2. Build and install the binary in your $GOPATH/bin:

    go install ./cmd/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 v0.1.1
Commit: 18956ca1710e11c9952d13a8dde039d5d1d147d6
Built: 2025-06-30 13:59:34 UTC
Go version: go1.24.1
Platform: darwin/arm64

:::info[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:

Error: CLI conflict detected

The ToolHive Desktop application manages a CLI installation at:
  /Applications/ToolHive Studio.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

:::note[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

:::note

On Windows, you must stop all running MCP servers before upgrading ToolHive, otherwise the upgrade will fail because Windows locks the executable while it runs.

Run thv stop --all to stop all running servers. After you complete the upgrade, restart them using thv restart <SERVER_NAME>.

:::

If you installed ToolHive via WinGet, upgrade it with:

winget upgrade stacklok.thv

Follow the same steps as the initial installation, downloading the latest release and overwriting the previous binary.

If you built ToolHive from source, upgrade it by pulling the latest changes and rebuilding:

Using Task:

git pull

task install

Using Go tools

git pull

go install ./cmd/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:

{/* prettier-ignore */} 

   If you installed ToolHive via Homebrew, uninstall it with:

   ```bash
   brew uninstall thv
   ```

 </TabItem>
 <TabItem value='winget' label='WinGet (Windows)'>

   If you installed ToolHive via WinGet, uninstall it with:

   ```bash
   winget uninstall stacklok.thv
   ```

 </TabItem>
 <TabItem value='binary' label='Pre-compiled binaries'>

   Delete the binary from your PATH:

   ```bash
   sudo rm /usr/local/bin/thv
   ```

 </TabItem>
 <TabItem value='source' label='Build from source'>

   Remove the binary from your `$GOPATH`:

   ```bash
   rm $(go env GOPATH)/bin/thv
   ```

 </TabItem>

Next steps

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

Related information

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 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 this to take effect)

    See Docker documentation for more details.

Upgrade error on Windows

If you encounter an error when upgrading ToolHive on Windows, it may be due to the ToolHive executable being locked by a running MCP server proxy.

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. After stopping all servers, run the upgrade command again:

    winget upgrade stacklok.thv

  3. If you still encounter issues, check if any ToolHive processes are still running in the background. You can use Task Manager to end any lingering thv.exe processes.

  4. Restart your MCP servers:

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

Other issues

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