Topologia kontenerów

Speedwave uruchamia usługi każdego projektu w postaci skonteneryzowanych procesów wewnątrz lekkiej maszyny wirtualnej Linuksa, zapewniając pełną izolację od systemu operacyjnego hosta.

Architektura maszyny wirtualnej

Speedwave posiada wbudowaną warstwę wirtualizacji oraz własne środowisko uruchomieniowe kontenerów, działając całkowicie niezależnie od zewnętrznych narzędzi kontenerowych.

macOS

W systemie macOS Speedwave uruchamia maszynę wirtualną Lima opartą na natywnym środowisku Apple Virtualization Framework. Lima jest zintegrowana z aplikacją i działa w pełnej separacji od innych instalacji w systemie.

Zasoby maszyny wirtualnej są przydzielane dynamicznie: połowa dostępnej pamięci RAM hosta (w przedziale od 4 GiB do 32 GiB – np. 8 GiB RAM dla Maca z 16 GiB pamięci).

Windows

W systemie Windows Speedwave korzysta z wydzielonej dystrybucji WSL2 o nazwie Speedwave opartej na Hyper-V. Wstępna instalacja jest przeprowadzana przez kreator konfiguracji z możliwością instalacji w trybie offline. Przy każdym uruchomieniu Speedwave weryfikuje środowisko, dbając o przypięcie wersji nerdctl oraz prawidłowe opcje montowania DrvFs, aby uniknąć problemów z uprawnieniami kontenerów.

WSL2 zarządza przydziałem pamięci i procesora automatycznie. Speedwave konfiguruje parametry zgodności z sieciami VPN w pliku .wslconfig, zapewniając łączność z wewnętrznymi usługami firmowymi.

Obie platformy wymagają co najmniej 16 GiB pamięci RAM. System macOS sprawdza dostępność pamięci przy starcie i wyświetla ostrzeżenie w razie niespełnienia tego warunku.

Speedwave automatycznie mapuje ścieżki systemu plików hosta na ścieżki wewnątrz kontenerów: litery dysków w Windows (np. C:\Users\...) są tłumaczone na /mnt/c/Users/..., a ścieżki UNC wewnątrz dystrybucji Speedwave mapują się bezpośrednio. Ścieżki wskazujące na inne dystrybucje WSL lub zewnętrzne udziały sieciowe są odrzucane z podaniem odpowiednich instrukcji.

Topologia kontenerów w projekcie

Każdy projekt działa w ramach własnej izolowanej sieci mostkowej (speedwave_<project>_network), która wyklucza widoczność kontenerów innych projektów. Standardowa topologia obejmuje:

• speedwave_<project>_claude: Wykonuje proces Claude Code bez dostępu do gniazda silnika kontenerów i bez zewnętrznych tokenów.
• speedwave_<project>_proxy: Pośredniczy w ruchu do dostawców LLM na porcie 4000.
• speedwave_<project>_mcp_hub: Centralny gateway MCP udostępniany dla Claude na porcie 4000.
• speedwave_<project>_mcp_<service>: Odrębne kontenery workerów uruchamiane dla każdej aktywnej integracji.

flowchart TB
  subgraph VM["Maszyna wirtualna Linux (Lima na macOS / WSL2 na Windows)"]
    subgraph NET["speedwave_<project>_network"]
      Claude["claude<br/>zero tokenów, brak socketu"]
      Proxy["proxy<br/>port 4000"]
      Hub["mcp_hub<br/>port 4000, zero tokenów"]
      W1["worker mcp_&lt;service&gt;<br/>/tokens:ro"]
      W2["worker mcp_&lt;service&gt;<br/>/tokens:ro"]
      Claude -->|"ruch LLM"| Proxy
      Claude -->|"narzędzia"| Hub
      Hub --> W1
      Hub --> W2
    end
  end

Kontener Claude łączy się wyłącznie z lokalnym proxy (w celu komunikacji z modelem) oraz z Hubem MCP (w celu wyszukiwania i wykonywania narzędzi). Nigdy nie łączy się z usługami zewnętrznymi bezpośrednio. Poszczególne workery montują poświadczenia w trybie tylko do odczytu, a sam hub nie przechowuje żadnych sekretów. Szczegółowe zasady opisano w sekcjach Model izolacji oraz Workery.

Zgodność międzyplatformowa

Obrazy kontenerów oraz profile zabezpieczeń są identyczne w systemach macOS i Windows. Warstwa abstrakcji środowiska zapewnia jednolite zachowanie modeli niezależnie od bazowego systemu operacyjnego.