Konfiguration: ENV-Variablen, YAML-Dateien
ToolMesh wird vollständig über Umgebungsvariablen und YAML-Dateien konfiguriert.
Umgebungsvariablen
Abschnitt betitelt „Umgebungsvariablen“MCP-Server
Abschnitt betitelt „MCP-Server“| Variable | Standard | Beschreibung |
|---|---|---|
TOOLMESH_PORT | 8123 | Host-Port (Docker-Mapping; intern immer 8080) |
TOOLMESH_TRANSPORT | http | Transport: http oder stdio |
TOOLMESH_CORS_ORIGINS | (leer) | Erlaubte CORS-Origins |
TOOLMESH_AUTH_PASSWORD | (leer) | Single-User-OAuth-Passwort |
TOOLMESH_API_KEY | (leer) | Statischer API-Key |
TOOLMESH_AUTH_USER | owner | Benutzer-ID des einzelnen Passworts oder API-Keys |
TOOLMESH_AUTH_PLAN | pro | Plan des einzelnen Passworts oder API-Keys |
TOOLMESH_AUTH_ROLES | admin | Kommagetrennte Rollen des einzelnen Passworts oder API-Keys |
TOOLMESH_ISSUER | https://toolmesh.invalid/ | OAuth-Issuer-URL (muss mit / enden). Der Standard ist ein Platzhalter auf einer Top-Level-Domain, die nie aufgelöst wird, und ist durch die öffentliche URL zu ersetzen, die Clients verwenden. Sie benennt die Ressource in der 401-Challenge von /mcp und ist die Basis der Freigabelinks von request_grant. ToolMesh warnt beim Start, solange sie unverändert ist, und ebenso, solange sie https://toolmesh.io/ lautet, den Platzhalter der Versionen vor 0.6.0. |
TOOLMESH_TRUSTED_PROXIES | (leer: nur Loopback) | Adressen der Reverse-Proxys, deren X-Forwarded-For-Header beachtet wird, als kommagetrennte Adressen oder CIDRs, oder none. Hierher gehören die eigenen Adressen der Proxys, weder die Netze der Clients noch ein Compose-Netz, das ein Proxy mit ToolMesh teilt. Ein ungültiger Eintrag stoppt den Server beim Start. Siehe Client-Adresse. |
Login-Drosselung
Abschnitt betitelt „Login-Drosselung“Fehlgeschlagene Passwort-Logins unter /authorize und fehlgeschlagene API-Keys sind begrenzt; was zählt und wie eine Sperre endet, steht unter Authentifizierung, für die API-Keys unter Drosselung von API-Keys.
| Variable | Standard | Beschreibung |
|---|---|---|
TOOLMESH_LOGIN_MAX_FAILURES_PER_USER_IP | 5 | Fehlgeschlagene Logins für ein Konto von einer Client-Adresse |
TOOLMESH_LOGIN_MAX_FAILURES_PER_USER | 20 | Fehlgeschlagene Logins für ein Konto von allen Adressen zusammen |
TOOLMESH_LOGIN_MAX_FAILURES_PER_IP | 50 | Fehlgeschlagene Logins von einer Client-Adresse über alle Konten |
TOOLMESH_LOGIN_FAILURE_WINDOW | 900 | Länge des Zählfensters in Sekunden (1 bis 2592000) |
TOOLMESH_APIKEY_MAX_FAILURES_PER_IP | 50 | Fehlgeschlagene Bearer-Credentials (API-Keys) von einer Client-Adresse im selben Zählfenster |
TOOLMESH_BCRYPT_MAX_CONCURRENT | Hälfte der verfügbaren CPUs, mindestens 1 | Wie viele bcrypt-Vergleiche gleichzeitig laufen dürfen, im ganzen Prozess |
Ein Limit mit dem Wert 0 ist aus und wird in der Security-Posture-Zusammenfassung beim Start gemeldet. Diese sechs werden streng geparst: Ein Wert, der keine Ganzzahl ist oder außerhalb des Bereichs liegt, stoppt den Server beim Start.
OAuth-Clients
Abschnitt betitelt „OAuth-Clients“MCP-Clients wie Claude und ChatGPT registrieren sich unter /register, bevor sich der Benutzer anmeldet.
| Variable | Standard | Beschreibung |
|---|---|---|
TOOLMESH_OAUTH_REDIRECT_HOSTS | (leer: jeder https-Host) | Kommagetrennte Hosts, die ein Client in seiner redirect_uri verwenden darf: Hostnamen (claude.ai) oder *.example.com für jede Subdomain. Geprüft unter /register und erneut unter /authorize, gilt also auch für Clients, die sich vorher registriert haben. Loopback-Redirect-URIs nativer Clients (http://localhost, 127.0.0.1, [::1]) sind immer erlaubt. |
Die Registrierung ist auf 5 pro Stunde von einer Client-Adresse begrenzt; eine IPv6-Adresse zählt als ihr /64. Mit Redis gilt das Limit über Replikas hinweg, ohne Redis je Prozess. Was Benutzer beim Login bestätigen, steht unter Die Login-Seite.
| Variable | Standard | Beschreibung |
|---|---|---|
AUDIT_STORE | log | log (slog) oder sqlite |
AUDIT_RETENTION_DAYS | 90 | Aufbewahrungsdauer für SQLite-Store |
Autorisierung
Abschnitt betitelt „Autorisierung“Standardmäßig aktiv, ohne Setup; siehe Autorisierung. Koffer und Approver stehen in derselben Grants-Datei; siehe Koffer und Freigaben.
| Variable | Standard | Beschreibung |
|---|---|---|
TOOLMESH_AUTHZ_MODE | embedded | embedded: ToolMesh prüft selbst, auf authz.db im Datenverzeichnis. external: Prüfungen gehen an einen OpenFGA-Server, den Sie betreiben. disabled: keine Prüfungen, bei jedem Start gemeldet und im Audit-Trail festgehalten. |
TOOLMESH_AUTHZ_PRESET | (beim Start gewählt) | Embedded Mode: single-user, team oder open. Wird ignoriert, solange config/authz.yaml existiert. |
TOOLMESH_AUTHZ_CONFIG | /app/config/authz.yaml | Embedded Mode: die Grants-Datei. Existiert sie, ersetzen ihre Grants das Preset. |
OPENFGA_API_URL | http://localhost:8080 | Nur External Mode: OpenFGA-API-Endpunkt. In Docker Compose http://openfga:8080 verwenden. |
OPENFGA_STORE_ID | (leer) | Nur External Mode: Store-ID, Pflicht. |
OPENFGA_MODE | (leer) | Veraltet. Wird nur gelesen, solange TOOLMESH_AUTHZ_MODE nicht gesetzt ist: restrict wählt external, bypass wählt embedded. Loggt eine Warnung, solange es gesetzt ist. |
Gate-Policies
Abschnitt betitelt „Gate-Policies“| Variable | Standard | Beschreibung |
|---|---|---|
TOOLMESH_POLICIES_DIR | /app/policies | Das Policies-Verzeichnis. Das mitgelieferte docker-compose.yml mountet ./config/policies dorthin; Beispiele liegen in config/policies/examples. |
GATE_EVALUATORS | goja | Die Evaluator-Kette, kommagetrennt. |
Die ctx-Referenz und das Verhältnis von Policies zu Koffern stehen unter Output Gate.
Timeouts
Abschnitt betitelt „Timeouts“| Variable | Standard | Beschreibung |
|---|---|---|
TOOLMESH_MCP_TIMEOUT | 120 | HTTP-Client-Timeout für MCP-Backends (Sekunden) |
TOOLMESH_EXEC_TIMEOUT | 120 | Tool-Ausführungs-Timeout (Sekunden) |
Code Mode
Abschnitt betitelt „Code Mode“| Variable | Standard | Beschreibung |
|---|---|---|
TOOLMESH_CODE_TIMEOUT | 120 | Zeitbudget für einen execute_code-Lauf (Sekunden) |
TOOLMESH_CODE_MAX_CONCURRENT | 16 | Gleichzeitig laufende execute_code-Läufe; 0 für kein Limit. Ein Benutzer darf höchstens die Hälfte davon belegen, aufgerundet (8 mit dem Standard), und ein Lauf über diesen Anteil hinaus wird sofort abgewiesen. Ein Lauf, der alle Plätze belegt vorfindet, wartet bis zu 10 Sekunden auf einen und schlägt dann mit einem Fehlerergebnis fehl. Muss eine Ganzzahl ab 0 sein; alles andere stoppt den Server beim Start. |
In einer Installation mit nur einem Benutzer kann dieser die Hälfte des Limits parallel nutzen; dort lässt sich das Limit bei Bedarf anheben. Jeder Lauf bekommt eine eigene JavaScript-Laufzeit, die kein eigenes Speicherlimit hat; ToolMesh sollte deshalb mit einem Speicherlimit für den Container laufen. Siehe Code Mode.
Datei-Broker
Abschnitt betitelt „Datei-Broker“Der Datei-Broker hält Dateien, die Tool-Calls weiterreichen, ohne ihren Inhalt durch die Unterhaltung zu schicken: upload_file holt eine öffentliche URL hinein, POST /files/upload nimmt eine Datei direkt an, und Tools mit binärer Antwort (Audio, Bilder, PDFs) geben statt der Bytes eine Download-URL unter /blobs/<id> zurück. Eine Datei bleibt für ihre TTL erhalten: standardmäßig eine Stunde, bei Uploads höchstens 24 Stunden.
| Variable | Standard | Beschreibung |
|---|---|---|
TOOLMESH_FILE_BROKER_ENABLED | true | false schaltet den Datei-Broker ab: upload_file wird nicht angeboten, /files/upload und /blobs/ antworten mit 404, und ein Tool mit binärer Antwort liefert einen Fehler statt einer Download-URL. |
TOOLMESH_FILE_BROKER_MAX_TOTAL_BYTES | 0 (kein Limit) | Bytes, die alle Dateien zusammen belegen dürfen |
TOOLMESH_FILE_BROKER_MAX_BYTES_PER_USER | 0 (kein Limit) | Bytes, die die Dateien eines Benutzers belegen dürfen |
DELETE /blobs/<id> erfordert MCP-Authentifizierung und gelingt nur für den Benutzer, für den die Datei angelegt wurde. Allen anderen antwortet ToolMesh mit 404, wie bei einer unbekannten ID. Eine ohne Benutzer angelegte Datei lässt sich so nicht löschen; sie wird entfernt, wenn ihre TTL abläuft.
Logging
Abschnitt betitelt „Logging“| Variable | Standard | Beschreibung |
|---|---|---|
LOG_LEVEL | debug / info | Log-Detailgrad |
LOG_FORMAT | json | json oder text |
DEBUG_BACKENDS | (leer) | Kommaseparierte Backend-Namen für Debug-Logging |
DEBUG_FILE | (leer) | Pfad zur Debug-Log-Datei |
Sicherheitshinweis: Debug-Logging kann vollständige Request/Response-Payloads einschließlich sensibler Daten erfassen.
DEBUG_BACKENDSoderDEBUG_FILEniemals in Produktionsumgebungen aktivieren.
Telemetrie
Abschnitt betitelt „Telemetrie“ToolMesh meldet alle 24 Stunden aggregierte Nutzungsstatistiken an https://tmc.dunkel.cloud/v1/telemetry. Der erste Report geht wenige Minuten nach dem ersten Start hinaus, nach einer zufälligen Wartezeit von einer bis fünf Minuten, danach einer alle 24 Stunden. toolmesh.json im Datenverzeichnis hält den Zeitpunkt des letzten Reports fest; Neustarts verschieben den Plan deshalb nicht und erzeugen keine zusätzlichen Reports.
| Variable | Standard | Beschreibung |
|---|---|---|
DO_NOT_SEND_ANONYMOUS_STATISTICS | (leer) | Auf yes setzen, um das Senden zu stoppen. Es wird keine Site-ID angelegt; Zähler laufen lokal weiter. |
TELEMETRY_INTERVAL | 24h | Sendeintervall als Go-Duration (1h, 30m) — für Tests gedacht |
Jeder Eintrag eines Reports enthält genau sechs Felder:
site_id— die Site-ID der Installation (siehe unten)dadl_hash— Content-Hash der DADL-Datei, über die die Aufrufe liefencall_count/error_count— erfolgreiche und fehlgeschlagene Aufrufe seit dem letzten Reportversion— die ToolMesh-Versionmcp_server_count— Anzahl der konfigurierten MCP-Server-Backends
Site-ID. Beim ersten Start mit eingeschalteter Telemetrie erzeugt ToolMesh eine zufällige UUIDv7 und legt sie als site_id in toolmesh.json im Datenverzeichnis ab (/app/data im Docker-Container). Sie dient dazu, Installationen statt IP-Adressen zu zählen, auch wie lange sie in Gebrauch bleiben. Nichts darin ist aus Host, Konfiguration oder Betreiber abgeleitet, sie ist aber eine dauerhafte Kennung: Sie verknüpft die Reports einer Installation über die Zeit, und als UUIDv7 enthält sie ihren Erzeugungszeitpunkt. Ohne dauerhaftes Datenverzeichnis entsteht bei jedem Start eine neue. Lässt sich toolmesh.json nicht schreiben, warnt ToolMesh, weil sich die Site-ID dann bei jedem Neustart ändert. Zum Verwerfen ToolMesh stoppen, site_id aus toolmesh.json entfernen und neu starten; dann entsteht eine neue. Mit DO_NOT_SEND_ANONYMOUS_STATISTICS=yes wird keine Site-ID angelegt, und eine früher angelegte wird nicht mehr gesendet. Versionen bis v0.4.1 senden keine Site-ID.
Tool-Argumente, Antworten, Credentials, Backend-URLs, Hostnamen und Nutzerkennungen werden nie erfasst. Der DADL-Hash identifiziert die Connector-Definition, nicht die Installation — wer dieselbe DADL einsetzt, meldet denselben Wert. Wie bei jedem HTTP-Request sieht der empfangende Endpunkt allerdings die IP-Adresse des Absenders.
Zum Deaktivieren:
DO_NOT_SEND_ANONYMOUS_STATISTICS=yesCredential-Stores
Abschnitt betitelt „Credential-Stores“CREDENTIAL_STORE legt fest, woher ToolMesh die Credentials der Backends nimmt:
| Store | Werte kommen aus | Werte liegen in |
|---|---|---|
embedded (Standard) | Umgebungsvariablen CREDENTIAL_*, meist in .env gesetzt | der Prozessumgebung |
command | der Ausgabe eines Befehls, den ToolMesh ausführt, etwa sops -d oder vault kv get | nur dem Arbeitsspeicher von ToolMesh |
Mit beiden Stores liest ein REST-Backend nur die Credentials im Namensraum seines backends.yaml-Eintrags (CREDENTIAL_GITHUB_* für einen Eintrag namens github) und die, die sein Eintrag nennt; siehe Bindung an Credentials und Hosts.
Embedded Store
Abschnitt betitelt „Embedded Store“Credentials werden als Umgebungsvariablen mit CREDENTIAL_-Präfix gesetzt:
CREDENTIAL_GITHUB_TOKEN=ghp_xxxxxCREDENTIAL_STRIPE_KEY=sk_live_xxxxxCREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxxWarum Credentials nicht in die Umgebung gehören
Abschnitt betitelt „Warum Credentials nicht in die Umgebung gehören“Unter Docker gelangen die Werte über env_file: oder environment: in den Container. Docker schreibt die Umgebung eines Containers im Klartext in dessen Konfiguration auf dem Host (/var/lib/docker/containers/<id>/config.v2.json, auch sichtbar mit docker inspect). Jedes Credential liegt dann auf der Platte des Hosts und in jedem Backup oder Snapshot davon, selbst wenn die .env verschlüsselt abgelegt ist und nur zum Start des Containers entschlüsselt wird. Stdio-Backends erben außerdem die gesamte Umgebung, jedes von ihnen erhält also jedes Credential.
Der Store command vermeidet beides: ToolMesh holt die Werte selbst und hält sie im Arbeitsspeicher.
Command Store
Abschnitt betitelt „Command Store“| Variable | Standard | Beschreibung |
|---|---|---|
CREDENTIAL_STORE | embedded | Auf command setzen |
TOOLMESH_CREDENTIAL_COMMAND | (keiner) | Befehlszeile, die die Werte ausgibt. Pflicht |
TOOLMESH_CREDENTIAL_RELOAD_IN | 0 | Sekunden zwischen zwei Läufen. 0 führt den Befehl nur beim Start aus |
TOOLMESH_CREDENTIAL_COMMAND_TIMEOUT | 30 | Sekunden, die ein einzelner Lauf dauern darf |
TOOLMESH_CREDENTIAL_FORMAT | dotenv | Ausgabeformat: dotenv oder json |
TOOLMESH_CREDENTIAL_JSON_PATH | (oberste Ebene) | Bei json: durch Punkte getrennter Pfad zu dem Objekt, das die Werte enthält, z.B. data.data |
Die Einstellungen tragen das Präfix TOOLMESH_, weil CREDENTIAL_<NAME> der Namensraum der Credentials selbst ist. Ungültige Werte verhindern den Start.
Der Befehl. ToolMesh führt ihn ohne Shell aus, denn das Image enthält keine. Die Zeile wird so in Argumente zerlegt, wie eine Shell Wörter trennt: Einfache und doppelte Anführungszeichen sowie Backslash-Escapes funktionieren. Pipes, Umleitungen, ;, &&, Variablen, Befehlsersetzung und ein vorangestelltes VAR=value werden beim Start abgewiesen; Globbing gibt es nicht. Das Programm ist mit absolutem Pfad anzugeben und schreibgeschützt in den Container zu mounten, zusammen mit allem, was es liest. Es muss ohne libc laufen, wie statisch gelinkte Binaries es tun. Der Befehl erbt die Umgebung von ToolMesh, die mit diesem Store keine Credentials enthält.
Ein Lauf schlägt fehl, wenn der Befehl mit einem anderen Code als 0 endet, das Timeout überschreitet, mehr als 1 MiB auf stdout schreibt, gar keinen Wert ausgibt oder etwas ausgibt, das sich nicht parsen lässt.
dotenv-Ausgabe (Standard). Eine Zeile KEY=value je Wert, wie sops -d --output-type dotenv sie schreibt:
- Kommentarzeilen mit
#und Leerzeilen werden übersprungen, ein vorangestelltesexportwird ignoriert. - Werte ohne Anführungszeichen werden getrimmt, ein
#nach einem Leerzeichen oder Tab beginnt einen Kommentar, und\nsteht für einen Zeilenumbruch (so schreibt sops mehrzeilige Werte). 'Einfache Anführungszeichen'lassen alles wörtlich."Doppelte Anführungszeichen"kennen die Escapes\n,\r,\t,\",\\und\$. Werte in Anführungszeichen dürfen über mehrere Zeilen gehen.- Variablen werden nicht expandiert. Eine spätere Zeile gewinnt gegen eine frühere.
JSON-Ausgabe. Mit TOOLMESH_CREDENTIAL_FORMAT=json gibt der Befehl einen JSON-Wert aus, wie es vault kv get -format=json und bao kv get -format=json tun. TOOLMESH_CREDENTIAL_JSON_PATH wählt das Objekt, das die Werte enthält: data.data für ein KV-Secret der Version 2 von Vault oder OpenBao, data für Version 1, leer für die oberste Ebene. Alles außerhalb dieses Objekts, etwa Metadaten zu Anfrage und Lease, wird ignoriert.
- Verschachtelte Objekte unterhalb des Pfads werden flachgeklopft: Jeder String, jede Zahl und jeder Boolean wird ein Schlüssel mit dem Namen seines eigenen Members, gleich wie tief er liegt.
{"github": {"CREDENTIAL_GITHUB_TOKEN": "..."}}ergibtCREDENTIAL_GITHUB_TOKEN. - Zahlen behalten ihre geschriebene Form.
null-Werte und Arrays werden übersprungen. - Ein Member-Name, der kein Name einer Umgebungsvariablen ist oder nach dem Flachklopfen doppelt vorkommt, lässt den Lauf fehlschlagen.
- Das Feld
lease_durationvon Vault wird nicht verwendet; ein KV-Secret der Version 2 meldet dort0.
Schlüssel sind Namen im Stil von Umgebungsvariablen: CREDENTIAL_<NAME> für Credentials der Backends und jeder andere Name, auf den eine env:-Abbildung, ein credential_env-Eintrag oder eines der eigenen Secrets von ToolMesh (siehe unten) verweist. RELOAD_IN ist in beiden Formaten reserviert.
Wo die Werte bleiben. In einer Map im Arbeitsspeicher von ToolMesh, nie in seiner Umgebung und nie im Log. stdout wird nicht geloggt; stderr wird mit WARN geloggt und nach 4 KiB abgeschnitten, der Befehl darf dort also keine Secrets schreiben. Fügt ein Lauf Schlüssel hinzu oder fallen welche weg, nennt das Log die Schlüssel, nicht die Werte.
Erneuern. Nach TOOLMESH_CREDENTIAL_RELOAD_IN Sekunden läuft der Befehl erneut. Ein Schlüssel RELOAD_IN in der Ausgabe (eine Zeile RELOAD_IN=<seconds> oder ein gleichnamiger JSON-Member) legt stattdessen die Wartezeit bis zum nächsten Lauf fest; RELOAD_IN=0 beendet das Erneuern. Ein erfolgreicher Lauf ersetzt den ganzen Satz auf einmal, und Schlüssel, die er nicht mehr ausgibt, sind weg. Ein fehlgeschlagener Lauf behält den bisherigen Satz und wird nach 30 Sekunden wiederholt, dann mit jeweils doppelter Wartezeit bis zum geltenden Intervall. Schlägt der erste Lauf beim Start fehl, beendet sich ToolMesh mit einem Code ungleich 0, und die Restart-Policy des Containers versucht es erneut.
Erneuerte Werte erreichen REST-Backends mit ihrem nächsten Aufruf. MCP-Backends lesen ihre Werte (api_key_env, credential_env), wenn ToolMesh sich mit ihnen verbindet: beim Start und wenn sich backends.yaml ändert.
Die eigenen Secrets von ToolMesh. Mit dem Command Store werden TOOLMESH_AUTH_PASSWORD, TOOLMESH_API_KEY und REDIS_URL aus der Ausgabe genommen, wenn sie dort stehen, vorrangig vor der Umgebung und einmal beim Start. Abbildungen (env: in backends.yaml) lösen ihre Schlüssel ebenfalls in der Ausgabe auf, nicht in der Umgebung.
Stdio-Backends. Ein Stdio-MCP-Server erbt die Umgebung von ToolMesh, die mit diesem Store keine Credentials enthält. Was er braucht, bekommt er über credential_env in seinem backends.yaml-Eintrag: Variablenname im Kindprozess, Schlüssel im Store.
backends: - name: github transport: stdio command: /usr/local/bin/github-mcp-server args: ["stdio"] credential_env: GITHUB_PERSONAL_ACCESS_TOKEN: CREDENTIAL_GITHUB_TOKENSonst erhält der Kindprozess nichts aus dem Store. Ein Schlüssel, den der Store nicht hat, verhindert die Verbindung zum Backend. Mit dem Embedded Store liest credential_env den Schlüssel aus der Umgebung, derselbe Eintrag funktioniert also mit beiden Stores.
Monitoring. Zwei Metriken begleiten die Läufe: toolmesh_credential_store_runs_total{result="success|failure"} und toolmesh_credential_store_last_success_timestamp_seconds. Ein Alarm ist angebracht, wenn der letzte Erfolg mehr als zwei Intervalle zurückliegt, zum Beispiel bei einem Intervall von einer Stunde:
time() - toolmesh_credential_store_last_success_timestamp_seconds > 7200Beispiel: eine verschlüsselte Datei mit sops
Abschnitt betitelt „Beispiel: eine verschlüsselte Datei mit sops“sops mit age lässt die Schlüsselnamen lesbar und verschlüsselt nur die Werte:
sops --encrypt --age <recipient> --input-type dotenv --output-type dotenv \ secrets.plain.env > secrets/toolmesh.envDie verschlüsselte Datei und ein statisches sops-Binary werden schreibgeschützt gemountet, zum Beispiel in docker-compose.override.yml:
services: toolmesh: volumes: - /usr/local/bin/sops:/usr/local/bin/sops:ro - ./secrets/toolmesh.env:/run/secrets/toolmesh.env:roDie .env enthält dann keine Credentials mehr, nur noch die Einstellungen des Stores:
CREDENTIAL_STORE=commandTOOLMESH_CREDENTIAL_COMMAND=/usr/local/bin/sops -d --input-type dotenv --output-type dotenv /run/secrets/toolmesh.envWie sops an seine age-Identität kommt, entscheidet der Betreiber: eine schreibgeschützt gemountete Schlüsseldatei (SOPS_AGE_KEY_FILE ist ein Pfad, kein Secret), ein Schlüsselbefehl oder ein Mechanismus, der den Schlüssel erst zur Laufzeit freigibt. ergosum ist ein solcher Mechanismus: Es gibt Maschinen kurzlebige Identitäten, die eine geklonte Maschine nicht bekommt, und ergosumd secret get (ergosum v0.2.0 oder neuer) gibt ein versiegeltes Secret wie den age-Schlüssel nur auf der Maschine frei, an die es gebunden ist, an ihrem Ort. Der Schlüssel liegt dann nicht im Klartext auf der Platte, und eine kopierte Platte, ein VM-Image oder ein Backup enthält kein brauchbares Secret. Der Schlüssel selbst gehört nicht in .env oder environment:; er landete dort wie jeder andere Wert in der Konfiguration des Containers. Werte lassen sich mit sops secrets/toolmesh.env ändern; ToolMesh übernimmt sie beim nächsten Lauf oder Neustart.
Beispiel: Vault oder OpenBao über ihren Proxy
Abschnitt betitelt „Beispiel: Vault oder OpenBao über ihren Proxy“Vault Proxy (vault proxy, in OpenBao bao proxy) meldet sich mit seiner Auto-Auth-Methode an und fügt sein Token jeder Anfrage hinzu, die keines trägt (use_auto_auth_token). Der Befehl braucht dann kein eigenes Token, und nichts wird auf die Platte geschrieben:
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:8100Das KV-Secret secret/toolmesh enthält die Schlüssel so, wie eine dotenv-Datei sie enthielte (CREDENTIAL_GITHUB_TOKEN, TOOLMESH_API_KEY und so weiter). Das statische vault-Binary (oder bao, mit BAO_ADDR) wird schreibgeschützt gemountet; die Adresse ist kein Secret. Der Listener des Proxys sollte so gebunden sein, dass nur ToolMesh ihn erreicht, zum Beispiel auf Loopback in einem Netzwerk-Namespace, den er mit dem ToolMesh-Container teilt: Wer ihn erreicht, handelt mit dem Token des Proxys.
Auch die Anmeldung des Proxys selbst braucht ein Credential. Mit ergosum erhält die Maschine ein kurzlebiges JWT für die JWT-Auth-Methode von Vault oder OpenBao erst, nachdem ergosum sie an den Orten zurückgerufen hat, an die sie gebunden ist; so liegt kein langlebiges Secret wie eine AppRole-Secret-ID auf ihrer Platte.
Beispiel: kurzlebige Tokens
Abschnitt betitelt „Beispiel: kurzlebige Tokens“Ein kleines Programm, das ein Access-Token anfordert und es zusammen mit seiner Laufzeit abzüglich einer Reserve ausgibt, hält das Token frisch. Für ein Token, das eine Stunde gilt:
CREDENTIAL_EXAMPLE_TOKEN=eyJhbGciOi...RELOAD_IN=3300ToolMesh führt das Programm nach 55 Minuten erneut aus. Schlägt dieser Lauf fehl, bleibt das alte Token in Gebrauch, während die Wiederholungen länger warten (30 s, 60 s, 120 s, …); die Reserve sollte also für einige davon reichen. Das Programm kann auch statische Werte ausgeben, zum Beispiel indem es zuerst eine Datei entschlüsselt und das Token an seine Ausgabe anhängt.
Konfigurationsdateien
Abschnitt betitelt „Konfigurationsdateien“backends.yaml
Abschnitt betitelt „backends.yaml“Definiert, mit welchen Backends sich ToolMesh verbindet:
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" # Nur, wenn das Log sie verlangt (siehe unten): # credentials: [legacy_token] # allowed_hosts: [files.example.net, "*.example-cdn.com", media.example.com:8443]Tools werden automatisch mit einem Backend-Präfix exponiert (z.B. memorizer_retrieve_knowledge, github_list_repos).
Bindung an Credentials und Hosts
Abschnitt betitelt „Bindung an Credentials und Hosts“Jedes REST-Backend ist an seinen Eintrag in backends.yaml gebunden. Die Bindung kommt aus der Konfiguration des Betreibers, nie aus der DADL: Eine DADL kann die Credentials eines anderen Backends nicht lesen, und die Hosts, an die ihre eigenen Credentials gehen, sind begrenzt, wie unten beschrieben.
Eine DADL ist Code, den Sie installieren. Die DADL bestimmt, welche Anfragen ihr Backend mit dessen Credentials sendet; DADLs sollten deshalb nur aus vertrauenswürdigen Quellen kommen, wie ein Programm. ToolMesh hält die Credentials verschiedener Backends getrennt. Die Host-Bindung begrenzt als zweite Verteidigungslinie, wohin die eigenen Credentials eines Backends gehen können; aus einer bösartigen DADL macht sie keine sichere, so wenig wie eine Konfiguration aus einem bösartigen ToolMesh-Build einen sicheren macht.
-
Credentials. Jeder Eintrag hat einen Namensraum: seinen
namein Großbuchstaben, mit_statt-(Eintragshelly-cloud:CREDENTIAL_SHELLY_CLOUD_*). Ein Credential gehört zu dem Eintrag mit dem längsten Namensraum, mit dem sein Name beginnt;CREDENTIAL_GITHUB_ENTERPRISE_TOKENgehört also zu einem Eintraggithub-enterprise, nicht zu einem Eintraggithub. Jeder benannte Eintrag zählt, gleich mit welchem Transport: REST- und MCP-Einträge, Units und die Sub-Backends in einerunit.yaml. Ein Backend liest ein Credential nur, wenn sein Eintrag es besitzt, untercredentials:aufführt oder perenv:abbildet. Ein Credential in keinem Namensraum oder in einem, den sich zwei Schreibweisen eines Eintragsnamens teilen (my-apiundmy_api), gehört keinem Eintrag und muss aufgeführt werden. Die Aufteilung folgt bei jedem Reload der Konfiguration. REST-Einträge brauchen einenname; ein Eintrag ohne Namen wird abgewiesen. -
Hosts. Credentials, Session-Cookies, OAuth2-Token-Anfragen und Session-Logins gehen nur
- an den Host der wirksamen
base_url(dieurldes Eintrags, sonst diebase_urlder DADL) auf ihrem Port, bei einerhttp-base_urlauf Port 80 auch an ihrehttps-Form auf Port 443; - an die anderen Hosts ihrer registrierbaren Domain, auf dem Standardport;
- an die Einträge von
allowed_hosts:: einen Host (api.example.com), eine Wildcard für jede Subdomain ("*.example.com", in YAML in Anführungszeichen) oder eine IP-Adresse (10.0.0.5,"[2001:db8::1]"), jeweils auf dem Standardport, oder mit:portnur auf diesem Port. Ein Eintrag mit Schema, Pfad oder anderem Text ist ein Konfigurationsfehler, und das Backend wird nicht geladen.
Bei einer
https-base_urlgehen Credentials nur über https hinaus. Die registrierbare Domain richtet sich nach der Public Suffix List, die auch Domains von Hosting-Angeboten enthält:googleapis.comist ein solcher Suffix, also ist jeder Google-API-Host eine eigene Domain und brauchtallowed_hosts. Viele geteilte SaaS-Domains, auf denen jeder Kunde eine eigene Subdomain hat, etwaatlassian.net,zendesk.comoderservice-now.com, stehen nicht auf dieser Liste: Dort zählen die Tenants anderer Kunden zur selben registrierbaren Domain, und nur die DADL hält die Credentials auf dem eigenen Tenant. Für einen solchen Dienst empfiehlt sich eine selbst geprüfte DADL oder eine, deren Tools alle auf dem Host derbase_urlbleiben. Einetoken_uri, die ein Service-Account-Schlüssel fürjwt_bearermitbringt, gehört zu den eigenen Daten des Betreibers und wird nicht geprüft. - an den Host der wirksamen
-
Beim Laden geprüft. ToolMesh prüft die Credentials, die eine DADL liest, und die Ziele, die sie nennt (
token_url, absolute Tool-Pfade, den Health Check, die Login-URL einer Session), wenn es das Backend lädt: beim Start und bei jedem Reload vonbackends.yaml. Tools außerhalb voninclude_toolswerden nicht geprüft, da sie sich nicht aufrufen lassen; der Health Check wird in jedem Fall geprüft. Ein Backend, das weiter reicht, wird nicht geladen: EineERROR-Zeilebackend refusednennt jeden Verstoß und die genauen Zeilen, die in den Eintrag gehören (add_to_backends_yaml_entry). Die übrigen Backends laufen weiter, und die Security-Posture-Zusammenfassung beim Start führt die abgewiesenen auf. Einen globalen Schalter gibt es nicht, nur diese Zeilen je Eintrag. -
Bei jeder Anfrage erneut geprüft. Dieselben Regeln gelten überall, wo ein Credential hinausgeht, auch bei jedem Schritt einer Weiterleitung. Hat ein Eintrag keine
urlund ist die eigenebase_urlder DADL reineshttp, warnt ToolMesh beim Laden, dass Credentials unverschlüsselt hinausgehen. -
Namen. In
credentials:undenv:bestehen Namen aus Buchstaben, Ziffern und_.env:-Schlüssel werden in Großbuchstaben gelesen;credential_fooundCREDENTIAL_FOOsind also derselbe Schlüssel, und ein Eintrag mit beiden wird abgewiesen. -
Kein Secret.
credential: nonein einem Auth-Block ist der Platzhalter von DADLs für APIs ohne Authentifizierung. Er wird nie nachgeschlagen und braucht keine Bindung.
Zwei Einträge, die eine Zeile brauchen, jeweils benannt wie ihre 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]Nach einem Upgrade auf v0.6.0 im Log nach backend refused suchen und die genannten Zeilen ergänzen; der nächste Reload von backends.yaml lädt das Backend. Siehe Upgrade auf v0.6.0. Wie REST-Backends mit Weiterleitungen, Token-Anfragen, Pfadparametern und privaten Adressen umgehen, steht unter DADL.
MCP-Backends per HTTP
Abschnitt betitelt „MCP-Backends per HTTP“Ein MCP-Backend per HTTP bleibt beim Origin (Schema, Host und Port) seiner konfigurierten url, und sein api_key_env-Token geht nur dorthin. Eine Weiterleitung zu einem anderen Origin oder von https zu http wird abgewiesen, ebenso ein Message-Endpunkt auf einem anderen Origin, den ein Server mit dem älteren SSE-Transport ankündigt.
users.yaml
Abschnitt betitelt „users.yaml“Multi-User-Konfiguration für OAuth:
users: - username: alice password_hash: "$2a$12$..." company: acme plan: pro roles: [admin]apikeys.yaml
Abschnitt betitelt „apikeys.yaml“API-Key-Definitionen. Ein Eintrag benennt seinen Key als key_sha256 (der SHA-256 eines zufällig erzeugten Keys, direkt nachgeschlagen) oder als bcrypt-key_hash (einmal je Key nach dem Start verglichen); siehe 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
Abschnitt betitelt „authz.yaml“Optionale Grants und Denies: wer welche Tools aufrufen darf. Ohne diese Datei gilt ein Preset. Ein Deny gewinnt gegen jeden Grant und gegen das Preset. Kopieren Sie config/authz.yaml.example als Ausgangspunkt; ToolMesh übernimmt Änderungen innerhalb weniger Sekunden. Siehe Autorisierung. Dieselbe Datei definiert Koffer, Bündel von Tools, die ein Mensch auf Anfrage befristet freigibt, und die Approver, die sie freigeben dürfen; siehe Koffer und Freigaben.
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
Abschnitt betitelt „caller-classes.yaml“Ordnet Caller-IDs Vertrauensklassen zu:
classes: trusted: - claude-code - claude-desktop standard: - partner-* # Alles andere → "untrusted"