Container topology
Speedwave executes all project services as containerized workloads within a managed Linux virtual machine, providing full process isolation from your host operating system.
Virtual machine architecture
Section titled “Virtual machine architecture”Speedwave embeds its own lightweight Linux virtualization layer and container runtime directly within the application, operating independently of third-party desktop container tools.
On macOS, Speedwave provisions a dedicated Lima virtual machine using Apple’s native Virtualization Framework. Lima is bundled internally and operates isolated from any other virtual machine installations on the system.
Virtual machine resources are dynamically allocated based on host specifications: allocating half of available host RAM, clamped between a minimum of 4 GiB and a maximum of 32 GiB (for example, an 8 GiB VM on a 16 GiB Mac).
On Windows, Speedwave provisions a dedicated WSL2 distribution named Speedwave on top of Hyper-V. The initial provisioning is performed by the Setup Wizard with an offline installer fallback. Upon startup, Speedwave verifies critical environment invariants, ensuring nerdctl version pinning and configuring DrvFs filesystem options to avoid permission mismatches.
WSL2 manages CPU and memory scheduling dynamically. Speedwave configures VPN compatibility parameters in the shared .wslconfig file, ensuring corporate intranet endpoints remain reachable within the distribution.
Both operating systems require at least 16 GiB of host RAM. macOS verifies memory availability on startup and displays an alert if system memory is below the recommended threshold.
Speedwave automatically translates host filesystem paths for container mounts: standard Windows paths (such as C:\Users\...) map to /mnt/c/Users/..., and native WSL UNC paths within the Speedwave distribution resolve directly. Paths pointing to external distributions or unmapped network shares are rejected with clear configuration instructions.
Per-project container topology
Section titled “Per-project container topology”Every project executes inside an isolated Docker bridge network (speedwave_<project>_network), preventing cross-project discovery. The standard topology includes:
speedwave_<project>_claude: Runs the Claude Code process without host sockets or external service tokens.speedwave_<project>_proxy: Mediates and monitors LLM provider traffic on port 4000.speedwave_<project>_mcp_hub: The central MCP Gateway exposed to Claude on port 4000.speedwave_<project>_mcp_<service>: Dedicated worker containers instantiated for each active integration.
flowchart TB
subgraph VM["Linux VM (Lima on macOS / WSL2 on Windows)"]
subgraph NET["speedwave_<project>_network"]
Claude["claude<br/>zero tokens, no socket"]
Proxy["proxy<br/>port 4000"]
Hub["mcp_hub<br/>port 4000, zero tokens"]
W1["mcp_<service> worker<br/>/tokens:ro"]
W2["mcp_<service> worker<br/>/tokens:ro"]
Claude -->|"LLM traffic"| Proxy
Claude -->|"tools"| Hub
Hub --> W1
Hub --> W2
end
end
The Claude container connects only to the local proxy (for model requests) and the MCP Hub (for tool discovery and execution). It never connects to external service endpoints directly. Individual worker containers mount their respective credentials in read-only mode, and the central hub maintains zero credentials. See the Isolation model and Workers architecture for complete details.
Cross-platform consistency
Section titled “Cross-platform consistency”Container images and security profiles are identical across macOS and Windows. The platform abstraction layer ensures uniform model execution regardless of the underlying host operating system.