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

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	Specifies the target Claude model for the Claude Code process in the container.
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

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 both the Lima VM instance name and Docker Compose project prefix 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.

shell

export SPEEDWAVE_DATA_DIR=/opt/speedwave-ci

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

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

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

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

ANTHROPIC_MODEL sets the target Claude model for the Claude Code process in the container. The value is determined with claude.llm.model taking precedence over claude.env.ANTHROPIC_MODEL.

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

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

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.