Upgrade notes: what changes for existing installations
This page lists what an upgrade changes for an installation that is already running, and what to do about it. The release notes on GitHub list every change of every release.
Upgrading to v0.6.0
Section titled “Upgrading to v0.6.0”ToolMesh v0.6.0 takes the credentials out of .env: the new credential store command keeps them in memory only. The release has a security focus throughout. It binds every REST backend to the credentials and hosts of its entry in backends.yaml, makes the OAuth login page name where an authorization goes, and checks tokens against the current user configuration. Some of these changes need a line of configuration on an existing installation, so read this section before upgrading from 0.5.x. The v0.6.0 release notes link the security advisory.
Checklist
Section titled “Checklist”- Start v0.6.0, search the log for
backend refusedand add thecredentials:orallowed_hosts:lines it names to the entries inbackends.yaml. Give every REST entry aname. - Behind a reverse proxy that is not on the same host, set
TOOLMESH_TRUSTED_PROXIESto the proxy’s own address, not to the network it shares with ToolMesh. - Make scripted logins send
confirm_host, and considerTOOLMESH_OAUTH_REDIRECT_HOSTS. - Set
TOOLMESH_ISSUERto the public URL clients use, if it still has its default. - Check gate policies that compare DADL parameters with strings such as
"false": they now see the declared type. - Update dashboards and alerts that select a backend whose name contains
_by its shortenedbackendlabel (see Full backend names in audit, telemetry and metrics). - If you suspect a session was misused, revoke its tokens or clear the stored tokens, then change the password (see Tokens from before the upgrade).
Credentials out of .env, optional
Section titled “Credentials out of .env, optional”The new credential store command (CREDENTIAL_STORE=command) runs a command such as sops -d or vault kv get and keeps what it prints in memory only, out of .env, the container environment and the log. With ergosum, the key that opens the credentials is released only on the machine it is bound to. Stdio backends then receive only the variables their new credential_env entry names. See Credential stores.
The store is optional. Without CREDENTIAL_STORE=command, the embedded store reads CREDENTIAL_* from the environment as before, and there is nothing to change. The credential and host binding below applies with either store.
Backends can be refused at load
Section titled “Backends can be refused at load”A REST backend reads only the credentials in the namespace of its entry, CREDENTIAL_<ENTRY>_*, where the longest matching entry name owns a credential, plus what the entry lists in env: or the new credentials: field. It sends credentials, token requests and session logins only to the host and port of its base_url, other hosts of the same registrable domain on the default port, and the hosts in the new allowed_hosts: field; an https base_url stays on https. A backend whose DADL reaches further is refused when it is loaded, at startup and on every reload, and the log line backend refused names the exact lines to add. The other backends keep running.
DADLs with credential names other than letters, digits and _, with a parameter default credential:<name>, or with a placeholder in the scheme, host or port of an absolute tool path are refused when they are parsed; such a DADL needs a change to the file itself. REST entries without a name are refused. See Credential and host binding.
The login page asks for a confirmation
Section titled “The login page asks for a confirmation”The OAuth login page names the client and the host of its redirect URI and requires the user to tick a confirmation for that host. Scripted logins must send confirm_host=<redirect host>. TOOLMESH_OAUTH_REDIRECT_HOSTS optionally restricts the redirect hosts, for example to claude.ai,claude.com. Redirect URIs with a fragment, without a host or with a non-ASCII host are refused; clients registered with such a URI register again. See The login page.
Tokens follow the current user configuration
Section titled “Tokens follow the current user configuration”Every refresh and every access token is checked against the users as loaded at startup. After a restart, removed users lose access at once, running sessions included, and changed roles and plans apply to existing tokens; in single-password mode, changing TOOLMESH_AUTH_USER ends existing sessions. A password change ends the user’s sessions. POST /revoke revokes a token pair. A refresh token is refused once its seven days are over; neither its Redis key nor the warm-up after a restart extends its lifetime any more. Changes to users.yaml still take effect only after a restart.
Tokens issued before the upgrade are bound to the password at their next refresh, so a password change made after the upgrade does not end them yet. See Tokens from before the upgrade for how to end such sessions.
Client address from trusted proxies only
Section titled “Client address from trusted proxies only”X-Forwarded-For is honored only from the addresses in TOOLMESH_TRUSTED_PROXIES, by default loopback only. Behind a reverse proxy in another container, on another machine or behind a CDN, list the proxy’s address. Until then all clients share the proxy’s address for the login, registration and API key limits, and ToolMesh logs a warning about it. For a proxy container, give it a fixed address in the Compose network and list that address alone, not the network: the network’s gateway belongs to it, and with Docker Desktop, rootless Docker or a userland proxy, direct connections to ToolMesh’s published port come from that gateway. Once a proxy container stands in front of ToolMesh, publish ToolMesh’s port on 127.0.0.1 only, or not at all. Behind a trusted proxy, entries with a port (203.0.113.7:51234, [2001:db8::7]:51234) or in brackets are read as the client address; an entry that is no address (unknown, empty) ends the evaluation at the last trusted proxy. See Client address and Proxy in a container.
Failed API keys are throttled
Section titled “Failed API keys are throttled”After 50 failed bearer credentials from one client address within the login window (TOOLMESH_APIKEY_MAX_FAILURES_PER_IP), further credentials from that address get 429 for the rest of the window, a correct key included. See API key throttling.
DADL arguments are checked before the policies run
Section titled “DADL arguments are checked before the policies run”Arguments of REST tools are checked against their declared types before the gate. "true" or "false" as strings for a boolean, fractions or non-numeric strings for an integer, and scalars for arrays or objects are refused with invalid_input. Numeric strings for numeric parameters are sent as numbers ("007" becomes 7), and policies see DADL defaults filled in. A number or boolean for a parameter declared string reaches the policies as exactly the text the API receives, also in a JSON body ("42", not 42); arrays, objects and other values without a text form are refused for such parameters with invalid_input. See What policies see.
Only the statuses in retry_on are retried
Section titled “Only the statuses in retry_on are retried”A REST call is retried only when its status is listed in the DADL’s retry_on, as the DADL specification (§8) requires. Until now every 5xx was retried. Most published DADLs list [429, 502, 503, 504], so a 500 is no longer retried. A DADL that wants a 500 retried lists it in retry_on. A tool with its own errors block needs its own retry_on, because that block replaces the defaults of the backend.
Full backend names in audit, telemetry and metrics
Section titled “Full backend names in audit, telemetry and metrics”Backends with an underscore in their name, such as web_search, appear in the audit trail, in telemetry and in the metrics toolmesh_tool_calls_total and toolmesh_tool_call_duration_seconds with their full name. Until now the name was cut at the first underscore (web). Dashboards and alerts that select such a backend by the shortened backend label need the full name. Tools that no backend claims are counted under the backend unknown.
Requests stay where the configuration points
Section titled “Requests stay where the configuration points”- Redirects to another origin drop credentials, custom headers, the
Refererand session cookies, never go from https to http, and do not send a request body again. - OAuth token and session login requests follow no redirects.
- Path parameter values
.and..are refused. - Transport errors name only scheme and host.
file_url_allowed_hostsin abackends.yamlentry, which limits the hosts that caller-suppliedfile_urlvalues are fetched from, applies to every redirect of such a fetch, not only to the URL the caller passes. If an allowed source redirects to a CDN or storage host, add that host to the list.- MCP backends over HTTP stay on the origin of their configured URL: a redirect or a legacy SSE endpoint pointing elsewhere is refused.
See Requests to REST backends and MCP backends over HTTP.
Private addresses
Section titled “Private addresses”With allow_private_url, private addresses are reachable only at the destinations the configuration names (base_url, token_url, absolute tool paths), not as redirect targets. Without it, carrier-grade NAT addresses (including Tailscale addresses), benchmarking, documentation, multicast, reserved, NAT64 and 6to4 ranges count as private too. IPv6 addresses with a zone suffix and a base_url on the unspecified address are refused.
Smaller changes
Section titled “Smaller changes”- Blobs can be deleted only by the user who created them (File broker).
execute_coderuns at mostTOOLMESH_CODE_MAX_CONCURRENTscripts at once (default 16), one user at most half of them. Further runs wait up to 10 seconds, then fail (Code Mode).- Without Redis,
/registeris limited per client address, per process. TOOLMESH_ISSUERdefaults tohttps://toolmesh.invalid/when unset; set it to the public URL clients use.