Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/upstream-projects.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ projects:

- id: toolhive
repo: stacklok/toolhive
version: v0.55.0
version: v0.55.2
# toolhive is a monorepo covering the CLI, the Kubernetes
# operator, and the vMCP gateway. It also introduces cross-
# cutting features that land in concepts/, integrations/,
Expand Down
33 changes: 22 additions & 11 deletions docs/toolhive/guides-cli/network-isolation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -351,20 +351,31 @@ server.
To allow an MCP server to access other workloads on the same network, configure
outbound network isolation to include the appropriate hostnames and ports.

**Reaching the host with `host.docker.internal`**
**Reaching the host machine**

`host.docker.internal` is a Docker Desktop hostname that resolves to the host
machine's IP address. Docker gateway addresses are blocked by an explicit deny
in the egress proxy by default, even when `insecure_allow_all` is set. Pass the
`--allow-docker-gateway` flag to grant access to `host.docker.internal`,
`gateway.docker.internal`, and the gateway IP of every bridge network on the
machine's IP address, and `host.containers.internal` is its Podman equivalent.
The egress proxy blocks host gateway addresses with an explicit deny by default,
even when `insecure_allow_all` is set. Pass the `--allow-docker-gateway` flag to
grant access to `host.docker.internal`, `gateway.docker.internal`,
`host.containers.internal`, and the gateway IP of every bridge network on the
container runtime (typically `172.17.0.1` on Linux, `192.168.65.1` on Docker
Desktop). The flag alone is enough: you do not need to add the gateway hostname
or IP to `allow_host`.

ToolHive discovers the bridge gateway IPs when it deploys the MCP server. If you
create a new bridge network afterward, remove the MCP server with `thv rm` and
run it again so the egress proxy picks up the new gateway.
Desktop). On Podman, the flag also covers every address that the runtime maps to
those hostnames, which includes the host-access address used by rootless Podman.
The flag alone is enough: you do not need to add the gateway hostname or IP to
`allow_host`.

ToolHive discovers these addresses when it deploys the MCP server. If you create
a new bridge network afterward, or change Podman's host mappings or rootless
networking mode, remove the MCP server with `thv rm` and run it again so the
egress proxy picks up the new addresses.

On Podman, ToolHive reads the host mappings from the `/etc/hosts` file that the
runtime generates for its DNS sidecar container. If that file has no
`host.containers.internal` entry (for example, because `no_hosts = true` is set
in `containers.conf`), or ToolHive can't read it, network-isolated deployments
fail before the MCP server starts, whether or not you pass
`--allow-docker-gateway`.

Gateway access granted by `--allow-docker-gateway` is intentionally
port-independent. It bypasses the permission profile's `allow_port` list so that
Expand Down
18 changes: 10 additions & 8 deletions docs/toolhive/guides-ui/network-isolation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -107,10 +107,11 @@ purposes; the form displays a warning in this case.

### Allowing host machine access

When a server runs behind the HTTP proxy, ToolHive blocks connections to Docker
gateway addresses (`host.docker.internal`, `gateway.docker.internal`, and the
Docker bridge gateway IP) by default, even when you allow all destinations.
Reaching the host machine is a separate, more privileged opt-in.
When a server runs behind the HTTP proxy, ToolHive blocks connections to host
gateway addresses (`host.docker.internal`, `gateway.docker.internal`,
`host.containers.internal`, the bridge gateway IPs, and on Podman, any address
the runtime maps to those hostnames) by default, even when you allow all
destinations. Reaching the host machine is a separate, more privileged opt-in.

Enable **Allow host machine access** to let the server connect to these gateway
addresses. Turn this on when your MCP server needs to reach a service running on
Expand Down Expand Up @@ -143,10 +144,11 @@ such as databases, APIs, or other local servers.

To reach a service on your **host machine**, enable
[**Allow host machine access**](#allowing-host-machine-access). The server can
then connect to `host.docker.internal` (on macOS and Windows) or the Docker
bridge gateway IP (typically `172.17.0.1` on Linux) on any port. Because these
gateway addresses are blocked by default, adding them to the allowed hosts list
alone is not enough; you must enable this option.
then connect to `host.docker.internal` (Docker Desktop on macOS and Windows),
`host.containers.internal` (Podman), or the Docker bridge gateway IP (typically
`172.17.0.1` on Linux) on any port. Because these gateway addresses are blocked
by default, adding them to the allowed hosts list alone is not enough; you must
enable this option.

To reach a service that is **not** on the host machine, add its hostname and
port to the allowed hosts and ports under **Selected destinations**, as
Expand Down
2 changes: 1 addition & 1 deletion docs/toolhive/reference/cli/thv_run.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...]
### Options

```
--allow-docker-gateway Allow outbound connections to Docker gateway addresses (all daemon bridge gateways, host.docker.internal, and gateway.docker.internal). Only applies when --isolate-network is set. Gateways are snapshotted at deployment; redeploy to include bridges created later. These are blocked by default even when insecure_allow_all is enabled. Gateway access is port-independent: it ignores the permission profile's allowed ports, so once enabled the gateway is reachable on any port.
--allow-docker-gateway Allow outbound connections to Docker/Podman host addresses (all daemon bridge gateways, runtime host-alias IPs, host.docker.internal, gateway.docker.internal, and host.containers.internal). Only applies when --isolate-network is set. Addresses are snapshotted at deployment; redeploy after runtime network changes. These are blocked by default even when insecure_allow_all is enabled. Gateway access is port-independent: it ignores the permission profile's allowed ports, so once enabled the gateway is reachable on any port.
--allowed-origins stringArray Exact-match allowlist for the HTTP Origin header (repeatable). Recommended when binding publicly; loopback binds derive a default allowlist automatically, non-loopback binds log a warning when no value is supplied. Example: https://my-mcp.example.com
--audit-config string Path to the audit configuration file
--authz-config string Path to the authorization configuration file
Expand Down
6 changes: 3 additions & 3 deletions docs/toolhive/reference/helm/operator-crds.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ Control CRD installation and preservation with these Helm values.
This reference lists values declared in the chart's default `values.yaml`.
Templates can also accept optional settings and inherited `global` values.

Chart: `toolhive-operator-crds`. Chart version: `0.55.0`. Source:
[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.55.0/deploy/charts/operator-crds/values.yaml)
at `v0.55.0`.
Chart: `toolhive-operator-crds`. Chart version: `0.55.2`. Source:
[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.55.2/deploy/charts/operator-crds/values.yaml)
at `v0.55.2`.

## Values

Expand Down
18 changes: 9 additions & 9 deletions docs/toolhive/reference/helm/operator.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ Configure the ToolHive operator with these Helm values.
This reference lists values declared in the chart's default `values.yaml`.
Templates can also accept optional settings and inherited `global` values.

Chart: `toolhive-operator`. Chart version: `0.55.0`. Source:
[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.55.0/deploy/charts/operator/values.yaml)
at `v0.55.0`.
Chart: `toolhive-operator`. Chart version: `0.55.2`. Source:
[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.55.2/deploy/charts/operator/values.yaml)
at `v0.55.2`.

## Values

Expand Down Expand Up @@ -68,7 +68,7 @@ features:
gc:
gogc: 75
gomemlimit: 110MiB
image: ghcr.io/stacklok/toolhive/operator:v0.55.0
image: ghcr.io/stacklok/toolhive/operator:v0.55.2
imageDiscovery:
enabled: false
resources: {}
Expand Down Expand Up @@ -153,8 +153,8 @@ serviceAccount:
labels: {}
name: toolhive-operator
tolerations: []
toolhiveRunnerImage: ghcr.io/stacklok/toolhive/proxyrunner:v0.55.0
vmcpImage: ghcr.io/stacklok/toolhive/vmcp:v0.55.0
toolhiveRunnerImage: ghcr.io/stacklok/toolhive/proxyrunner:v0.55.2
vmcpImage: ghcr.io/stacklok/toolhive/vmcp:v0.55.2
volumeMounts: []
volumes: []
```
Expand Down Expand Up @@ -255,7 +255,7 @@ Key containing the password in `existingSecret`. When empty, uses

**Type:** `string`

**Default:** `"ghcr.io/stacklok/toolhive/operator:v0.55.0"`
**Default:** `"ghcr.io/stacklok/toolhive/operator:v0.55.2"`

Container image for the operator.

Expand All @@ -271,15 +271,15 @@ Image pull policy for the operator container and image-discovery containers.

**Type:** `string`

**Default:** `"ghcr.io/stacklok/toolhive/proxyrunner:v0.55.0"`
**Default:** `"ghcr.io/stacklok/toolhive/proxyrunner:v0.55.2"`

Container image for ToolHive proxy runners created by the operator.

### `operator.vmcpImage`

**Type:** `string`

**Default:** `"ghcr.io/stacklok/toolhive/vmcp:v0.55.0"`
**Default:** `"ghcr.io/stacklok/toolhive/vmcp:v0.55.2"`

Container image for Virtual MCP Server (vMCP) deployments created by the
operator.
Expand Down
Loading