Memory and CPU caps

Speedwave runs Claude and its tools in separate containers, each capped on memory and CPU. Use this guide to check whether your machine meets the RAM requirement and to understand what each container’s cap is.

Check your machine

1. Confirm your machine has at least 16 GiB of RAM. Speedwave warns you at startup if the host has less; it may still start, but performance can suffer.
2. Look up the container you care about in the memory caps or CPU caps table below.

Memory and CPU caps are fixed by Speedwave, not user-configurable: they are not settings in ~/.speedwave/config.json, and the config keys reference lists no cap-related key. If you do change a cap yourself (for example by editing the compose file directly), the new value only takes effect the next time the project’s containers start. Nothing applies while they keep running.

Note

On Windows, Speedwave cannot detect the host’s real RAM at all, so it always reports 16 GiB and the low-memory warning never appears, even on a machine with far less than 16 GiB. The requirement still applies: check your RAM yourself before relying on Speedwave’s startup check.

Memory caps per container

A memory cap is a ceiling, not a reservation: an idle container uses little regardless of cap.

Container	Memory cap
Claude	6 GiB
Tool gateway (MCP hub)	512 MiB
LLM proxy	128 MiB
Most tool workers (Slack, GitLab, SharePoint, and similar)	128 MiB
GitHub worker	256 MiB
Office worker	1 GiB
Playwright (browser) worker	2 GiB

Claude’s 6 GiB cap is fixed everywhere. Three workers get more than the 128 MiB default:

• GitHub worker, 256 MiB: loads full result pages on a busy repository.
• Office worker, 1 GiB: runs LibreOffice in the background.
• Playwright worker, 2 GiB plus 2 GiB shared memory: drives a real Chromium browser.

A worker’s cap only matters once you enable its integration. These caps can add up to more than the VM’s total memory: that is expected, since most containers sit well under their cap, and Speedwave only checks that Claude and the tool gateway together fit.

CPU caps

The same containers carry CPU ceilings, shared from one pool rather than dedicated cores. A cap limits how much one container can take from the others; it is a resource limit, not a security boundary.

Container	CPU cap
Claude	up to 2 CPUs
Playwright (browser) worker	up to 2 CPUs
Tool gateway (MCP hub)	up to 1 CPU
Office worker	up to 1 CPU
LLM proxy	up to 0.5 CPU
Standard tool workers	up to 0.5 CPU

How the virtual machine is sized

macOS

Speedwave sizes a Linux VM from your hardware: half your RAM (8 to 32 GiB) and half your cores (4 to 8).

Host RAM and cores	VM memory	VM CPUs
16 GiB / 8 cores	8 GiB	4
32 GiB / 16 cores	16 GiB	8
64 GiB / 24 cores	32 GiB	8

The VM grows, but Claude’s 6 GiB cap stays the same no matter how large the VM is.

The VM’s RAM ceiling is deliberately conservative because of how Lima behaves: once the VM has claimed memory from macOS, it holds on to it for as long as it runs and does not give it back, even after the containers inside go idle. This is also why Activity Monitor can show the VM sitting at a few GiB even when Speedwave isn’t doing anything. The memory only returns to macOS when the VM restarts.

Windows

Speedwave runs inside WSL2 and leaves its sizing alone: WSL2 picks its own memory, by default half your RAM. Container caps still apply.

Container time zone

Speedwave detects your host’s time zone and passes it into every container, so timestamps you see from Claude, such as when a usage limit resets, read in your local time instead of UTC. If detection fails, containers fall back to UTC. If you change your system time zone, containers pick up the new one the next time they start, not immediately.

If none of this is set up yet, start with Install Speedwave, which runs the RAM check and VM sizing automatically.