Environment variables
Speedwave relies on a focused set of environment variables. Certain variables can be defined on the host prior to launching the application, while others are configured automatically inside containers based on your user profile. Variables marked host originate from your shell environment. Variables marked container are managed internally by Speedwave and should not be set manually.
The table layout corresponds to the structure outlined in the Configuration keys reference.
Complete variable reference
Section titled “Complete variable reference”| Variable | Scope | Description |
|---|---|---|
SPEEDWAVE_DATA_DIR | host | Overrides the default data directory ~/.speedwave/. Requires an absolute path. The directory basename isolates the entire instance. |
SPEEDWAVE_RESOURCES_DIR | host | Directs the CLI to packaged application resources. When unset, the CLI falls back to the marker file. |
SPW_TOKENS_DIR | container | Overrides the in-container path where the proxy reads mounted provider API keys (defaults to /tokens). |
POLICY_FILE | container | In-container path to the effective PII tokenization policy (/policy/policy.json), alongside the per-project encryption key. |
RUST_LOG | host | Logging level filter for the CLI and proxy container (defaults to info). |
ANTHROPIC_MODEL | container | For local and OpenRouter providers, the routed id of the picked model. Not set by Speedwave for Anthropic. |
CLAUDE_CODE_MAX_CONTEXT_TOKENS | container | Context window of a local or OpenRouter model, when discovery reported it. |
SPW_KEY_<ID> | container | Environment variable name passing the provider key identifier to the proxy. <ID> is the uppercase provider slug with - replaced by _. |
SPEEDWAVE_PLUGINS | container | Comma-separated list of enabled plugin slugs passed to the Claude container. |
WORKER_<SLUG_UPPER>_URL | container | Discovery URL for third-party MCP plugin workers, derived from service_id. |
WORKER_SLACK_URL, WORKER_GITHUB_URL, WORKER_GITLAB_URL, WORKER_ATLASSIAN_URL, WORKER_REDMINE_URL, WORKER_SHAREPOINT_URL, WORKER_OFFICE_URL, WORKER_PLAYWRIGHT_URL | container | Static discovery URLs for built-in integration workers. |
SPEEDWAVE_VERSION | container | Reserved variable injected into every plugin MCP service to record the runtime version. Plugins cannot override this variable. |
SPEEDWAVE_DATA_DIR
Section titled “SPEEDWAVE_DATA_DIR”SPEEDWAVE_DATA_DIR overrides the default storage path ~/.speedwave/. When unset or empty, Speedwave defaults to ~/.speedwave/. The value must be an absolute path; relative paths halt application execution.
The directory basename controls instance isolation and must match the pattern ^[a-z][a-z0-9-]{0,63}$ after stripping any leading periods (must begin with a lowercase letter, contain only lowercase alphanumeric characters and dashes, and not exceed 64 characters).
Speedwave derives the Lima VM instance name, the Docker Compose project prefix and the installed CLI name from this basename. A distinct SPEEDWAVE_DATA_DIR completely isolates the virtual machine, containers, and application data. For instance, .speedwave-dev maps to speedwave-dev, allowing development builds to run side by side with release installations without interference. Such an instance installs its CLI as speedwave-dev rather than speedwave, and that command finds its own data directory without the variable being set.
export SPEEDWAVE_DATA_DIR=/opt/speedwave-ciSPEEDWAVE_RESOURCES_DIR
Section titled “SPEEDWAVE_RESOURCES_DIR”SPEEDWAVE_RESOURCES_DIR points the CLI to bundled desktop application assets (such as /usr/lib/Speedwave). The Desktop application exports this variable automatically when spawning the CLI.
When invoking the CLI standalone in terminal sessions, the variable is typically unset. In this scenario, the CLI reads the path stored in ~/.speedwave/resources-dir. Once resolved, the value is populated into the process environment.
Self-update routines clear this variable before restarting the CLI binary, ensuring that freshly launched processes re-evaluate the marker file.
SPW_TOKENS_DIR
Section titled “SPW_TOKENS_DIR”The proxy container reads provider API keys from files mounted under /tokens by default. Setting SPW_TOKENS_DIR redirects the proxy to an alternative mount path inside the container.
POLICY_FILE
Section titled “POLICY_FILE”POLICY_FILE specifies the location of the effective PII tokenization policy inside the mcp-hub container. It defaults to /policy/policy.json within a read-only directory mounted into the hub, where the project AES encryption key is also located. See Tokenization for policy details.
RUST_LOG
Section titled “RUST_LOG”RUST_LOG controls the logging verbosity for the Speedwave CLI and proxy container (defaulting to info). See Logs and diagnostics for log handling details.
ANTHROPIC_MODEL
Section titled “ANTHROPIC_MODEL”For local and OpenRouter providers, Speedwave sets ANTHROPIC_MODEL (and the opus, sonnet, haiku and fable alias variables) to the routed id of the model picked in the composer, so every alias reaches the proxy route. For Anthropic, Speedwave does not set it: the composer pick is stored as model in the project’s Claude Code settings. A value you put in claude.env is still passed to the container, and Claude Code gives it priority over the settings file when a session starts, so it overrides the composer choice.
When a local or OpenRouter model has a known context window, Speedwave also sets CLAUDE_CODE_MAX_CONTEXT_TOKENS; when the window is unknown, it tells Claude Code not to enforce a limit it cannot know.
Provider keys: SPW_KEY_<ID>
Section titled “Provider keys: SPW_KEY_<ID>”Provider API keys are passed to the proxy container exclusively as variable names rather than raw key strings. Variable names are generated by converting provider identifiers to uppercase and replacing dashes with underscores (e.g. openrouter becomes SPW_KEY_OPENROUTER). The proxy reads the actual secret value directly from the mounted file (see SPW_TOKENS_DIR).
Plugin discovery: SPEEDWAVE_PLUGINS and WORKER_<SLUG_UPPER>_URL
Section titled “Plugin discovery: SPEEDWAVE_PLUGINS and WORKER_<SLUG_UPPER>_URL”SPEEDWAVE_PLUGINS provides a comma-separated list of enabled plugin slugs to the Claude container.
For each active MCP plugin, Speedwave injects a WORKER_<SID>_URL variable based on the plugin’s service_id (or slug if omitted), formatted in uppercase with underscores. For example, example-plugin maps to WORKER_EXAMPLE_PLUGIN_URL.
Built-in integration workers use static environment variables predefined within Speedwave: WORKER_SLACK_URL, WORKER_GITHUB_URL, WORKER_GITLAB_URL, WORKER_ATLASSIAN_URL, WORKER_REDMINE_URL, WORKER_SHAREPOINT_URL, WORKER_OFFICE_URL, and WORKER_PLAYWRIGHT_URL.
See Using plugins and the Configuration keys reference for further information.
SPEEDWAVE_VERSION
Section titled “SPEEDWAVE_VERSION”SPEEDWAVE_VERSION is a reserved environment variable injected by Speedwave into all plugin MCP services. It provides the runtime version so plugin tools can record which application release produced their output. Plugin manifests cannot define or override this variable.