Token and credential paths

All credentials and tokens managed by Speedwave are stored within a unified data directory (defaulting to ~/.speedwave/). Setting the SPEEDWAVE_DATA_DIR environment variable relocates the entire directory tree. This variable is evaluated once at process initialization. For the full list of startup variables, see Environment variables; for credential isolation guarantees, see Credentials management.

Directory structure

• Directory~/.speedwave/

  • Directorytokens/

    • Directory<project> /

      • Directory<service> / worker credentials for a specific service

        • … credential files
        • _settings.json non-secret plugin settings
      • Directoryllm/

        • <provider_id> _api_key LLM provider API key
  • Directoryclaude-home/

    • Directory<project> /

      • Directory.claude/

        • .credentials.json Anthropic OAuth tokens (managed by Claude Code)
  • Directoryoauth/

    • Directory<project> /

      • <service> .json plugin OAuth refresh tokens (outside mount points)
  • Directoryplugin-state/

    • Directory<slug> /

      • bridge-token saved host bridge authentication token
  • Directoryide-bridge/

    • <port> .lock IDE Bridge UUID lock token
  • Directorypolicies/

    • Directory<project> /

      • policy.json resolved PII protection policy
      • key PII tokenization encryption key
  • Directoryaudit/

    • Directory<project> /

      • audit-proxy.jsonl proxy PII detection log
      • audit-hub.jsonl hub PII detection log

Variables: <project> is the project namespace, <service> is the MCP service identifier, <provider_id> is the LLM provider identifier, <slug> is the plugin slug, and <port> is the IDE Bridge port.

Path overview

Path	Contents	Mount destination	File permissions
tokens/<project>/<service>/<file>	Service credentials for a single MCP service	Read-only in that service’s worker container under /tokens	file 0o600, directory 0o700
tokens/<project>/llm/<provider_id>_api_key	LLM provider API key	Read-only in proxy container under /tokens as SPW_KEY_<PROVIDER_ID>	file 0o600, directory 0o700
tokens/<project>/<service>/_settings.json	Non-secret settings for a single plugin	Read-only in that plugin’s worker under /tokens	file 0o600, directory 0o700
policies/<project>/policy.json	Resolved PII policy for the project	Read-only in mcp-hub under /policy as POLICY_FILE=/policy/policy.json	file 0o600, directory 0o700
policies/<project>/key	32-byte hex AES-128-SIV tokenization key	Read-only in mcp-hub under /policy	file 0o600, directory 0o700
audit/<project>/audit-*.jsonl	PII detection event logs (excluding original data values)	Read-write in proxy and mcp-hub under /audit	n/a
claude-home/<project>/.claude/.credentials.json	Anthropic OAuth authentication tokens	Read-write in ${CLAUDE_HOME} under /home/speedwave	managed by Claude Code
oauth/<project>/<service>.json	Plugin OAuth refresh tokens and client secrets	Unmounted; read directly by the host oauth worker	file 0o600, directory 0o700
plugin-state/<slug>/bridge-token	Persistent host bridge authentication token	Unmounted	file 0o600 (when present)
ide-bridge/<port>.lock	UUID v4 lock token for IDE Bridge	Read-only under /home/speedwave/.claude/ide/	file 0o600, directory 0o700

Service worker credentials

Each MCP service requiring credentials receives an isolated directory at tokens/<project>/<service>/ containing the files declared in its manifest. Speedwave creates this folder only when credentials are defined. If a plugin defines a settings schema, non-secret parameters are placed in _settings.json, while sensitive values remain stored in dedicated credential files. This directory is mounted read-only into the corresponding worker container at /tokens, with the SecurityCheck rule PLUGIN_TOKEN_PATH_MISMATCH validating the mount path prior to container startup.

LLM provider keys

Provider keys configured in claude.llm are saved to tokens/<project>/llm/<provider_id>_api_key. The llm directory is mounted read-only exclusively inside the proxy container, with each key exposed as an environment variable named SPW_KEY_<PROVIDER_ID>:

Example SPW_KEY names and paths

openrouter     -> SPW_KEY_OPENROUTER
my-anthropic   -> SPW_KEY_MY_ANTHROPIC

tokens/proj/llm/openrouter_api_key

Caution

LLM provider keys are never exposed to the claude container. The SecurityCheck rule PROXY_VOLUMES restricts proxy mounts strictly to config:ro, tokens/<project>/llm:/tokens:ro, and usage:rw. Direct Anthropic API keys represent the single exception, remaining in the claude container environment for direct forwarding by Claude Code.

Anthropic OAuth credentials

Anthropic OAuth credentials reside at claude-home/<project>/.claude/.credentials.json, where Claude Code manages and refreshes them within the ${CLAUDE_HOME} mount at /home/speedwave. Speedwave configures the mount definition in compose and clears this file upon running speedwave logout.

Plugin OAuth refresh tokens

OAuth refresh tokens and client secrets for plugins are stored outside container mount points at oauth/<project>/<service>.json, ensuring that all directories under tokens/ remain read-only when mounted into containers.

Plugin state and bridge tokens

Dynamic plugin state is maintained under plugin-state/<slug>/, isolated from signed plugin packages. For example, host bridge tokens (plugin-state/<slug>/bridge-token) are created with 0o600 permissions when the plugin manifest enables persistent_token.

IDE Bridge lock files

The IDE Bridge lock file (ide-bridge/<port>.lock) holds an ephemeral UUID v4 authentication token generated on application startup. It is written with 0o600 permissions in a 0o700 parent directory and mounted read-only into the container at /home/speedwave/.claude/ide/.

PII policy files and encryption keys

The owner-only directory policies/<project>/ contains policy.json (the evaluated PII protection policy) and key (a 32-byte hexadecimal AES-128-SIV encryption key generated on first use). The entire directory is mounted read-only into the Tool Gateway (mcp-hub) at /policy, with POLICY_FILE=/policy/policy.json pointing to the policy file. For operational details, see Tokenization.

Loss of this key file prevents decryption of any tokens previously generated within that project. Speedwave maintains no secondary lookup table: the encryption key is the sole mechanism for restoring original values.

PII detection audit logs

The audit/<project>/ directory holds audit-proxy.jsonl and audit-hub.jsonl, which log PII tokenization events without persisting original values. The directory is mounted read-write in proxy and mcp-hub at /audit. See Logs and diagnostics for log structure details.

Filesystem permissions

Speedwave sets credential files to 0o600 and parent directories to 0o700, owned by your local user account. On Windows, this corresponds to an explicit discretionary access control list (DACL) granting full control to your account.

On Unix-like systems, Speedwave verifies these permissions at startup and corrects misconfigured permission bits. On Windows, DACL settings are applied once during file creation.