# Configuration: env vars, YAML files, secrets

> Reference of every ToolMesh env var and YAML config file: TOOLMESH_*, OPENFGA_*, AUDIT_* plus backends.yaml, users.yaml, apikeys.yaml — defaults included.

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

ToolMesh is configured entirely via environment variables and YAML files.

## Environment Variables

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

### Audit

| Variable | Default | Description |
|----------|---------|-------------|
| `AUDIT_STORE` | `log` | `log` (slog) or `sqlite` |
| `AUDIT_RETENTION_DAYS` | `90` | Retention for SQLite store |

### Authorization

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENFGA_API_URL` | `http://localhost:8080` | OpenFGA API endpoint. In Docker Compose use `http://openfga:8080` (set in `.env`). |
| `OPENFGA_STORE_ID` | *(empty)* | OpenFGA store ID (set by `./config/openfga/setup.sh`) |
| `OPENFGA_MODE` | `bypass` | `bypass` (no authz, dev only) or `restrict` (enforced, recommended for production) |

### Timeouts

| Variable | Default | Description |
|----------|---------|-------------|
| `TOOLMESH_MCP_TIMEOUT` | `120` | HTTP client timeout for MCP backends (seconds) |
| `TOOLMESH_EXEC_TIMEOUT` | `120` | Tool execution timeout (seconds) |

### 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_BACKENDS` or `DEBUG_FILE` in production environments.

### Credentials

Credentials are set as env vars with `CREDENTIAL_` prefix:

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

## Configuration Files

### backends.yaml

Defines which backends ToolMesh connects to:

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

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

### users.yaml

Multi-user configuration for OAuth:

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

### apikeys.yaml

API key definitions:

```yaml
keys:
  - key_hash: "$2a$12$..."
    username: ci-bot
    company: acme
    plan: standard
    roles: [read]
    caller_id: github-actions
```

### caller-classes.yaml

Maps caller IDs to trust classes:

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