From 9b071976dbcf6f606b1ff862c9dbd4d5b4d06fea Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 11 Jun 2026 22:53:41 -0400 Subject: [PATCH 1/4] Document authenticating to private build registries The custom package registries section covered setting plaintext build environment variables but not how to supply credentials. Add an 'Authenticate to private registries' subsection covering the --from-secret and --from-env flags on thv config set-build-env, which keep credentials out of the configuration file. Closes #359. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/build-containers.mdx | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/toolhive/guides-cli/build-containers.mdx b/docs/toolhive/guides-cli/build-containers.mdx index 58de5ebb..51010e9c 100644 --- a/docs/toolhive/guides-cli/build-containers.mdx +++ b/docs/toolhive/guides-cli/build-containers.mdx @@ -371,6 +371,47 @@ thv config set-build-env GOPRIVATE "github.com/mycompany/*" thv config set-build-env PIP_INDEX_URL https://pypi.corp.example.com/simple ``` +#### Authenticate to private registries + +Private registries usually require credentials such as an authentication token +or API key. Don't pass these as literal values, because literal values are +stored in plaintext in ToolHive's configuration file. Instead, supply the +credential from a [ToolHive secret](./secrets-management.mdx) or from the shell +environment so that only a reference is stored. ToolHive resolves the value at +build time and injects it into the builder stage of the multi-stage Docker +build, so the credential never appears in the final image. + +To reference a stored secret, use the `--from-secret` flag. Pass two positional +arguments: the environment variable name the package manager expects, followed +by the name of the secret. The `--from-secret` flag tells ToolHive to treat the +second argument as a secret reference rather than a literal value. The secret +must already exist; ToolHive validates it when you run the command: + +```bash +# Store the credential as a ToolHive secret (enter the value when prompted) +thv secret set artifactory-token + +# Reference it by name when setting the build environment variable +thv config set-build-env ARTIFACTORY_API_KEY --from-secret artifactory-token +``` + +To read the credential from the shell at build time, use the `--from-env` flag +with no value. ToolHive reads the variable of the same name from your +environment when you run `thv build`. This is useful in CI/CD pipelines that +inject credentials as environment variables: + +```bash +thv config set-build-env GITHUB_TOKEN --from-env +``` + +:::tip + +Use `thv config get-build-env` to review your configured build environment +variables. Secret-backed and shell-backed values are shown as references +(`` or ``), never as resolved values. + +::: + ### Build local Go projects Build MCP servers from local Go projects: From d68434093eb61332e0787888838c3a6442996f0a Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 12 Jun 2026 09:55:08 -0400 Subject: [PATCH 2/4] Document set-build-auth-file for credential files Add an 'Authenticate with a credential file' subsection covering thv config set-build-auth-file (npmrc/netrc/yarnrc), the --stdin input mode, the secrets-manager storage model, and the get/unset commands. Complements the set-build-env credential path and addresses the build-auth-file gap from #654. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/build-containers.mdx | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/toolhive/guides-cli/build-containers.mdx b/docs/toolhive/guides-cli/build-containers.mdx index 51010e9c..47896f98 100644 --- a/docs/toolhive/guides-cli/build-containers.mdx +++ b/docs/toolhive/guides-cli/build-containers.mdx @@ -412,6 +412,38 @@ variables. Secret-backed and shell-backed values are shown as references ::: +#### Authenticate with a credential file + +Some package managers read credentials from a configuration file instead of an +environment variable, such as `.npmrc` for npm or `.netrc` for pip and Go. Use +`thv config set-build-auth-file` to store one of these files and have ToolHive +inject it into the build. The supported file types are `npmrc`, `netrc`, and +`yarnrc`. + +Pass the file content as the second argument: + +```bash +thv config set-build-auth-file npmrc '//npm.corp.example.com/:_authToken=' +``` + +To avoid recording the credential in your shell history, read the content from +standard input with the `--stdin` flag instead: + +```bash +thv config set-build-auth-file npmrc --stdin < ~/.npmrc +``` + +ToolHive stores the file content in its secrets manager and keeps only a +reference in your configuration, so the credentials never appear in plaintext. +At build time, ToolHive resolves the file and injects it into the builder stage +of the multi-stage Docker build, not the final image. This requires a configured +secrets provider; see [Secrets management](./secrets-management.mdx) to set one +up. + +Review or remove configured files with `thv config get-build-auth-file` (which +hides content by default unless you pass `--show-content`) and +`thv config unset-build-auth-file`. + ### Build local Go projects Build MCP servers from local Go projects: From c06d4ab501efc1de4d3ea4e376bd3f3ecb188940 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 12 Jun 2026 10:40:14 -0400 Subject: [PATCH 3/4] Document runtime image build customization flags Add a 'Customize the runtime image' subsection covering --runtime-image and --runtime-add-package for protocol-scheme builds. Addresses the build customization gap from #654. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/build-containers.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/toolhive/guides-cli/build-containers.mdx b/docs/toolhive/guides-cli/build-containers.mdx index 47896f98..e2292d2e 100644 --- a/docs/toolhive/guides-cli/build-containers.mdx +++ b/docs/toolhive/guides-cli/build-containers.mdx @@ -331,6 +331,23 @@ thv build uvx://internal-mcp-server thv build --ca-cert /path/to/special-ca.crt uvx://special-server ``` +### Customize the runtime image + +Protocol-scheme builds use a default base image for each language. To override +it, use `--runtime-image`: + +```bash +thv build --runtime-image node:20-alpine npx://@modelcontextprotocol/server-filesystem +``` + +To install additional OS packages into the builder and runtime stages, use +`--runtime-add-package`. Repeat the flag for multiple packages: + +```bash +thv build --runtime-add-package git --runtime-add-package ca-certificates \ + uvx://mcp-server-git +``` + ### Custom package registries Enterprise environments often use private package registries or mirrors instead From 288df6a57aaece2b1d232df4600288c4bb588547 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 12 Jun 2026 10:50:33 -0400 Subject: [PATCH 4/4] Revert "Document runtime image build customization flags" This reverts commit c06d4ab501efc1de4d3ea4e376bd3f3ecb188940. --- docs/toolhive/guides-cli/build-containers.mdx | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/docs/toolhive/guides-cli/build-containers.mdx b/docs/toolhive/guides-cli/build-containers.mdx index e2292d2e..47896f98 100644 --- a/docs/toolhive/guides-cli/build-containers.mdx +++ b/docs/toolhive/guides-cli/build-containers.mdx @@ -331,23 +331,6 @@ thv build uvx://internal-mcp-server thv build --ca-cert /path/to/special-ca.crt uvx://special-server ``` -### Customize the runtime image - -Protocol-scheme builds use a default base image for each language. To override -it, use `--runtime-image`: - -```bash -thv build --runtime-image node:20-alpine npx://@modelcontextprotocol/server-filesystem -``` - -To install additional OS packages into the builder and runtime stages, use -`--runtime-add-package`. Repeat the flag for multiple packages: - -```bash -thv build --runtime-add-package git --runtime-add-package ca-certificates \ - uvx://mcp-server-git -``` - ### Custom package registries Enterprise environments often use private package registries or mirrors instead