This guide walks you through installing, upgrading, and managing the ToolHive CLI (thv).
Before installing ToolHive, make sure your system meets these requirements:
ToolHive requires minimal CPU, memory, and disk space. The exact requirements depend on how many MCP servers you run and the resources they use.
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.
Visit the ToolHive releases page
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)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.
$GOPATH/bin directory should be in your PATHnote
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:
Clone the repository:
git clone https://github.com/stacklok/toolhive.git
cd toolhive
Build and install the binary in your $GOPATH/bin:
Clone the repository:
git clone https://github.com/stacklok/toolhive.git
cd toolhive
Build and install the binary in your $GOPATH/bin:
To verify that ToolHive is installed correctly:
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
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:
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: Using Go toolsgit pull
go install ./cmd/thv
ToolHive has built-in help for all commands:
thv --help
thv <COMMAND> --help
For detailed documentation on each command, see the CLI reference documentation.
Enable shell completionToolHive 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:
thv completion --help
thv completion bash --help
thv completion zsh --help
thv completion fish --help
thv completion powershell --help
To uninstall ToolHive:
First, remove any MCP servers managed by ToolHive:
thv list
thv stop --all
thv rm <SERVER_NAME>
Remove all ToolHive configuration and log files:
thv secret reset-keyring
rm -rf ~/Library/Application\ Support/toolhive/
rm -rf ~/.config/toolhive/
Remove-Item "$env:LOCALAPPDATA\toolhive" -Recurse -Force
Remove the ToolHive CLI:
If you installed ToolHive via Homebrew, uninstall it with:
If you installed ToolHive via WinGet, uninstall it with:
winget uninstall stacklok.thv
Delete the binary from your PATH:
sudo rm /usr/local/bin/thv
Remove the binary from your $GOPATH:
rm $(go env GOPATH)/bin/thv
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.
thv CLI referenceIf you see "permission denied" errors when running ToolHive:
Make sure the binary is executable:
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.
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.
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:
Stop all running MCP servers:
After stopping all servers, run the upgrade command again:
winget upgrade stacklok.thv
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.
Restart your MCP servers:
thv list --all
thv restart <SERVER_NAME>
For other installation issues, check the GitHub issues page or join the Discord community.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4