Skip to content

Configuration: env vars, YAML files, secrets

ToolMesh is configured entirely via environment variables and YAML files.

VariableDefaultDescription
TOOLMESH_PORT8123Host port (Docker mapping; internally always 8080)
TOOLMESH_TRANSPORThttpTransport: http or stdio
TOOLMESH_CORS_ORIGINS(empty)Allowed CORS origins
TOOLMESH_AUTH_PASSWORD(empty)Single-user OAuth password
TOOLMESH_API_KEY(empty)Static API key
TOOLMESH_AUTH_USERownerUser ID of the single password or API key
TOOLMESH_AUTH_PLANproPlan of the single password or API key
TOOLMESH_AUTH_ROLESadminComma-separated roles of the single password or API key
TOOLMESH_ISSUERhttps://toolmesh.invalid/OAuth issuer URL (must end with /). The default is a placeholder on a top-level domain that never resolves: set it to the public URL clients use. It names the resource in the 401 challenge of /mcp and is the base of the approval links of request_grant. ToolMesh warns at startup while it is unchanged, and also while it is https://toolmesh.io/, the placeholder of versions before 0.6.0.
TOOLMESH_TRUSTED_PROXIES(empty: loopback only)Addresses of the reverse proxies whose X-Forwarded-For header is honored, as comma-separated addresses or CIDRs, or none. List the proxies’ own addresses, not client networks and not a Compose network the proxy shares with ToolMesh. An invalid entry stops the server at startup. See Client address.

Failed password logins at /authorize and failed API keys are limited; see Authentication for what counts and how a lockout ends, and API key throttling for the API keys.

VariableDefaultDescription
TOOLMESH_LOGIN_MAX_FAILURES_PER_USER_IP5Failed logins for one account from one client address
TOOLMESH_LOGIN_MAX_FAILURES_PER_USER20Failed logins for one account from all addresses together
TOOLMESH_LOGIN_MAX_FAILURES_PER_IP50Failed logins from one client address across all accounts
TOOLMESH_LOGIN_FAILURE_WINDOW900Length of the counting window in seconds (1 to 2592000)
TOOLMESH_APIKEY_MAX_FAILURES_PER_IP50Failed bearer credentials (API keys) from one client address within the same window
TOOLMESH_BCRYPT_MAX_CONCURRENThalf of the available CPUs, at least 1How many bcrypt comparisons may run at the same time, across the whole process

A limit set to 0 is off and reported in the startup security-posture summary. These six are parsed strictly: a value that is not an integer or is out of range stops the server at startup.

MCP clients such as Claude and ChatGPT register themselves at /register before the user logs in.

VariableDefaultDescription
TOOLMESH_OAUTH_REDIRECT_HOSTS(empty: any https host)Comma-separated hosts a client may use in its redirect_uri: host names (claude.ai) or *.example.com for any subdomain. Checked at /register and again at /authorize, so it also covers clients registered before it was set. Loopback redirect URIs of native clients (http://localhost, 127.0.0.1, [::1]) are always accepted.

Registration is limited to 5 per hour from one client address; an IPv6 address counts as its /64. With Redis the limit holds across replicas; without Redis it applies per process. See The login page for what users confirm when they log in.

VariableDefaultDescription
AUDIT_STOREloglog (slog) or sqlite
AUDIT_RETENTION_DAYS90Retention for SQLite store

On by default with nothing to set up; see Authorization. Kits and approvers live in the same grants file; see Kits and approvals.

VariableDefaultDescription
TOOLMESH_AUTHZ_MODEembeddedembedded: ToolMesh runs the checks itself, on authz.db in the data directory. external: checks go to an OpenFGA server you operate. disabled: no checks, reported at every start and recorded in the audit trail.
TOOLMESH_AUTHZ_PRESET(chosen at startup)Embedded mode: single-user, team or open. Ignored while config/authz.yaml exists.
TOOLMESH_AUTHZ_CONFIG/app/config/authz.yamlEmbedded mode: the grants file. When it exists, its grants replace the preset.
OPENFGA_API_URLhttp://localhost:8080External mode only: OpenFGA API endpoint. In Docker Compose use http://openfga:8080.
OPENFGA_STORE_ID(empty)External mode only: store ID, required.
OPENFGA_MODE(empty)Deprecated. Read only while TOOLMESH_AUTHZ_MODE is not set: restrict selects external, bypass selects embedded. Logs a warning while set.
VariableDefaultDescription
TOOLMESH_POLICIES_DIR/app/policiesThe policies directory. The shipped docker-compose.yml mounts ./config/policies there; examples are in config/policies/examples.
GATE_EVALUATORSgojaThe evaluator chain, comma-separated.

See Output Gate for the ctx reference and for how policies relate to kits.

VariableDefaultDescription
TOOLMESH_MCP_TIMEOUT120HTTP client timeout for MCP backends (seconds)
TOOLMESH_EXEC_TIMEOUT120Tool execution timeout (seconds)
VariableDefaultDescription
TOOLMESH_CODE_TIMEOUT120Wall-clock budget for one execute_code run (seconds)
TOOLMESH_CODE_MAX_CONCURRENT16execute_code runs in progress at once; 0 for no limit. One user may hold at most half of them, rounded up (8 with the default), and a run beyond that share is refused at once. A run that finds every slot taken waits up to 10 seconds for one, then fails with an error result. Must be an integer of 0 or more; anything else stops the server at startup.

On a deployment with a single user, that user can run half the limit in parallel; raise the limit there if needed. Each run gets its own JavaScript runtime, which has no memory limit of its own, so run ToolMesh with a container memory limit. See Code Mode.

The file broker holds files that tool calls pass around without sending their content through the conversation: upload_file fetches a public URL into it, POST /files/upload takes a file directly, and tools with a binary response (audio, images, PDFs) return a download URL under /blobs/<id> instead of the bytes. A file is kept for its TTL: one hour by default, at most 24 hours for uploads.

VariableDefaultDescription
TOOLMESH_FILE_BROKER_ENABLEDtruefalse switches the file broker off: upload_file is not offered, /files/upload and /blobs/ answer 404, and a tool with a binary response returns an error instead of a download URL.
TOOLMESH_FILE_BROKER_MAX_TOTAL_BYTES0 (no limit)Bytes all files together may take
TOOLMESH_FILE_BROKER_MAX_BYTES_PER_USER0 (no limit)Bytes the files of one user may take

DELETE /blobs/<id> needs MCP authentication and succeeds only for the user the file was created for. For anyone else it answers 404, as for an unknown ID. A file created without a user cannot be deleted this way; it is removed when its TTL runs out.

VariableDefaultDescription
LOG_LEVELdebug / infoLog verbosity
LOG_FORMATjsonjson or text
DEBUG_BACKENDS(empty)Comma-separated backend names for debug logging
DEBUG_FILE(empty)Path to debug log file

Security warning: Debug logging may capture full request/response payloads including sensitive data. Never enable DEBUG_BACKENDS or DEBUG_FILE in production environments.

ToolMesh reports aggregated usage statistics to https://tmc.dunkel.cloud/v1/telemetry once every 24 hours. The first report goes out a few minutes after the first start, after a random delay of one to five minutes, and then one every 24 hours. toolmesh.json in the data directory keeps the time of the last report, so restarts neither postpone the schedule nor add reports.

VariableDefaultDescription
DO_NOT_SEND_ANONYMOUS_STATISTICS(empty)Set to yes to stop sending. No site ID is created; counters keep accumulating locally.
TELEMETRY_INTERVAL24hSend interval as a Go duration (1h, 30m) — intended for testing

Each entry in a report carries exactly six fields:

  • site_id — the site ID of the installation (see below)
  • dadl_hash — content hash of the DADL file the calls went through
  • call_count / error_count — successful and failed calls since the last report
  • version — the ToolMesh version
  • mcp_server_count — number of configured MCP server backends

Site ID. On its first start with telemetry enabled, ToolMesh creates a random UUIDv7 and keeps it as site_id in toolmesh.json in the data directory (/app/data in Docker). It is there so that installations can be counted instead of IP addresses, including how long they stay in use. Nothing in it is derived from the host, the configuration or the operator, but it is a persistent identifier: it links the reports of one installation over time, and as a UUIDv7 it includes the time it was created. Without a persistent data directory, every start creates a new one. If toolmesh.json cannot be written, ToolMesh warns, since the site ID then changes on every restart. To discard it, stop ToolMesh, remove site_id from toolmesh.json and start again; a new one is created. With DO_NOT_SEND_ANONYMOUS_STATISTICS=yes no site ID is created, and one created earlier is no longer sent. Versions up to v0.4.1 send no site ID.

Tool arguments, responses, credentials, backend URLs, hostnames and user identifiers are never collected. The DADL hash identifies the connector definition rather than the deployment — everyone running the same DADL reports the same value. As with any HTTP request, the receiving endpoint does see the sender’s IP address.

To opt out:

Terminal window
DO_NOT_SEND_ANONYMOUS_STATISTICS=yes

CREDENTIAL_STORE selects where ToolMesh takes backend credentials from:

StoreValues come fromValues are kept in
embedded (default)CREDENTIAL_* environment variables, usually set in .envthe process environment
commandthe output of a command ToolMesh runs, such as sops -d or vault kv getToolMesh’s memory only

With either store, a REST backend reads only the credentials in the namespace of its backends.yaml entry (CREDENTIAL_GITHUB_* for an entry named github) and the ones its entry names; see Credential and host binding.

Credentials are set as env vars with CREDENTIAL_ prefix:

Terminal window
CREDENTIAL_GITHUB_TOKEN=ghp_xxxxx
CREDENTIAL_STRIPE_KEY=sk_live_xxxxx
CREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxx

Why the environment is not the place for credentials

Section titled “Why the environment is not the place for credentials”

Under Docker the values reach the container through env_file: or environment:. Docker writes a container’s environment in plain text into the container configuration on the host (/var/lib/docker/containers/<id>/config.v2.json, also shown by docker inspect). Every credential then sits on the host’s disk and in every backup or snapshot of it, even when the .env file itself is stored encrypted and decrypted only to start the container. Stdio backends inherit the whole environment as well, so each of them receives every credential.

The command store avoids both: ToolMesh fetches the values itself and keeps them in memory.

VariableDefaultDescription
CREDENTIAL_STOREembeddedSet to command
TOOLMESH_CREDENTIAL_COMMAND(none)Command line that prints the values. Required
TOOLMESH_CREDENTIAL_RELOAD_IN0Seconds between runs. 0 runs the command only at startup
TOOLMESH_CREDENTIAL_COMMAND_TIMEOUT30Seconds a single run may take
TOOLMESH_CREDENTIAL_FORMATdotenvOutput format: dotenv or json
TOOLMESH_CREDENTIAL_JSON_PATH(top level)With json: dot-separated path to the object that holds the values, e.g. data.data

The settings carry a TOOLMESH_ prefix because CREDENTIAL_<NAME> is the namespace of the credentials themselves. Invalid values stop the start.

The command. ToolMesh runs it without a shell, since the image has none. The line is split into arguments the way a shell splits words: single quotes, double quotes and backslash escapes work. Pipes, redirections, ;, &&, variables, command substitution and a leading VAR=value are refused at startup; there is no globbing. Give the program as an absolute path and mount it read-only into the container, together with whatever it reads. It has to run without a libc, as statically linked binaries do. The command inherits ToolMesh’s environment, which with this store holds no credentials.

A run fails when the command exits with a code other than 0, exceeds the timeout, writes more than 1 MiB to stdout, prints no value at all, or prints something that does not parse.

dotenv output (the default). One KEY=value per line, as sops -d --output-type dotenv writes it:

  • # comment lines and blank lines are skipped, and a leading export is ignored.
  • Unquoted values are trimmed, a # after a space or tab starts a comment, and \n stands for a line break (the way sops writes multi-line values).
  • 'single quotes' keep everything literal. "double quotes" know the escapes \n, \r, \t, \", \\ and \$. Quoted values may span lines.
  • Variables are not expanded. A later line wins over an earlier one.

JSON output. With TOOLMESH_CREDENTIAL_FORMAT=json the command prints one JSON value, as vault kv get -format=json and bao kv get -format=json do. TOOLMESH_CREDENTIAL_JSON_PATH selects the object that holds the values: data.data for a KV version 2 secret of Vault or OpenBao, data for version 1, empty for the top level. Everything outside that object, such as request and lease metadata, is ignored.

  • Nested objects below the path are flattened: every string, number and boolean becomes a key named after its own member name, however deep it sits. {"github": {"CREDENTIAL_GITHUB_TOKEN": "..."}} gives CREDENTIAL_GITHUB_TOKEN.
  • Numbers keep their written form. null values and arrays are skipped.
  • A member name that is not an environment variable name, or that occurs twice after flattening, fails the run.
  • Vault’s lease_duration is not used; a KV version 2 secret reports 0 there.

Keys are environment-style names: CREDENTIAL_<NAME> for backend credentials, and any other name that an env: remapping, a credential_env entry or one of ToolMesh’s own secrets (below) refers to. RELOAD_IN is reserved in both formats.

Where the values stay. In a map in ToolMesh’s memory, never in its environment and never in the log. stdout is not logged; stderr is logged at WARN, cut off after 4 KiB, so the command must not write secrets there. When a run adds or drops keys, the log names the keys, not the values.

Refreshing. After TOOLMESH_CREDENTIAL_RELOAD_IN seconds the command runs again. A key RELOAD_IN in the output (a line RELOAD_IN=<seconds>, or a JSON member of that name) sets the delay until the next run instead; RELOAD_IN=0 ends the refreshing. A successful run replaces the whole set at once, and keys it no longer prints are gone. A failed run keeps the previous set and is retried after 30 seconds, then with a doubling delay up to the interval in force. If the first run at startup fails, ToolMesh exits with a non-zero code and the container’s restart policy tries again.

Refreshed values reach REST backends with their next call. MCP backends read theirs (api_key_env, credential_env) when ToolMesh connects to them: at startup and when backends.yaml changes.

ToolMesh’s own secrets. With the command store, TOOLMESH_AUTH_PASSWORD, TOOLMESH_API_KEY and REDIS_URL are taken from the output when it contains them, ahead of the environment, once at startup. Remappings (env: in backends.yaml) resolve their keys in the output too, not in the environment.

Stdio backends. A stdio MCP server inherits ToolMesh’s environment, which with this store contains no credentials. Pass it what it needs with credential_env in its backends.yaml entry: variable name in the child, key in the store.

backends:
- name: github
transport: stdio
command: /usr/local/bin/github-mcp-server
args: ["stdio"]
credential_env:
GITHUB_PERSONAL_ACCESS_TOKEN: CREDENTIAL_GITHUB_TOKEN

The child receives nothing else from the store. A key the store does not hold keeps the backend from connecting. With the embedded store credential_env reads the key from the environment, so the same entry works with both stores.

Monitoring. Two metrics follow the runs: toolmesh_credential_store_runs_total{result="success|failure"} and toolmesh_credential_store_last_success_timestamp_seconds. Alert when the last success lies more than two intervals back, for example with a one-hour interval:

time() - toolmesh_credential_store_last_success_timestamp_seconds > 7200

sops with age keeps the key names readable and encrypts only the values:

Terminal window
sops --encrypt --age <recipient> --input-type dotenv --output-type dotenv \
secrets.plain.env > secrets/toolmesh.env

Mount the encrypted file and a static sops binary read-only, for example in docker-compose.override.yml:

services:
toolmesh:
volumes:
- /usr/local/bin/sops:/usr/local/bin/sops:ro
- ./secrets/toolmesh.env:/run/secrets/toolmesh.env:ro

The .env then holds no credentials, only the store settings:

Terminal window
CREDENTIAL_STORE=command
TOOLMESH_CREDENTIAL_COMMAND=/usr/local/bin/sops -d --input-type dotenv --output-type dotenv /run/secrets/toolmesh.env

How sops gets its age identity is your decision: a key file mounted read-only (SOPS_AGE_KEY_FILE is a path, not a secret), a key command, or a mechanism that releases the key only at runtime. ergosum is such a mechanism: it gives machines short-lived identities that a cloned machine does not get, and ergosumd secret get (ergosum v0.2.0 or later) releases a sealed secret, such as the age key, only on the machine it is bound to, at its place. The key then does not lie on the disk in plain text, and a copied disk, VM image or backup holds no usable secret. Do not put the key itself into .env or environment:; it would end up in the container configuration like any other value there. Change values with sops secrets/toolmesh.env; ToolMesh picks them up at its next run or restart.

Example: Vault or OpenBao through their proxy

Section titled “Example: Vault or OpenBao through their proxy”

Vault Proxy (vault proxy, in OpenBao bao proxy) logs in with its auto-auth method and adds its token to every request that carries none (use_auto_auth_token). The command then needs no token of its own, and nothing is written to disk:

Terminal window
CREDENTIAL_STORE=command
TOOLMESH_CREDENTIAL_FORMAT=json
TOOLMESH_CREDENTIAL_JSON_PATH=data.data
TOOLMESH_CREDENTIAL_COMMAND=/usr/local/bin/vault kv get -format=json -mount=secret toolmesh
TOOLMESH_CREDENTIAL_RELOAD_IN=300
VAULT_ADDR=http://127.0.0.1:8100

The KV secret secret/toolmesh holds the keys as a dotenv file would (CREDENTIAL_GITHUB_TOKEN, TOOLMESH_API_KEY and so on). Mount the static vault binary (or bao, with BAO_ADDR) read-only; the address is not a secret. Bind the proxy’s listener so that only ToolMesh reaches it, for example on loopback in a network namespace shared with the ToolMesh container: whoever reaches it acts with the proxy’s token.

The proxy’s own login needs a credential too. With ergosum, the machine receives a short-lived JWT for the JWT auth method of Vault or OpenBao only after ergosum has called it back at the places it is bound to, so no long-lived secret such as an AppRole secret ID lies on its disk.

A small program that requests an access token and prints it together with its lifetime minus a margin keeps the token fresh. For a token that is valid for an hour:

Terminal window
CREDENTIAL_EXAMPLE_TOKEN=eyJhbGciOi...
RELOAD_IN=3300

ToolMesh runs the program again after 55 minutes. If that run fails, the old token stays in use while the retries back off (30 s, 60 s, 120 s, …), so leave a margin for a few of them. The program can print static values too, for example by decrypting a file first and adding the token to its output.

Defines which backends ToolMesh connects to:

backends:
# MCP backend
- name: memorizer
transport: http
url: "https://memorizer.example.com/mcp"
api_key_env: "MEMORIZER_API_KEY"
# REST backend via DADL
- name: github
transport: rest
dadl: /app/dadl/github.dadl
url: "https://api.github.com"
# Only when the log asks for them (see below):
# credentials: [legacy_token]
# allowed_hosts: [files.example.net, "*.example-cdn.com", media.example.com:8443]

Tools are automatically exposed with a backend prefix (e.g., memorizer_retrieve_knowledge, github_list_repos).

Every REST backend is bound to its entry in backends.yaml. The binding comes from your configuration, never from the DADL: a DADL cannot read the credentials of another backend, and the hosts its own credentials go to are limited as described below.

A DADL is code you install. It decides which requests its backend sends with that backend’s credentials, so load DADLs only from sources you trust, as you would a program. ToolMesh keeps the credentials of different backends apart. The host binding narrows where a backend’s own credentials can go, as a second line of defense; it cannot make a malicious DADL safe, any more than a configuration can make a malicious ToolMesh build safe.

  • Credentials. Each entry has a namespace: its name in upper case with - as _ (entry shelly-cloud: CREDENTIAL_SHELLY_CLOUD_*). A credential belongs to the entry with the longest namespace that starts its name, so CREDENTIAL_GITHUB_ENTERPRISE_TOKEN belongs to an entry github-enterprise, not to an entry github. Every named entry counts, whatever its transport: REST and MCP entries, units and the sub-backends in a unit.yaml. A backend reads a credential only when its entry owns it, lists it in credentials: or maps it with env:. A credential in no namespace, or in one that two spellings of an entry name share (my-api and my_api), belongs to no entry and must be listed. The division follows the configuration on every reload. REST entries need a name; an entry without one is refused.

  • Hosts. Credentials, session cookies, OAuth2 token requests and session logins go only to:

    • the host of the effective base_url (the entry’s url, otherwise the DADL’s base_url) on its port, and for an http base_url on port 80 also its https form on port 443;
    • the other hosts of its registrable domain, on the default port;
    • the entries of allowed_hosts:: a host (api.example.com), a wildcard for any subdomain ("*.example.com", quoted in YAML) or an IP address (10.0.0.5, "[2001:db8::1]"), on the default port, or with :port on that port only. An entry with a scheme, a path or other text is a configuration error, and the backend is not loaded.

    With an https base_url, credentials go out over https only. The registrable domain follows the public suffix list, which includes shared hosting domains: googleapis.com is such a suffix, so every Google API host is a domain of its own and needs allowed_hosts. Many shared SaaS domains whose customers each get a subdomain, such as atlassian.net, zendesk.com or service-now.com, are not on that list: there, the tenants of other customers count as the same registrable domain, and only the DADL keeps the credentials on your tenant. For such a service, use a DADL you have checked, or one whose tools all stay on the base_url host. A token_uri that a jwt_bearer service-account key brings along is your own data and is not checked.

  • Checked at load. ToolMesh checks the credentials a DADL reads and the destinations it names (token_url, absolute tool paths, the health check, the session login URL) when it loads the backend, at startup and on every reload of backends.yaml. Tools outside include_tools are not checked, since they cannot be called; the health check is checked in any case. A backend that reaches further is not loaded: an ERROR line backend refused names each violation and the exact lines to add to the entry (add_to_backends_yaml_entry). The other backends keep running, and the startup security-posture summary lists the refused ones. There is no global switch, only these lines per entry.

  • Checked again on every request. The same rules apply wherever a credential goes out, on every redirect hop as well. When an entry has no url and the DADL’s own base_url is plain http, ToolMesh warns at load that credentials go out unencrypted.

  • Names. In credentials: and env:, names consist of letters, digits and _. env: keys are read in upper case, so credential_foo and CREDENTIAL_FOO are the same key; an entry with both is refused.

  • No secret. credential: none in an auth block is the placeholder of DADLs for APIs without authentication. It is never looked up and needs no binding.

Two entries that need a line, each named like its DADL:

- name: shelly-cloud # reads shelly_auth_key, outside CREDENTIAL_SHELLY_CLOUD_*
transport: rest
dadl: shelly-cloud.dadl
credentials: [shelly_auth_key]
- name: youtube # token_url on oauth2.googleapis.com
transport: rest
dadl: youtube.dadl
allowed_hosts: [oauth2.googleapis.com]

After an upgrade to v0.6.0, search the log for backend refused and add the lines it names; the next reload of backends.yaml loads the backend. See Upgrading to v0.6.0. How REST backends handle redirects, token requests, path parameters and private addresses is described under DADL.

An MCP backend over HTTP stays on the origin (scheme, host and port) of its configured url, and its api_key_env token goes only there. A redirect to another origin, or from https to http, is refused, and so is a message endpoint on another origin that a server using the legacy SSE transport announces.

Multi-user configuration for OAuth:

users:
- username: alice
password_hash: "$2a$12$..."
company: acme
plan: pro
roles: [admin]

API key definitions. An entry names its key as key_sha256 (the SHA-256 of a randomly generated key, looked up directly) or as a bcrypt key_hash (compared once per key after startup); see API Keys.

keys:
- key_sha256: "<SHA-256 of the key, 64 hex characters>"
user_id: ci-bot
company_id: acme
plan: standard
roles: [read]
caller_id: github-actions

Optional grants and denies: who may call which tools. Without this file a preset applies. A deny wins over every grant and the preset. Copy config/authz.yaml.example to start; ToolMesh applies changes within seconds. See Authorization. The same file defines kits, bundles of tools a person grants on request for a limited time, and the approvers who may grant them; see Kits and approvals.

preset: single-user # optional
grants:
- plan: free
access: [read]
- role: support
tools: [zammad_list_tickets, zammad_get_ticket]
- company: acme
backends: [netbox]
denies: # optional
- role: support
tools: [zammad_delete_ticket]
kits: # optional: granted on request, for a limited time
net-diag-read:
description: "Network diagnosis (read-only)"
grants: [graylog:read, unifi:read, netbox:read]
ttl_default: 4h
ttl_max: 24h
approvers: # optional: who may grant kits
- name: bob@example.com
address: bc1q0xcqpzrky6eff2g52qdye53xkk9jxkvrh6yhyw
kits: [net-diag-read]

Maps caller IDs to trust classes:

classes:
trusted:
- claude-code
- claude-desktop
standard:
- partner-*
# Everything else → "untrusted"