Configuration: env vars, YAML files, secrets
ToolMesh is configured entirely via environment variables and YAML files.
Environment Variables
Section titled “Environment Variables”MCP Server
Section titled “MCP Server”| Variable | Default | Description |
|---|---|---|
TOOLMESH_PORT | 8123 | Host port (Docker mapping; internally always 8080) |
TOOLMESH_TRANSPORT | http | Transport: 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_USER | owner | User ID of the single password or API key |
TOOLMESH_AUTH_PLAN | pro | Plan of the single password or API key |
TOOLMESH_AUTH_ROLES | admin | Comma-separated roles of the single password or API key |
TOOLMESH_ISSUER | https://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. |
Login throttling
Section titled “Login throttling”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.
| Variable | Default | Description |
|---|---|---|
TOOLMESH_LOGIN_MAX_FAILURES_PER_USER_IP | 5 | Failed logins for one account from one client address |
TOOLMESH_LOGIN_MAX_FAILURES_PER_USER | 20 | Failed logins for one account from all addresses together |
TOOLMESH_LOGIN_MAX_FAILURES_PER_IP | 50 | Failed logins from one client address across all accounts |
TOOLMESH_LOGIN_FAILURE_WINDOW | 900 | Length of the counting window in seconds (1 to 2592000) |
TOOLMESH_APIKEY_MAX_FAILURES_PER_IP | 50 | Failed bearer credentials (API keys) from one client address within the same window |
TOOLMESH_BCRYPT_MAX_CONCURRENT | half of the available CPUs, at least 1 | How 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.
OAuth clients
Section titled “OAuth clients”MCP clients such as Claude and ChatGPT register themselves at /register before the user logs in.
| Variable | Default | Description |
|---|---|---|
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.
| Variable | Default | Description |
|---|---|---|
AUDIT_STORE | log | log (slog) or sqlite |
AUDIT_RETENTION_DAYS | 90 | Retention for SQLite store |
Authorization
Section titled “Authorization”On by default with nothing to set up; see Authorization. Kits and approvers live in the same grants file; see Kits and approvals.
| Variable | Default | Description |
|---|---|---|
TOOLMESH_AUTHZ_MODE | embedded | embedded: 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.yaml | Embedded mode: the grants file. When it exists, its grants replace the preset. |
OPENFGA_API_URL | http://localhost:8080 | External 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. |
Gate policies
Section titled “Gate policies”| Variable | Default | Description |
|---|---|---|
TOOLMESH_POLICIES_DIR | /app/policies | The policies directory. The shipped docker-compose.yml mounts ./config/policies there; examples are in config/policies/examples. |
GATE_EVALUATORS | goja | The evaluator chain, comma-separated. |
See Output Gate for the ctx reference and for how policies relate to kits.
Timeouts
Section titled “Timeouts”| Variable | Default | Description |
|---|---|---|
TOOLMESH_MCP_TIMEOUT | 120 | HTTP client timeout for MCP backends (seconds) |
TOOLMESH_EXEC_TIMEOUT | 120 | Tool execution timeout (seconds) |
Code Mode
Section titled “Code Mode”| Variable | Default | Description |
|---|---|---|
TOOLMESH_CODE_TIMEOUT | 120 | Wall-clock budget for one execute_code run (seconds) |
TOOLMESH_CODE_MAX_CONCURRENT | 16 | execute_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.
File broker
Section titled “File broker”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.
| Variable | Default | Description |
|---|---|---|
TOOLMESH_FILE_BROKER_ENABLED | true | false 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_BYTES | 0 (no limit) | Bytes all files together may take |
TOOLMESH_FILE_BROKER_MAX_BYTES_PER_USER | 0 (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.
Logging
Section titled “Logging”| Variable | Default | Description |
|---|---|---|
LOG_LEVEL | debug / info | Log verbosity |
LOG_FORMAT | json | json 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_BACKENDSorDEBUG_FILEin production environments.
Telemetry
Section titled “Telemetry”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.
| Variable | Default | Description |
|---|---|---|
DO_NOT_SEND_ANONYMOUS_STATISTICS | (empty) | Set to yes to stop sending. No site ID is created; counters keep accumulating locally. |
TELEMETRY_INTERVAL | 24h | Send 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 throughcall_count/error_count— successful and failed calls since the last reportversion— the ToolMesh versionmcp_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:
DO_NOT_SEND_ANONYMOUS_STATISTICS=yesCredential stores
Section titled “Credential stores”CREDENTIAL_STORE selects where ToolMesh takes backend credentials from:
| Store | Values come from | Values are kept in |
|---|---|---|
embedded (default) | CREDENTIAL_* environment variables, usually set in .env | the process environment |
command | the output of a command ToolMesh runs, such as sops -d or vault kv get | ToolMesh’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.
Embedded store
Section titled “Embedded store”Credentials are set as env vars with CREDENTIAL_ prefix:
CREDENTIAL_GITHUB_TOKEN=ghp_xxxxxCREDENTIAL_STRIPE_KEY=sk_live_xxxxxCREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxxWhy 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.
Command store
Section titled “Command store”| Variable | Default | Description |
|---|---|---|
CREDENTIAL_STORE | embedded | Set to command |
TOOLMESH_CREDENTIAL_COMMAND | (none) | Command line that prints the values. Required |
TOOLMESH_CREDENTIAL_RELOAD_IN | 0 | Seconds between runs. 0 runs the command only at startup |
TOOLMESH_CREDENTIAL_COMMAND_TIMEOUT | 30 | Seconds a single run may take |
TOOLMESH_CREDENTIAL_FORMAT | dotenv | Output 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 leadingexportis ignored.- Unquoted values are trimmed, a
#after a space or tab starts a comment, and\nstands 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": "..."}}givesCREDENTIAL_GITHUB_TOKEN. - Numbers keep their written form.
nullvalues 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_durationis not used; a KV version 2 secret reports0there.
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_TOKENThe 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 > 7200Example: an encrypted file with sops
Section titled “Example: an encrypted file with sops”sops with age keeps the key names readable and encrypts only the values:
sops --encrypt --age <recipient> --input-type dotenv --output-type dotenv \ secrets.plain.env > secrets/toolmesh.envMount 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:roThe .env then holds no credentials, only the store settings:
CREDENTIAL_STORE=commandTOOLMESH_CREDENTIAL_COMMAND=/usr/local/bin/sops -d --input-type dotenv --output-type dotenv /run/secrets/toolmesh.envHow 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:
CREDENTIAL_STORE=commandTOOLMESH_CREDENTIAL_FORMAT=jsonTOOLMESH_CREDENTIAL_JSON_PATH=data.dataTOOLMESH_CREDENTIAL_COMMAND=/usr/local/bin/vault kv get -format=json -mount=secret toolmeshTOOLMESH_CREDENTIAL_RELOAD_IN=300VAULT_ADDR=http://127.0.0.1:8100The 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.
Example: short-lived tokens
Section titled “Example: short-lived tokens”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:
CREDENTIAL_EXAMPLE_TOKEN=eyJhbGciOi...RELOAD_IN=3300ToolMesh 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.
Configuration Files
Section titled “Configuration Files”backends.yaml
Section titled “backends.yaml”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).
Credential and host binding
Section titled “Credential and host binding”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
namein upper case with-as_(entryshelly-cloud:CREDENTIAL_SHELLY_CLOUD_*). A credential belongs to the entry with the longest namespace that starts its name, soCREDENTIAL_GITHUB_ENTERPRISE_TOKENbelongs to an entrygithub-enterprise, not to an entrygithub. Every named entry counts, whatever its transport: REST and MCP entries, units and the sub-backends in aunit.yaml. A backend reads a credential only when its entry owns it, lists it incredentials:or maps it withenv:. A credential in no namespace, or in one that two spellings of an entry name share (my-apiandmy_api), belongs to no entry and must be listed. The division follows the configuration on every reload. REST entries need aname; 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’surl, otherwise the DADL’sbase_url) on its port, and for anhttpbase_urlon port 80 also itshttpsform 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:porton 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
httpsbase_url, credentials go out over https only. The registrable domain follows the public suffix list, which includes shared hosting domains:googleapis.comis such a suffix, so every Google API host is a domain of its own and needsallowed_hosts. Many shared SaaS domains whose customers each get a subdomain, such asatlassian.net,zendesk.comorservice-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 thebase_urlhost. Atoken_urithat ajwt_bearerservice-account key brings along is your own data and is not checked. - the host of the effective
-
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 ofbackends.yaml. Tools outsideinclude_toolsare not checked, since they cannot be called; the health check is checked in any case. A backend that reaches further is not loaded: anERRORlinebackend refusednames 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
urland the DADL’s ownbase_urlis plainhttp, ToolMesh warns at load that credentials go out unencrypted. -
Names. In
credentials:andenv:, names consist of letters, digits and_.env:keys are read in upper case, socredential_fooandCREDENTIAL_FOOare the same key; an entry with both is refused. -
No secret.
credential: nonein 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.
MCP backends over HTTP
Section titled “MCP backends over HTTP”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.
users.yaml
Section titled “users.yaml”Multi-user configuration for OAuth:
users: - username: alice password_hash: "$2a$12$..." company: acme plan: pro roles: [admin]apikeys.yaml
Section titled “apikeys.yaml”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-actionsauthz.yaml
Section titled “authz.yaml”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]caller-classes.yaml
Section titled “caller-classes.yaml”Maps caller IDs to trust classes:
classes: trusted: - claude-code - claude-desktop standard: - partner-* # Everything else → "untrusted"