Runtime architecture

Every workspace in Speedwave operates inside a managed container topology hosted within an isolated Linux virtual machine (Lima on macOS, WSL2 on Windows). This architecture abstracts container orchestration away from user management while strictly isolating execution.

Claude Code executes within the central runtime container. It holds no privileges to create containers and has zero access to the container management socket. When authenticating via Anthropic OAuth subscriptions, session bearer tokens are forwarded dynamically through the local proxy. When using direct Anthropic API keys, keys are injected into the Claude container to support /model parameter aliases and native 1M context tiers. Claude communicates exclusively with two local endpoints: the Speedwave LLM Proxy for upstream inference and the Tool Gateway (MCP Hub) for tool routing.

flowchart TB
  subgraph VM["Linux VM (Lima on macOS / WSL2 on Windows)"]
    subgraph NET["Per-project bridge network"]
      Claude["Claude container<br/>No engine socket"]
      Proxy["Speedwave Proxy<br/>LLM traffic"]
      Hub["Tool Gateway (MCP Hub)<br/>Zero credentials"]
      W1["Integration worker<br/>Scoped read-only token"]
      W2["Integration worker<br/>Scoped read-only token"]
      Claude --> Proxy
      Claude --> Hub
      Hub --> W1
      Hub --> W2
    end
  end

The entire container topology executes inside a dedicated bridge network scoped per project (speedwave_<project>_network), preventing cross-workspace network visibility.

Architectural modules

Container topology Container definitions, image build pipelines, and virtual machine sizing.

Workers architecture Worker lifecycle, credential mounting, and host bridge mediators.

Tool Gateway Centralized MCP routing hub, search_tools, and execute_code mechanics.

Plugin mechanism Cryptographic signature verification, local image builds, and runtime extensions.

Updates and auto-recovery Reconciliation state machines, cryptographic hashes, and image rebuilds.