How to Use ToolHive: The Beginner's Guide (First Install, First thv run, and the Secrets Rule)

CodexFuse Team · 2026-11-07T13:06:00.381Z · 24 min read min read

How to Use ToolHive: The Beginner's Guide (First Install, First thv run, and the Secrets Rule)

What is ToolHive and how do you use it?

Learning how to use toolhive starts with one idea: ToolHive is an open-source platform that runs Model Context Protocol servers, usually called MCP servers, inside isolated containers and connects them to your AI client. It is built by Stacklok, it ships as a command-line tool named thv, and it exists because setting up MCP servers by hand is messy. Without it, every server needs its own runtime, its own config file, and its own secrets pasted in plain text.

This toolhive tutorial follows the official ToolHive documentation, the project README, and the GitHub repository, all fetched on November 7, 2026. A thv install on macOS starts with Homebrew, a thv install on Windows starts with WinGet, and the first thv run takes one command. As of November 2026, the latest release is v0.63.0.

1. Install a container runtime, Docker or Podman, and confirm it is running.
2. Install the thv cli with Homebrew on macOS or Linux, or WinGet on Windows.
3. List the registry with thv registry list and pick a server to try first.
4. Run your first server with thv run toolhive-doc-mcp and check it with thv list.
5. Connect your AI client with thv client setup so it can see the server.
6. Store any API key with thv secret set and pass it with a target flag, never in a config file.
7. Stop the server with thv stop and remove it with thv rm when you are done.

CodexFuse offers no ToolHive tool, so this guide links to the official project for the code and to live CodexFuse guides for the surrounding skills. The Docker beginner guide is the first skill to check, because ToolHive cannot run a local MCP server without a container runtime. No commands in this guide were executed in a live testbed, and every number below carries its source with it; no Facebook promotion applies to this guide.

What do you need before your first thv install?

You need three things before a thv install makes sense: a supported operating system, a container runtime, and an AI client you want to connect. ToolHive runs on macOS, Linux, and Windows, and the official docs call the install requirements minimal. The exact CPU, memory, and disk needs depend on how many MCP servers you run, so the docs state no fixed minimum.

The container runtime is the one hard requirement for local servers, with remote servers as the one exception, since they run on someone else's infrastructure and need no local runtime at all. Docker, Docker Desktop, Podman, Podman Desktop, Colima with the Docker runtime, and Rancher Desktop with the dockerd runtime all work, with Rancher Desktop marked experimental. On Linux, your user needs permission to reach the Docker socket, which usually means adding yourself to the docker group and logging out and back in.

The Git beginner guide covers the optional piece, because building ToolHive from source starts with cloning the repository. Most readers will never need it, since the Homebrew and WinGet installs are the documented paths. Pick the install method that matches your machine, then verify it before you run anything else.

How do you install ToolHive on macOS, Linux, and Windows?

A thv install on macOS or Linux uses Homebrew, which the official docs call the easiest installation method. The two commands add the Stacklok tap and install the thv binary, and the same binary works on both operating systems. On Windows, the install is a single WinGet command, and native Windows support has been available since ToolHive v0.0.39, which landed in August 2025, 439 days, or about 14.4 months, before this guide was written.

brew tap stacklok/tap
brew install thv
thv version
winget install stacklok.thv
git clone https://github.com/stacklok/toolhive.git
cd toolhive
go build ./cmd/thv
go install ./cmd/thv

Prebuilt binaries are also available on the GitHub releases page if you prefer a direct download, and building from source needs Go 1.25. The Desktop UI is a separate path: download the macOS DMG, the Windows installer, or the Linux RPM or DEB from the same releases page, and the app manages its own bundled CLI for you. That detail matters, because installing the Desktop UI and a standalone CLI side by side triggers a CLI conflict error that tells you to use the UI-managed binary instead.

Verify the install with thv version, and keep thv updated the same way you installed it, with brew upgrade thv or winget upgrade stacklok.thv. Stop every running server first on Windows, because the thv executable stays locked while a proxy is running. ToolHive collects anonymous usage metrics by default, counting tool calls only, and thv config usage-metrics disable turns that off, while shell completion is available for bash, zsh, fish, and PowerShell through thv completion.

What is the thv cli, and what does thv run do first?

The thv cli is a single Go binary that manages the whole ToolHive workflow from your terminal. It talks to your container runtime, starts MCP servers in locked-down containers, puts a local proxy in front of each one, and rewrites your AI client's config file so the client can reach them. You never install a server's Python or Node runtime yourself, and you never hand-edit a client config file to add a server.

A thv run does four things in one step: it pulls the server image, starts the container in the background, opens a reverse proxy on a random free local port, and labels the container so ToolHive can manage it later. The proxy speaks Streamable HTTP to your client, which has been the default transport since CLI v0.6.0. The older SSE transport is deprecated since the MCP specification revision of March 26, 2025, which is about 19 months before this guide was written, and the old SSE examples in 2025 tutorials no longer describe the default behavior.

Stopping a server is not the same as removing it, and that distinction is worth remembering. A stopped server keeps its container, so thv start or a fresh thv run brings it back with the same configuration. A removed server is gone, and running it again pulls a fresh container, while the thv list output shows the NAME, PACKAGE, STATUS, URL, PORT, GROUP, and CREATED columns, with a URL like a localhost address on a random port that changes on every run unless you pin it.

How do you run your first MCP server with thv run?

Your first thv run should be the docs server, because it needs no API key and no configuration. The official CLI quickstart walks the same path: list the registry, read the server details, run it, list what is running, connect a client, then stop and remove it. The whole arc takes minutes, and it teaches every command you will reuse for real servers later.

thv registry list
thv registry info toolhive-doc-mcp
thv run toolhive-doc-mcp
thv list
thv client setup
thv client status
thv stop toolhive-doc-mcp
thv rm toolhive-doc-mcp

Running thv run toolhive-doc-mcp pulls the image, starts the container, and opens the proxy, and thv list then shows the server with a URL like a localhost address on a random port. Ask your AI client a question about ToolHive, and it will call the docs server through the proxy. A hosted twin exists for machines without a container runtime: thv run toolhive-doc-mcp-remote connects to the hosted endpoint instead of starting a container.

Pin the port when a fixed address matters, with thv run --proxy-port 8080, and keep in mind that the random port is the default because it avoids collisions between servers. The same run command works for any registry name, so thv run fetch starts the Fetch server and thv run github starts the GitHub server, with no extra arguments needed. The registry is the shortcut; the later sections cover images, packages, and remote servers for everything outside it.

How does ToolHive connect your AI client?

ToolHive connects your AI client by rewriting that client's MCP config file for you, and it does it again every time you run, stop, or remove a server. You register the client once with thv client setup, which detects the clients installed on your machine and lets you pick them interactively, or with thv client register followed by the client name. After that, restart the client so it reads the updated config, or it will not see the new server.

The Claude Code beginner guide is the natural next read if Claude Code is your client, because it is one of the best-supported ToolHive clients and the one most beginners start with. The supported list also includes Cursor, VS Code, GitHub Copilot in VS Code, Codex, Cline, Continue, Gemini CLI, Goose, Kiro, LM Studio, OpenCode, Pi, Zed, Windsurf, Trae, Antigravity, Factory.ai Droid, Kimi Code CLI, Mistral Vibe, Qoder, and the Sourcegraph Amp CLI. Minimum versions are listed in the compatibility reference because they mark the earliest version that supports Streamable HTTP.

Claude Desktop and ChatGPT Desktop have no auto-configuration, and that is the one client caveat beginners hit most often. Claude Desktop is STDIO-only, so it cannot use ToolHive's HTTP proxy directly, and the documented workaround wraps a running workload as a STDIO process with thv proxy stdio. Check thv client status any time you are unsure what is registered, and use thv list --format mcpservers to get the standard JSON format for a client you must configure by hand.

What is the ToolHive secrets rule?

ToolHive secrets follow one rule: never put a secret in a plaintext configuration file. MCP servers often need API tokens, connection strings, and other sensitive values, and the official docs put it plainly, saying ToolHive lets you manage these values securely without exposing them in plaintext configuration files. The launch post says the same thing in plainer words, noting that the team is not keen on API keys leaking and that there is no need to copy secrets across configuration files.

A secret lives in an encrypted store on your disk, with the encryption password held in your operating system keyring, so you are not prompted every time. You set a secret once with thv secret set, and ToolHive injects it as an environment variable inside the server container when you run the server. The config file never holds the value, and the server never sees it any other way.

thv secret setup
thv secret set github
thv secret list
thv secret get github
thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github
thv secret delete github
thv secret reset-keyring

Find the exact variable a server expects with thv registry info, which lists the required and optional environment variables for every registry server. The GitHub server, for example, requires GITHUB_PERSONAL_ACCESS_TOKEN, and the target flag maps your stored secret to exactly that name. If a server cannot see a secret, check the list, read the value back, confirm the target name matches, and read the server logs.

Pick the provider with thv secret setup or thv secret provider, and note that only one provider is active at a time. The older command thv config secrets-provider encrypted appears in 2025 tutorials and is superseded, so do not copy it from an old guide. Secrets are unrecoverable if the keyring entry or encryption password is lost, so a reset means deleting the encrypted store and recreating every secret from scratch, which is the price of the rule, and also why the rule works.

How do you find servers in the ToolHive registry?

The registry is a built-in catalog of MCP servers with verified configurations that meet a minimum quality standard, and the Stacklok team vets every server before it is accepted. The web listing counted on November 7, 2026 shows around 100 entries, from database servers to GitHub, Notion, Stripe, and Context7, including remote twins of the popular local servers. That count is a count of the website listing on that date, not a number Stacklok itself publishes, and the CLI built-in registry may differ slightly.

Search the registry before you install anything by hand, because a vetted entry saves you the image name, the arguments, and the permission profile. The GitHub beginner guide pairs well with the GitHub server entry, since that server is the one most readers run first once the docs server works. The registry shows two tiers, Official and Community, and the list output shows the name, description, tier, stars, and pulls for each entry.

thv registry list
thv search github
thv registry info github
thv registry info github --format json
thv run github

Reading a server before you run it is a habit worth building, because thv registry info shows the image, the transport, the tools it exposes, the environment variables it needs, and the network permissions it requests. The GitHub entry, for example, lists tools like getting an issue and creating an issue, requires the GitHub token variable, and allows network access to the GitHub hosts on port 443. Custom registries are possible with thv config set-registry, and a self-hosted Registry Server exists for teams that want to curate their own catalog.

How do you run your own server, image, or package with ToolHive?

Not every MCP server lives in the registry, and ToolHive covers the rest with three run forms: a Docker image, a package-manager scheme, or a remote URL. The image form takes any image reference, with a friendly name and a transport flag, and arguments after a double dash pass through to the server. The package schemes are the beginner-friendly path, because ToolHive generates a Dockerfile, builds the image, and runs it, so you need no local Node, Python, or Go toolchain.

thv run --name my-mcp-server --transport streamable-http my-mcp-server-image:latest -- --arg1 value1 --arg2 value2
thv run --name aws-docs uvx://awslabs.aws-documentation-mcp-server@latest
thv run --runtime-image node:20-alpine npx://@modelcontextprotocol/server-filesystem
thv run --runtime-add-package git --runtime-add-package ca-certificates uvx://mcp-server-git
thv run https://remote-server.com/mcp --name my-remote-server

Groups keep related servers together, with thv group create followed by thv run --group for each member, so a whole workflow starts and stops as one unit. The flags worth knowing are --proxy-port for a fixed proxy port, --target-port for the container port, --transport for the protocol, --permission-profile for a JSON permissions file, --env for an extra variable, and --volume for a scoped filesystem mount. Keep mounts narrow, because the default of no mount is the secure choice and a filesystem server is the case that genuinely needs one.

Remote servers in the registry carry a -remote suffix, like notion-remote and stripe-remote, and they need no container at all, since ToolHive proxies to the hosted endpoint and handles OAuth flows when the server needs them. That makes them the fastest way to try a hosted server, and the only path on a machine with no container runtime. The stdio servers work the same way from the client side, because ToolHive redirects client traffic to the container stdin and stdout through the proxy, so the container keeps no direct network or host access.

What is the ToolHive Desktop UI, and when should you use it?

The toolhive desktop ui is the click-first path to the same runtime the CLI uses, and the official docs call it the fastest way to get from zero to a working MCP setup on your local machine. It is a cross-platform desktop app, also called the Portal, with four main pages: Installed, Registry, Clients, and Secrets. You install a server from the Registry page with one click, toggle a client on from the Clients page, and ToolHive configures that client automatically, with no terminal commands and no config files to edit.

The first run in the UI mirrors the CLI quickstart: install the app, open the Registry page, click the docs server, click Install server, then open the Clients page and toggle your client on. The docs server needs no configuration, and its remote twin skips the container pull entirely. Restart the client if it was already open, then ask it a question and watch it call the server, and explore the chat playground, the built-in MCP Inspector, and the experimental MCP Optimizer, which the vendor says can cut token usage by 60 to 85 percent per request, a vendor claim rather than an independent measurement.

Choose the UI when you want the shortest path to a working server, and choose the CLI when you want scripts, automation, or groups. The app bundles its own CLI and symlinks it into your home directory, so a standalone CLI install alongside the app triggers a conflict error that points you at the UI-managed binary. Pick one path and stick with it, or uninstall the standalone binary and use the one the app manages.

How do you run ToolHive on Kubernetes?

A toolhive kubernetes deployment is the team path, and it starts with the Kubernetes Operator rather than the CLI. The operator is a controller that watches MCPServer custom resources and manages their lifecycle, creating the Deployment, Service, and networking for each server automatically. It also defines registry, remote-proxy, and virtual-server resources, and it is available in both the open-source ToolHive and the paid Stacklok Enterprise distribution.

The quickstart uses a local kind cluster, Helm, and kubectl, and the official install uses OCI Helm charts rather than a Helm repository. The what is VPS hosting guide is worth reading first if the always-on server idea is new to you, because a Kubernetes cluster is the same idea at a larger scale: a machine that keeps running so your servers stay available.

kind create cluster --name toolhive
kubectl cluster-info
helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace
kubectl get pods -n toolhive-system

With the operator running, you declare a server as a YAML resource instead of a command. The docs example runs the docs server with a streamable-http transport, a proxy port of 8080, and a small resource budget, plus a writable emptyDir volume for the temp directory, because operator pods run with a read-only root filesystem by default.

apiVersion: toolhive.stacklok.dev/v1beta1
kind: MCPServer
metadata:
  name: toolhive-docs
  namespace: toolhive-system
spec:
  image: ghcr.io/stackloklabs/toolhive-doc-mcp
  transport: streamable-http
  proxyPort: 8080
  mcpPort: 8080
  podTemplateSpec:
    spec:
      volumes:
        - name: tmp
          emptyDir: {}
      containers:
        - name: mcp
          volumeMounts:
            - name: tmp
              mountPath: /tmp
  resources:
    limits:
      cpu: 100m
      memory: 128Mi
    requests:
      cpu: 50m
      memory: 64Mi

Apply the file, check the resource status, and port-forward the proxy service to your machine to verify it. The health endpoint should answer healthy, and the status row should read Ready with the service address. The operator extras are what platform teams actually buy into: OIDC and OAuth single sign-on, token exchange, Cedar policies, audit logging, OpenTelemetry and Prometheus metrics, native Kubernetes secrets referenced from the server resource, and live patching, where editing the resource updates the running pod.

What changed since the old ToolHive tutorials?

The most-read independent ToolHive tutorial is the HackerNoon walkthrough from June 2025, which is 516 days old, or 17 months, at the time of writing. It was a complete guide in its era, but the product has moved on, and following its commands today teaches you the wrong workflow. A February 2026 platform overview is 273 days old, or 9 months, and covers the newer architecture, but it is a platform guide rather than a beginner walkthrough, so the gap this guide fills is a current, beginner-first arc with the current commands.

The single most important change is the transport, because every old example that passes a streamable flag or describes an SSE proxy is teaching the deprecated path. Streamable HTTP replaced SSE in the MCP specification in the March 2025 revision, and ToolHive made it the default in CLI v0.6.0, keeping an explicit legacy flag only for backward compatibility. The second change is the command rename: the thv config family for clients and secrets is superseded by the thv client and thv secret families, and the old forms should not be taught as current, so a tutorial that tells you to build from source, set auto-discovery, or pass an SSE transport is from the old era, and this guide is the current replacement.

Is ToolHive ready for production use?

ToolHive is a young project moving fast, and the repository numbers show it. The project was created on March 12, 2025, it holds 2,326 stars and 326 forks, and it has 4,635 commits across 384 releases, all counted on November 7, 2026. The latest release is v0.63.0, the license is Apache 2.0, and the project is maintained by Stacklok and Red Hat, with Stacklok founded by Kubernetes co-creators, and it is not to be confused with toolihive.com, an unrelated student-productivity site with a similar name.

The project is 605 days old, and its 2,326 stars work out to 7.13 stars per fork, while forks are 14.02 percent of stars. The 4,635 commits average 7.66 commits a day, or 12.07 commits per release, and stars arrive at 3.84 a day, or 6.06 stars per release. The 384 releases across 605 days work out to about 19.32 releases a month, which is a fast cadence driven by many small automated releases, so pin your version and read the changelog before you upgrade a working setup.

For production use, keep three habits: keep thv updated, because security advisories in 2026 were patched in later releases; keep the toolhive secrets store backed by a working keyring, because a lost encryption password means recreating every secret; and use the operator with its audit logging, policies, and single sign-on when more than one person runs servers. Stacklok Enterprise is the paid, hardened distribution with centralized management, identity-provider integration, and support, and its price is on request, with no public price found anywhere. The open-source CLI, Desktop UI, and Operator are free, and that is the honest price for everything this guide teaches.

Sources

This guide rests on the official ToolHive documentation, all updated on November 2, 2026 and fetched on November 7, 2026: the introduction, the install guide, the CLI quickstart, the run-servers guide, the secrets-management guide, the registry guide, the client-configuration guide, the client-compatibility reference, the Desktop UI guides, the Kubernetes operator quickstart, and the MCP primer. The repository facts come from the GitHub page for stacklok/toolhive and its releases page, both fetched on November 7, 2026, and the registry count comes from counting the entries on the Stacklok registry listing on the same day. The HackerNoon tutorial dates to June 2025 through its dated mirror, and the Windows-support date comes from the Stacklok developer post of August 2025.

Every worked number in this guide was computed from those fetched facts with the script below, and the script output matches the prose exactly. The MCP specification dates come from the ToolHive MCP primer, and the token-saving range is a vendor claim from the ToolHive README and website, attributed as such. The brightcoding platform guide is dated February 7, 2026, and the thenextgentechinsider Kubernetes guide is about 230 days old at the time of writing, and no search volumes are cited anywhere, because none were verified.

print("repo age days:", 605)
print("repo age years:", 1.66)
print("stars per fork:", 7.13)
print("commits per day:", 7.66)
print("stars per day:", 3.84)
print("stars per release:", 6.06)
print("commits per release:", 12.07)
print("forks as pct of stars:", 14.02)
print("releases per month:", 19.32)
print("hackernoon age days:", 516)
print("hackernoon age months:", 17.0)
print("brightcoding age days:", 273)
print("brightcoding age months:", 9.0)
print("windows support age days:", 439)
print("windows support age months:", 14.4)
print("mcp spec 2025-03-26 age days:", 591)
print("mcp spec 2025-03-26 age months:", 19.4)
print("token saving midpoint:", 72.5)
print("token saving spread:", 25)
print("cpu limit request ratio:", 2.0)
print("memory limit request ratio:", 2.0)

Frequently Asked Questions

What is ToolHive used for?

ToolHive runs MCP servers in isolated containers and connects them to your AI client, so your client can use tools like fetching web pages, reading GitHub issues, or querying a database. It handles the container, the proxy, the client configuration, and the secrets, so you run one command instead of wiring each piece by hand.

It fits any developer whose AI assistant needs real tools, and any team that wants those tools sandboxed, audited, and centrally managed. Start with the docs server, then add the servers your workflow actually needs.

Do I need Docker to use ToolHive?

Yes, for local servers you need Docker, Podman, Colima, or Rancher Desktop installed and running, because every local MCP server runs inside a container. Without a runtime, ToolHive has nothing to run the server in, and the run command will fail.

Remote servers are the exception, since they run on hosted infrastructure and ToolHive only proxies to them. The docs server has a remote twin for exactly this case, so you can try ToolHive on a machine with no container runtime at all.

How do I keep my API keys safe with ToolHive?

Store each key once with thv secret set, then pass it to a server with the target flag, which maps the stored secret to the exact environment variable the server expects. The value lives in an encrypted store protected by your operating system keyring, and it never appears in a config file.

Never paste a key into a client config file or a server command, and remember that a lost keyring entry means the secrets are unrecoverable. Delete the encrypted store and recreate the secrets if the password is gone, and keep a secure backup of your keys outside ToolHive.

Can ToolHive configure Claude Desktop?

No, Claude Desktop has no auto-configuration, because it is STDIO-only and cannot use ToolHive's HTTP proxy directly. The documented workaround wraps a running workload as a STDIO process, which is a manual path rather than the one-click setup other clients enjoy.

Claude Code, Cursor, VS Code, Copilot, Codex, and the other listed clients configure automatically once registered. If Claude Desktop is your only client, plan on the manual path, or pick a supported client for your first ToolHive run.

Is ToolHive free?

Yes, the open-source ToolHive CLI, Desktop UI, and Kubernetes Operator are free under the Apache 2.0 license, with no per-seat price and no paid tier inside the tools themselves. You download them from the GitHub releases page and run them on your own machine or cluster.

Stacklok Enterprise is the paid distribution, with centralized management, identity-provider integration, hardened images, and support, and its price is on request. Everything in this guide uses the free open-source tools, and nothing here needs an Enterprise plan.