# Configuration keys

Speedwave stores its config at `~/.speedwave/config.json`. A project can also carry a repo-level `.speedwave.json`, which is merged in but restricted to a narrow subset (see [what the repo file may set](#what-a-repo-speedwavejson-may-set)). If you are tuning container memory or CPU limits, this is the reference the [performance guide](/docs/guides/performance/) points you to.

## Top-level keys

| Key | Meaning |
| --- | --- |
| `projects` | All registered projects. Each entry is described below. |
| `active_project` | Name of the currently active project. |
| `selected_ide` | The IDE picked for the IDE bridge: an `ide_name` and a `port`. |
| `ui.beta_enabled` | [Turns on work-in-progress UI surfaces in the Desktop app](/docs/guides/beta-features/). Off by default. User-only, a repo file cannot set it. |
| `telemetry` | OTLP telemetry export settings. User-only, a repo file cannot set it. See below. |

## Project entry keys

Each item in `projects[]`:

| Key | Meaning |
| --- | --- |
| `name` | Project name. |
| `dir` | Absolute project directory on the host. |
| `claude` | Overrides for the container Speedwave runs Claude Code in. See below. |
| `integrations` | Per-project integration toggles. See below. |
| `plugin_settings` | Per-plugin settings values, keyed by plugin slug. |

## claude overrides

| Key | Meaning |
| --- | --- |
| `claude.env` | Environment variables passed to Claude Code in the container. |
| `claude.settings` | Patch merged into `~/.claude/settings.json`. |
| `claude.llm` | LLM provider and model configuration. See below. |

`claude.env` in the repo layer has two sets of keys stripped before merge: the Anthropic auth and routing keys (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_CUSTOM_HEADERS`), and a reserved list covering things like `PATH`, `HOME`, `LD_PRELOAD`, and `NODE_OPTIONS`. `ANTHROPIC_MODEL` is the one Anthropic key a repo may still set. For the full variable list and where each one applies, see [environment variables](/docs/reference/env-vars/).

## claude.llm keys

`claude.llm` carries both legacy flat fields and the current provider-list fields. The schema is versioned; the app writes version 3.

| Key | Meaning |
| --- | --- |
| `schema_version` | LLM schema version. Absent means legacy v1. |
| `providers` | Configured providers. Each entry has an `id`, a `kind`, and per-provider `model`. See below. |
| `active` | Active provider and model pointer for a project's sessions. |
| `proxy_enabled` | Proxy kill-switch. Defaults to `true`. User-only. |
| `provider` | Legacy flat provider id. Auto-migrated. |
| `model` | Legacy flat model id. Auto-migrated. |
| `base_url` | Legacy flat base URL for a local server. Auto-migrated. |
| `context_tokens` | Legacy flat context window, in tokens. |
| `has_api_key` | Legacy presence flag for an API key file. |
| `has_custom_headers` | Legacy presence flag for a custom-headers file. |

### providers[] keys

| Key | Meaning |
| --- | --- |
| `id` | Slug for this provider. Also names its token file and its `SPW_KEY_<ID>` env var. |
| `kind` | Backend class: `anthropic_oauth`, `anthropic_api_key`, `local`, or `open_router`. |
| `base_url` | Base URL, for the `local` kind. |
| `model` | Model this provider routes. The source of truth for routing. |
| `has_api_key` | True when the provider's key file exists on disk. |
| `context_tokens` | Context window of this provider's model, when known. |
| `has_custom_headers` | True when a migrated `local` entry's custom-headers file applies. |
**Note:** Schema v3 adds provenance quarantine: migrating a v1 or v2 config to v3 clears any foreign (non-Anthropic) model value found sitting under an `anthropic` provider entry.

### active keys

| Key | Meaning |
| --- | --- |
| `provider_id` | The `id` of the selected `providers[]` entry. |
| `model` | Pointer to the active provider's model, not the routing authority. If the provider entry has no model, an active-only model is dropped. |

## integrations keys

`integrations` holds per-project enable toggles, each `{ "enabled": <bool> }`. All defaults are disabled.

| Key | Meaning |
| --- | --- |
| `integrations.slack` | Slack |
| `integrations.sharepoint` | SharePoint |
| `integrations.redmine` | Redmine |
| `integrations.gitlab` | GitLab |
| `integrations.github` | GitHub |
| `integrations.atlassian` | Atlassian |
| `integrations.office` | Office documents |
| `integrations.playwright` | Playwright |
| `integrations.context7` | Context7 |
| `integrations.os.reminders` | macOS Reminders |
| `integrations.os.calendar` | macOS Calendar |
| `integrations.os.mail` | macOS Mail |
| `integrations.os.notes` | macOS Notes |
| `integrations.plugins.<slug>` | Toggle for an installed plugin. |

## telemetry keys

[`telemetry` configures OTLP export for Speedwave's own metrics and logs](/docs/guides/telemetry/). It is a top-level, user-only key: a repo `.speedwave.json` cannot set it. The Desktop app exposes the same fields under Settings > Telemetry.

| Key | Meaning | Default |
| --- | --- | --- |
| `telemetry.enabled` | Master switch. When `true`, an `endpoint` is required or resolution fails with an error. | `false` |
| `telemetry.endpoint` | OTLP collector endpoint URL. | none |
| `telemetry.protocol` | Transport: `grpc`, `http/protobuf`, or `http/json`. | `grpc` |
| `telemetry.export_metrics` | Export the metrics signal. | `true` |
| `telemetry.export_logs` | Export the logs/events signal. | `false` |
| `telemetry.headers` | Collector auth headers, `Key=Value,...`. Secret. | none |
| `telemetry.resource_attributes` | Custom resource attributes, `key=value,...`. | none |
| `telemetry.include_account_uuid` | Include the account UUID as a metric attribute. | `true` |
| `telemetry.log_user_prompts` | Privacy gate: include user prompt content. | `false` |
| `telemetry.log_assistant_responses` | Privacy gate: include assistant response content. | `false` |
| `telemetry.log_tool_details` | Privacy gate: include tool command and parameter details. | `false` |
| `telemetry.log_raw_api_bodies` | Privacy gate: include raw API request and response bodies. | `false` |
| `telemetry.metric_export_interval_ms` | Metrics export interval, in milliseconds. | provider default |
| `telemetry.logs_export_interval_ms` | Logs export interval, in milliseconds. | provider default |

When `enabled` is `false`, Speedwave emits only the `CLAUDE_CODE_ENABLE_TELEMETRY` master-switch variable and nothing else. When it is `true`, it also emits `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_METRICS_INCLUDE_ACCOUNT_UUID`, the four `OTEL_LOG_*` privacy-gate variables, and the two export-interval variables. See [environment variables](/docs/reference/env-vars/) for where these apply.

An IT admin can lock any of these fields from a device-level `managed-config.json` (macOS: `/Library/Application Support/Speedwave/managed-config.json`; Windows: `<ProgramData>/Speedwave/managed-config.json`). A locked field always wins over the user's `telemetry` config, the file rejects unknown keys outright, and a malformed or unresolvable policy is caught at startup and stops Speedwave from launching rather than falling back silently.

## What a repo .speedwave.json may set

A checked-in `.speedwave.json` is parsed with only `claude` and `integrations`, and is sanitized further on merge.

| Key | Repo layer |
| --- | --- |
| `claude.env` `ANTHROPIC_MODEL` | Allowed |
| `claude.env` Anthropic auth/routing keys | Stripped |
| `claude.env` reserved keys (`PATH`, `LD_PRELOAD`, and similar) | Stripped |
| `claude.llm.model` | Allowed, as a suggestion |
| `claude.llm.provider` / `base_url` / `context_tokens` | Ignored |
| `claude.llm.providers` / `active` | Ignored, user-only |
| `claude.llm.proxy_enabled` | Ignored, user-only |
| `integrations.*` | Allowed |
| `ui.beta_enabled`, `telemetry`, `projects`, `active_project`, `selected_ide`, `plugin_settings` | Not present in the repo schema |

## See also

- [Environment variables](/docs/reference/env-vars/)
- [Tune memory and CPU caps](/docs/guides/performance/)