# Konfiguration: ENV-Variablen, YAML-Dateien

> Referenz aller ToolMesh-ENV-Variablen und YAML-Configs: TOOLMESH_*, AUDIT_*, Credential-Stores (CREDENTIAL_* oder ein Befehl), Login-Limits, plus backends.yaml, users.yaml, apikeys.yaml und authz.yaml mit Koffern und Approvern — mit Defaults.

Canonical: https://www.toolmesh.io/de/configuration/

ToolMesh wird vollständig über Umgebungsvariablen und YAML-Dateien konfiguriert.

## Umgebungsvariablen

### 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`](/de/authentication/#nicht-authentifizierte-anfragen) und ist die Basis der Freigabelinks von [`request_grant`](/de/kits/#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](/de/authentication/#client-adresse). |

### Login-Drosselung

Fehlgeschlagene Passwort-Logins unter `/authorize` und fehlgeschlagene API-Keys sind begrenzt; was zählt und wie eine Sperre endet, steht unter [Authentifizierung](/de/authentication/#login-drosselung), für die API-Keys unter [Drosselung von API-Keys](/de/authentication/#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

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](/de/authentication/#die-login-seite).

### Audit

| Variable | Standard | Beschreibung |
|----------|----------|--------------|
| `AUDIT_STORE` | `log` | `log` (slog) oder `sqlite` |
| `AUDIT_RETENTION_DAYS` | `90` | Aufbewahrungsdauer für SQLite-Store |

### Autorisierung

Standardmäßig aktiv, ohne Setup; siehe [Autorisierung](/de/authorization/). Koffer und Approver stehen in derselben Grants-Datei; siehe [Koffer und Freigaben](/de/kits/).

| 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

| 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](/de/output-gate/).

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

| 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](/de/code-mode/#sicherheit).

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

| 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_BACKENDS` oder `DEBUG_FILE` niemals in Produktionsumgebungen aktivieren.

### 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 liefen
- `call_count` / `error_count` — erfolgreiche und fehlgeschlagene Aufrufe seit dem letzten Report
- `version` — die ToolMesh-Version
- `mcp_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:

```bash
DO_NOT_SEND_ANONYMOUS_STATISTICS=yes
```

## 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](#bindung-an-credentials-und-hosts).

### Embedded Store

Credentials werden als Umgebungsvariablen mit `CREDENTIAL_`-Präfix gesetzt:

```bash
CREDENTIAL_GITHUB_TOKEN=ghp_xxxxx
CREDENTIAL_STRIPE_KEY=sk_live_xxxxx
CREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxx
```

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

| 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 vorangestelltes `export ` wird ignoriert.
- Werte ohne Anführungszeichen werden getrimmt, ein `#` nach einem Leerzeichen oder Tab beginnt einen Kommentar, und `\n` steht 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": "..."}}` ergibt `CREDENTIAL_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_duration` von Vault wird nicht verwendet; ein KV-Secret der Version 2 meldet dort `0`.

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.

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

Sonst 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:

```text
time() - toolmesh_credential_store_last_success_timestamp_seconds > 7200
```

### Beispiel: eine verschlüsselte Datei mit sops

sops mit age lässt die Schlüsselnamen lesbar und verschlüsselt nur die Werte:

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

Die verschlüsselte Datei und ein statisches `sops`-Binary werden schreibgeschützt gemountet, zum Beispiel in `docker-compose.override.yml`:

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

Die `.env` enthält dann keine Credentials mehr, nur noch die Einstellungen des Stores:

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

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

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:

```bash
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
```

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

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:

```bash
CREDENTIAL_EXAMPLE_TOKEN=eyJhbGciOi...
RELOAD_IN=3300
```

ToolMesh 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

### backends.yaml

Definiert, mit welchen Backends sich ToolMesh verbindet:

```yaml
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

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 `name` in Großbuchstaben, mit `_` statt `-` (Eintrag `shelly-cloud`: `CREDENTIAL_SHELLY_CLOUD_*`). Ein Credential gehört zu dem Eintrag mit dem **längsten** Namensraum, mit dem sein Name beginnt; `CREDENTIAL_GITHUB_ENTERPRISE_TOKEN` gehört also zu einem Eintrag `github-enterprise`, nicht zu einem Eintrag `github`. Jeder benannte Eintrag zählt, gleich mit welchem Transport: REST- und MCP-Einträge, Units und die Sub-Backends in einer `unit.yaml`. Ein Backend liest ein Credential nur, wenn sein Eintrag es besitzt, unter `credentials:` aufführt oder per `env:` abbildet. Ein Credential in keinem Namensraum oder in einem, den sich zwei Schreibweisen eines Eintragsnamens teilen (`my-api` und `my_api`), gehört keinem Eintrag und muss aufgeführt werden. Die Aufteilung folgt bei jedem Reload der Konfiguration. REST-Einträge brauchen einen `name`; 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` (die `url` des Eintrags, sonst die `base_url` der DADL) auf ihrem Port, bei einer `http`-`base_url` auf Port 80 auch an ihre `https`-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 `:port` nur auf diesem Port. Ein Eintrag mit Schema, Pfad oder anderem Text ist ein Konfigurationsfehler, und das Backend wird nicht geladen.

  Bei einer `https`-`base_url` gehen Credentials nur über https hinaus. Die registrierbare Domain richtet sich nach der Public Suffix List, die auch Domains von Hosting-Angeboten enthält: `googleapis.com` ist ein solcher Suffix, also ist jeder Google-API-Host eine eigene Domain und braucht `allowed_hosts`. Viele geteilte SaaS-Domains, auf denen jeder Kunde eine eigene Subdomain hat, etwa `atlassian.net`, `zendesk.com` oder `service-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 der `base_url` bleiben. Eine `token_uri`, die ein Service-Account-Schlüssel für `jwt_bearer` mitbringt, gehört zu den eigenen Daten des Betreibers und wird nicht geprüft.
- **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 von `backends.yaml`. Tools außerhalb von `include_tools` werden 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: Eine `ERROR`-Zeile `backend refused` nennt 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 `url` und ist die eigene `base_url` der DADL reines `http`, warnt ToolMesh beim Laden, dass Credentials unverschlüsselt hinausgehen.
- **Namen.** In `credentials:` und `env:` bestehen Namen aus Buchstaben, Ziffern und `_`. `env:`-Schlüssel werden in Großbuchstaben gelesen; `credential_foo` und `CREDENTIAL_FOO` sind also derselbe Schlüssel, und ein Eintrag mit beiden wird abgewiesen.
- **Kein Secret.** `credential: none` in 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:

```yaml
  - 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](/de/upgrading/). Wie REST-Backends mit Weiterleitungen, Token-Anfragen, Pfadparametern und privaten Adressen umgehen, steht unter [DADL](/de/dadl/#anfragen-an-rest-backends).

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

Multi-User-Konfiguration für OAuth:

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

### 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](/de/authentication/#api-keys).

```yaml
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
```

### 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](/de/authorization/#grants-configauthzyaml). 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](/de/kits/).

```yaml
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

Ordnet Caller-IDs Vertrauensklassen zu:

```yaml
classes:
  trusted:
    - claude-code
    - claude-desktop
  standard:
    - partner-*
  # Alles andere → "untrusted"
```
