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.65.0
version: v0.66.0
# 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
28 changes: 28 additions & 0 deletions docs/toolhive/guides-cli/filesystem-access.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,34 @@ thv run --permission-profile ./file-permissions.json <SERVER>
For more details on permission profiles and network permissions, see
[custom permissions](./custom-permissions.mdx).

## Make the container's root file system read-only

By default, an MCP server can write anywhere inside its own container, including
its image's files. To stop a compromised or misbehaving server from modifying
its own image layer, add the `--read-only-rootfs` flag:

```bash
thv run --read-only-rootfs fetch
```

With this flag, ToolHive mounts the container's root file system as read-only.
The server can still write to:

- The volumes you mount with `--volume` (unless you add `:ro`) and the `write`
paths in its permission profile.
- `/tmp`, `/var/tmp`, and `/run`, which each get a 64 MiB scratch space in
memory (a tmpfs). Files written there can't be executed and don't persist when
the container stops. If a volume already targets one of these paths, ToolHive
uses the volume instead.

A server that writes anywhere else fails with a read-only file system error. To
fix this, mount a writable volume at the path the server needs, or run it
without the flag.

The flag applies to Docker and Podman. In Kubernetes, the operator runs MCP
server containers with a read-only root file system by default; see
[Mount a volume](../guides-k8s/run-mcp-k8s.mdx#mount-a-volume).

## Examples

These examples use the Filesystem and Memory MCP servers from the ToolHive
Expand Down
1 change: 1 addition & 0 deletions docs/toolhive/reference/cli/thv_run.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,7 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...]
--proxy-port int Port for the HTTP proxy to listen on (host port)
--proxy-read-timeout duration Maximum time to read a full request on the proxy (e.g., 30s, 1m); zero uses the default (30s)
-p, --publish stringArray Publish a container's port(s) to the host (format: hostPort:containerPort)
--read-only-rootfs[=true|false] Mount the MCP server container's root filesystem as read-only (Docker/Podman only). /tmp, /var/tmp and /run get a 64 MiB noexec tmpfs unless a volume already targets them; servers that write anywhere else outside their mounted volumes will fail.
--remote-auth[=true|false] Enable OAuth/OIDC authentication to remote MCP server (default false)
--remote-auth-authorize-url string OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)
--remote-auth-bearer-token string Bearer token for remote server authentication (alternative to OAuth)
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.65.0`. Source:
[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.65.0/deploy/charts/operator-crds/values.yaml)
at `v0.65.0`.
Chart: `toolhive-operator-crds`. Chart version: `0.66.0`. Source:
[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.66.0/deploy/charts/operator-crds/values.yaml)
at `v0.66.0`.

## Values

Expand Down
24 changes: 13 additions & 11 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.65.0`. Source:
[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.65.0/deploy/charts/operator/values.yaml)
at `v0.65.0`.
Chart: `toolhive-operator`. Chart version: `0.66.0`. Source:
[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.66.0/deploy/charts/operator/values.yaml)
at `v0.66.0`.

## Values

Expand Down Expand Up @@ -73,7 +73,7 @@ features:
gc:
gogc: 75
gomemlimit: 110MiB
image: ghcr.io/stacklok/toolhive/operator:v0.65.0
image: ghcr.io/stacklok/toolhive/operator:v0.66.0
imageDiscovery:
enabled: false
resources: {}
Expand Down Expand Up @@ -158,8 +158,8 @@ serviceAccount:
labels: {}
name: toolhive-operator
tolerations: []
toolhiveRunnerImage: ghcr.io/stacklok/toolhive/proxyrunner:v0.65.0
vmcpImage: ghcr.io/stacklok/toolhive/vmcp:v0.65.0
toolhiveRunnerImage: ghcr.io/stacklok/toolhive/proxyrunner:v0.66.0
vmcpImage: ghcr.io/stacklok/toolhive/vmcp:v0.66.0
volumeMounts: []
volumes: []
```
Expand Down Expand Up @@ -318,7 +318,7 @@ Key containing the PEM-encoded CA certificate in the Secret.

**Type:** `string`

**Default:** `"ghcr.io/stacklok/toolhive/operator:v0.65.0"`
**Default:** `"ghcr.io/stacklok/toolhive/operator:v0.66.0"`

Container image for the operator.

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

**Type:** `string`

**Default:** `"ghcr.io/stacklok/toolhive/proxyrunner:v0.65.0"`
**Default:** `"ghcr.io/stacklok/toolhive/proxyrunner:v0.66.0"`

Container image for ToolHive proxy runners created by the operator.

### `operator.vmcpImage`

**Type:** `string`

**Default:** `"ghcr.io/stacklok/toolhive/vmcp:v0.65.0"`
**Default:** `"ghcr.io/stacklok/toolhive/vmcp:v0.66.0"`

Container image for Virtual MCP Server (vMCP) deployments created by the
operator.
Expand Down Expand Up @@ -393,8 +393,10 @@ workloads.

Additional environment variables for the operator container. Chart-managed
variables take precedence for duplicate names. Set `TOOLHIVE_SKIP_UPDATE_CHECK`
to `"true"` to disable periodic update checks and the usage metrics collected
with them.
to `"true"` to disable update checks and anonymous usage metrics, or
`TOOLHIVE_USAGE_METRICS_ENABLED` to `"false"` to disable usage metrics only. The
operator passes either setting to every MCPServer, MCPRemoteProxy and
VirtualMCPServer it deploys; changing it rolls out those workloads once.

### `operator.ports`

Expand Down
17 changes: 17 additions & 0 deletions static/api-specs/toolhive-api.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2260,6 +2260,13 @@ components:
description: RateLimitNamespace is the Kubernetes namespace for Redis key
derivation.
type: string
read_only_rootfs:
description: |-
ReadOnlyRootfs mounts the MCP server container's root filesystem as read-only.
/tmp, /var/tmp and /run get a small noexec tmpfs unless a volume targets them.
Opt-in: servers that write anywhere else outside their mounted volumes will fail.
Only applicable to Docker/Podman deployments.
type: boolean
registry_api_url:
description: |-
RegistryAPIURL is the registry API URL that served this server's metadata.
Expand Down Expand Up @@ -3529,6 +3536,11 @@ components:
Empty or zero uses the default timeout of 30 seconds.
example: 30s
type: string
read_only_rootfs:
description: |-
Whether to mount the container's root filesystem as read-only.
Only applicable to Docker/Podman deployments.
type: boolean
registry:
description: Registry is the optional registry name to resolve the server
from (e.g. "default").
Expand Down Expand Up @@ -4303,6 +4315,11 @@ components:
Empty or zero uses the default timeout of 30 seconds.
example: 30s
type: string
read_only_rootfs:
description: |-
Whether to mount the container's root filesystem as read-only.
Only applicable to Docker/Podman deployments.
type: boolean
runtime_config:
$ref: '#/components/schemas/templates.RuntimeConfig'
secrets:
Expand Down
Loading