Configuration keys
Speedwave maintains its global configuration in ~/.speedwave/config.json. Individual projects can also provide an optional .speedwave.json file in their repository, which is merged with global settings across a strictly limited scope (see repository configuration capabilities).
Top-level properties
Section titled “Top-level properties”| Property | Description |
|---|---|
projects | List of registered projects. Entry structure is detailed below. |
active_project | Name of the currently active project. |
selected_ide | IDE selection for the IDE Bridge: ide_name and port. |
ui.beta_enabled | Enables early-stage features in the Desktop application. Also controls PII tokenization enforcement (see policy properties). Disabled by default; configured only by the user. |
telemetry | OTLP telemetry export configuration. Configured exclusively by the user. Detailed below. |
Project entry properties
Section titled “Project entry properties”Each item within projects[]:
| Property | Description |
|---|---|
name | Project name. |
dir | Absolute path to the project directory on the host machine. |
claude | Configuration overrides for the container running Claude Code. Detailed below. |
integrations | Integration activation toggles for the project. Detailed below. |
plugin_settings | Plugin configuration values indexed by plugin slug. |
policy | Data protection and PII tokenization policies for the project. Detailed below. |
Claude overrides
Section titled “Claude overrides”| Property | Description |
|---|---|
claude.env | Environment variables passed to Claude Code in the container. |
claude.settings | Values merged into ~/.claude/settings.json. |
claude.llm | Model provider and routing configuration. Detailed below. |
Before merging repository-level .speedwave.json settings into claude.env, two sets of properties are filtered out: Anthropic authorization and routing keys (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_CUSTOM_HEADERS) and reserved system variables (PATH, HOME, LD_PRELOAD, NODE_OPTIONS, etc.). The only Anthropic variable a repository may set is ANTHROPIC_MODEL. For the complete list of variables and their scopes, see Environment variables.
Claude LLM properties
Section titled “Claude LLM properties”The claude.llm section uses schema version 3, featuring structured provider arrays while maintaining backwards compatibility for earlier flat definitions.
| Property | Description |
|---|---|
schema_version | LLM configuration schema version (3). Absence indicates version 1. |
providers | Configured provider entries. Each contains id, kind, and model fields. Detailed below. |
active | Active provider and model selection for the project session. |
proxy_enabled | Emergency proxy kill-switch (defaults to true). Configured exclusively by the user. |
provider | Legacy flat provider identifier (migrated automatically). |
model | Legacy flat model identifier (migrated automatically). |
base_url | Legacy flat local server URL (migrated automatically). |
context_tokens | Legacy flat context window size in tokens. |
has_api_key | Legacy flag indicating presence of an API key file. |
has_custom_headers | Legacy flag indicating presence of custom headers. |
Properties in providers[]
Section titled “Properties in providers[]”| Property | Description |
|---|---|
id | Provider identifier (slug). Defines the token filename and the SPW_KEY_<ID> environment variable name. |
kind | Provider backend type: anthropic_oauth, anthropic_api_key, local, or open_router. |
base_url | Endpoint URL for local provider types. |
model | Target model name used for routing decisions. |
has_api_key | Set to true when a provider key file exists on disk. |
context_tokens | Model context window size in tokens (if known). |
has_custom_headers | Set to true when custom headers are configured for a migrated local entry. |
Properties in active
Section titled “Properties in active”| Property | Description |
|---|---|
provider_id | Identifier id matching an entry in providers[]. |
model | Specifies the active model. If the referenced provider entry does not specify a model, values configured solely in active are rejected. |
Integrations properties
Section titled “Integrations properties”The integrations section stores activation flags for individual integrations in the format { "enabled": <bool> }. All integrations are disabled by default.
| Property | Description |
|---|---|
integrations.slack | Slack integration |
integrations.sharepoint | SharePoint integration |
integrations.redmine | Redmine integration |
integrations.gitlab | GitLab integration |
integrations.github | GitHub integration |
integrations.atlassian | Atlassian integration (Jira, Confluence) |
integrations.office | Office documents integration |
integrations.playwright | Playwright test automation |
integrations.context7 | Context7 integration |
integrations.os.reminders | macOS Reminders |
integrations.os.calendar | macOS Calendar |
integrations.os.mail | macOS Mail |
integrations.os.notes | macOS Notes |
integrations.plugins.<slug> | Installed plugin activation toggle |
Policy properties
Section titled “Policy properties”The policy property configures PII tokenization policies for the project. Tokenization enforcement is active when ui.beta_enabled is true or when policies are mandated via MDM. When enforcement is active and policy is omitted, the default built-in setting tokenizes all seven standard rules.
| Property | Description |
|---|---|
policy.policies | Enabled policy identifiers: built-in strict, gdpr-art32, eu-ai-act-art5, or a custom identifier from policy.customPolicies. |
policy.customPolicies | Custom policy definitions selected via policy.policies. Detailed below. |
Properties in customPolicies[]
Section titled “Properties in customPolicies[]”| Property | Description |
|---|---|
id | Unique policy identifier (cannot conflict with built-in names). |
name | Human-readable name displayed in the Desktop application. |
categories | {tokenize, log} flags for each built-in rule. Omitted rules are disabled. |
rules | Custom regex-based rules with {tokenize, log} flags and optional checksum validators (pesel, nip, iban, luhn). |
keywords | Keyword substitutions: {match, alias, caseSensitive}. Matched terms are replaced with their assigned alias. |
Organizations can also enforce policies globally using managed-config.json.
Telemetry properties
Section titled “Telemetry properties”The telemetry section configures OTLP telemetry export for Speedwave metrics and logs. This is a top-level setting configured exclusively by the user; repository .speedwave.json files cannot set it.
| Property | Description | Default |
|---|---|---|
telemetry.enabled | Master telemetry toggle. When true, endpoint is required. | false |
telemetry.endpoint | OTLP collector destination URL. | none |
telemetry.protocol | Transport protocol: grpc, http/protobuf, or http/json. | grpc |
telemetry.export_metrics | Enables metrics export. | true |
telemetry.export_logs | Enables log and event export. | false |
telemetry.headers | Collector authentication headers in Key=Value,... format (sensitive). | none |
telemetry.resource_attributes | Custom resource attributes in key=value,... format. | none |
telemetry.include_account_uuid | Includes user account UUID in exported metrics. | true |
telemetry.log_user_prompts | Privacy control: includes raw user prompt content. | false |
telemetry.log_assistant_responses | Privacy control: includes assistant response text. | false |
telemetry.log_tool_details | Privacy control: includes tool parameters and commands. | false |
telemetry.log_raw_api_bodies | Privacy control: includes 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 sets only the CLAUDE_CODE_ENABLE_TELEMETRY environment variable. When true, it also configures OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_HEADERS, OTEL_RESOURCE_ATTRIBUTES, OTEL_METRICS_INCLUDE_ACCOUNT_UUID, four OTEL_LOG_* privacy variables, and export interval values. See Environment variables for environmental scoping.
IT administrators can lock any of these settings using a system-level managed-config.json file (macOS: /Library/Application Support/Speedwave/managed-config.json; Windows: <ProgramData>/Speedwave/managed-config.json). Managed settings override user configurations. Invalid managed files or unresolvable policies halt startup to prevent fallback to less restrictive defaults.
The file also includes a forced_policies list specifying policy identifiers required for all projects. The presence of an identifier activates enforcement; unrecognized policy IDs halt project initialization.
What a repository .speedwave.json can configure
Section titled “What a repository .speedwave.json can configure”Repository .speedwave.json files are parsed only for claude and integrations properties, subject to sanitization rules:
| Property | Repository handling |
|---|---|
claude.env ANTHROPIC_MODEL | Allowed |
claude.env Anthropic routing and auth keys | Removed during merge |
claude.env reserved system variables (PATH, LD_PRELOAD, etc.) | Removed during merge |
claude.llm.model | Allowed (treated as a suggestion) |
claude.llm.provider / base_url / context_tokens | Ignored |
claude.llm.providers / active | Ignored (user-only setting) |
claude.llm.proxy_enabled | Ignored (user-only setting) |
integrations.* | Allowed |
ui.beta_enabled, telemetry, projects, active_project, selected_ide, plugin_settings | Not present in repository schema |