From c597ec106a373fb327456107b08c8ac6e80ad566 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 27 Mar 2026 18:48:11 +0000 Subject: [PATCH] Update ToolHive reference docs for v0.13.1 --- docs/toolhive/reference/cli/thv_run.md | 1 + docs/toolhive/reference/crd-spec.md | 29 ++++++++++++++++++++++---- static/api-specs/toolhive-api.yaml | 14 +++++++++++++ 3 files changed, 40 insertions(+), 4 deletions(-) diff --git a/docs/toolhive/reference/cli/thv_run.md b/docs/toolhive/reference/cli/thv_run.md index a308e589..d0e94e01 100644 --- a/docs/toolhive/reference/cli/thv_run.md +++ b/docs/toolhive/reference/cli/thv_run.md @@ -111,6 +111,7 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...] ### Options ``` + --allow-docker-gateway Allow outbound connections to Docker gateway addresses (host.docker.internal, gateway.docker.internal, 172.17.0.1). Only applies when --isolate-network is set. These are blocked by default even when insecure_allow_all is enabled. --audit-config string Path to the audit configuration file --authz-config string Path to the authorization configuration file --ca-cert string Path to a custom CA certificate file to use for container builds diff --git a/docs/toolhive/reference/crd-spec.md b/docs/toolhive/reference/crd-spec.md index c7d8e37f..386a9899 100644 --- a/docs/toolhive/reference/crd-spec.md +++ b/docs/toolhive/reference/crd-spec.md @@ -281,6 +281,7 @@ _Appears in:_ | `telemetry` _[pkg.telemetry.Config](#pkgtelemetryconfig)_ | Telemetry configures OpenTelemetry-based observability for the Virtual MCP server
including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint. | | Optional: \{\}
| | `audit` _[pkg.audit.Config](#pkgauditconfig)_ | Audit configures audit logging for the Virtual MCP server.
When present, audit logs include MCP protocol operations.
See audit.Config for available configuration options. | | Optional: \{\}
| | `optimizer` _[vmcp.config.OptimizerConfig](#vmcpconfigoptimizerconfig)_ | Optimizer configures the MCP optimizer for context optimization on large toolsets.
When enabled, vMCP exposes only find_tool and call_tool operations to clients
instead of all backend tools directly. This reduces token usage by allowing
LLMs to discover relevant tools on demand rather than receiving all tool definitions. | | Optional: \{\}
| +| `sessionStorage` _[vmcp.config.SessionStorageConfig](#vmcpconfigsessionstorageconfig)_ | SessionStorage configures session storage for stateful horizontal scaling.
When provider is "redis", the operator injects Redis connection parameters
(address, db, keyPrefix) here. The Redis password is provided separately via
the THV_SESSION_REDIS_PASSWORD environment variable. | | Optional: \{\}
| #### vmcp.config.ConflictResolutionConfig @@ -502,6 +503,27 @@ _Appears in:_ | `default` _[pkg.json.Any](#pkgjsonany)_ | Default is the fallback value if template expansion fails.
Type coercion is applied to match the declared Type. | | Schemaless: \{\}
Optional: \{\}
| +#### vmcp.config.SessionStorageConfig + + + +SessionStorageConfig configures session storage for stateful horizontal scaling. +The Redis password is not stored here; it is injected as the THV_SESSION_REDIS_PASSWORD +environment variable by the operator when spec.sessionStorage.passwordRef is set. + + + +_Appears in:_ +- [vmcp.config.Config](#vmcpconfigconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `provider` _string_ | Provider is the session storage backend type. | | Enum: [memory redis]
Required: \{\}
| +| `address` _string_ | Address is the Redis server address (required when provider is redis). | | Optional: \{\}
| +| `db` _integer_ | DB is the Redis database number. | 0 | Minimum: 0
Optional: \{\}
| +| `keyPrefix` _string_ | KeyPrefix is an optional prefix for all Redis keys used by ToolHive. | | Optional: \{\}
| + + #### vmcp.config.StaticBackendConfig @@ -991,6 +1013,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `issuer` _string_ | Issuer is the issuer identifier for this authorization server.
This will be included in the "iss" claim of issued tokens.
Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash (per RFC 8414). | | Pattern: `^https?://[^\s?#]+[^/\s?#]$`
Required: \{\}
| +| `authorizationEndpointBaseUrl` _string_ | AuthorizationEndpointBaseURL overrides the base URL used for the authorization_endpoint
in the OAuth discovery document. When set, the discovery document will advertise
`\{authorizationEndpointBaseUrl\}/oauth/authorize` instead of `\{issuer\}/oauth/authorize`.
All other endpoints (token, registration, JWKS) remain derived from the issuer.
This is useful when the browser-facing authorization endpoint needs to be on a
different host than the issuer used for backend-to-backend calls.
Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash. | | Pattern: `^https?://[^\s?#]+[^/\s?#]$`
Optional: \{\}
| | `signingKeySecretRefs` _[api.v1alpha1.SecretKeyRef](#apiv1alpha1secretkeyref) array_ | SigningKeySecretRefs references Kubernetes Secrets containing signing keys for JWT operations.
Supports key rotation by allowing multiple keys (oldest keys are used for verification only).
If not specified, an ephemeral signing key will be auto-generated (development only -
JWTs will be invalid after restart). | | MaxItems: 5
Optional: \{\}
| | `hmacSecretRefs` _[api.v1alpha1.SecretKeyRef](#apiv1alpha1secretkeyref) array_ | HMACSecretRefs references Kubernetes Secrets containing symmetric secrets for signing
authorization codes and refresh tokens (opaque tokens).
Current secret must be at least 32 bytes and cryptographically random.
Supports secret rotation via multiple entries (first is current, rest are for verification).
If not specified, an ephemeral secret will be auto-generated (development only -
auth codes and refresh tokens will be invalid after restart). | | Optional: \{\}
| | `tokenLifespans` _[api.v1alpha1.TokenLifespanConfig](#apiv1alpha1tokenlifespanconfig)_ | TokenLifespans configures the duration that various tokens are valid.
If not specified, defaults are applied (access: 1h, refresh: 7d, authCode: 10m). | | Optional: \{\}
| @@ -2698,10 +2721,8 @@ SessionStorageConfig defines session storage configuration for horizontal scalin This is the CRD/K8s-aware surface: it uses SecretKeyRef for secret resolution. The reconciler resolves PasswordRef to a plain string and builds a session.RedisConfig (pkg/transport/session) for the actual storage backend. - -vMCP process receives session storage config through the existing config injection -path (same as Optimizer and Audit). The CRD type will remain separate because -PasswordRef is K8s-specific and gets resolved away before the config-pkg type. +The operator also populates pkg/vmcp/config.SessionStorageConfig (without PasswordRef) +into the vMCP ConfigMap so the vMCP process receives connection parameters at startup. diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml index 014ebe85..6a2a3f65 100644 --- a/static/api-specs/toolhive-api.yaml +++ b/static/api-specs/toolhive-api.yaml @@ -429,6 +429,13 @@ components: type: string type: array uniqueItems: false + authorization_endpoint_base_url: + description: |- + AuthorizationEndpointBaseURL overrides the base URL used for the authorization_endpoint + in the OAuth discovery document. When set, the discovery document will advertise + `{authorization_endpoint_base_url}/oauth/authorize` instead of `{issuer}/oauth/authorize`. + All other endpoints remain derived from the issuer. + type: string hmac_secret_files: description: |- HMACSecretFiles contains file paths to HMAC secrets for signing authorization codes @@ -869,6 +876,13 @@ components: type: object github_com_stacklok_toolhive_pkg_runner.RunConfig: properties: + allow_docker_gateway: + description: |- + AllowDockerGateway permits outbound connections to Docker gateway addresses + (host.docker.internal, gateway.docker.internal, 172.17.0.1). These are + blocked by default in the egress proxy even when InsecureAllowAll is set. + Only applicable to Docker deployments with network isolation enabled. + type: boolean audit_config: $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_audit.Config' audit_config_path: