# Upgrade notes: what changes for existing installations

> What to check when upgrading ToolMesh: in v0.6.0 the optional command credential store, backends bound to their credentials and hosts, a login confirmation, trusted proxies.

Canonical: https://www.toolmesh.io/en/upgrading/

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](https://github.com/DunkelCloud/ToolMesh/releases) list every change of every release.

## 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](https://github.com/DunkelCloud/ToolMesh/releases/tag/v0.6.0) link the security advisory.

### Checklist

1. Start v0.6.0, search the log for `backend refused` and add the `credentials:` or `allowed_hosts:` lines it names to the entries in `backends.yaml`. Give every REST entry a `name`.
2. Behind a reverse proxy that is not on the same host, set `TOOLMESH_TRUSTED_PROXIES` to the proxy's own address, not to the network it shares with ToolMesh.
3. Make scripted logins send `confirm_host`, and consider `TOOLMESH_OAUTH_REDIRECT_HOSTS`.
4. Set `TOOLMESH_ISSUER` to the public URL clients use, if it still has its default.
5. Check gate policies that compare DADL parameters with strings such as `"false"`: they now see the declared type.
6. Update dashboards and alerts that select a backend whose name contains `_` by its shortened `backend` label (see [Full backend names in audit, telemetry and metrics](#full-backend-names-in-audit-telemetry-and-metrics)).
7. 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](/en/authentication/#tokens-from-before-the-upgrade)).

### 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](https://github.com/DunkelCloud/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](/en/configuration/#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

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](/en/configuration/#credential-and-host-binding).

### 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](/en/authentication/#the-login-page).

### 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](/en/authentication/#tokens-from-before-the-upgrade) for how to end such sessions.

### 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](/en/authentication/#client-address) and [Proxy in a container](/en/authentication/#proxy-in-a-container).

### 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](/en/authentication/#api-key-throttling).

### 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](/en/output-gate/#what-policies-see).

### 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](https://dadl.ai/spec/dadl-spec-v0.2) (§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

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

- Redirects to another origin drop credentials, custom headers, the `Referer` and 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_hosts` in a `backends.yaml` entry, which limits the hosts that caller-supplied `file_url` values 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](/en/dadl/#requests-to-rest-backends) and [MCP backends over HTTP](/en/configuration/#mcp-backends-over-http).

### 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

- Blobs can be deleted only by the user who created them ([File broker](/en/configuration/#file-broker)).
- `execute_code` runs at most `TOOLMESH_CODE_MAX_CONCURRENT` scripts at once (default 16), one user at most half of them. Further runs wait up to 10 seconds, then fail ([Code Mode](/en/configuration/#code-mode)).
- Without Redis, `/register` is limited per client address, per process.
- `TOOLMESH_ISSUER` defaults to `https://toolmesh.invalid/` when unset; set it to the public URL clients use.
