Working across projects
Speedwave runs several projects side by side, and more than one can be running at once. Each project is a separate world: its own container network, tokens directory, and Claude home directory. See projects and sessions for what a project is and how it’s registered.
What never crosses a project boundary
Section titled “What never crosses a project boundary”A worker in one project cannot reach another project’s network or credentials. Each project gets a network named speedwave_<project>_network by default, and containers on one project’s network cannot talk to containers on another. Service credentials live under a per-project tokens directory, ~/.speedwave/tokens/<project>/<service>/, and a worker only mounts its own service’s subdirectory there. Each project also has its own Claude home directory, so logging in to Claude for one project doesn’t log you in for another. Full detail on these boundaries lives at isolation.
What is shared
Section titled “What is shared”Projects share one virtual machine per Speedwave instance: Lima on macOS, WSL2 on Windows. All your projects run inside that VM even though they stay isolated at the network and tokens-directory level. A separate instance, with its own VM, is created only if you point SPEEDWAVE_DATA_DIR somewhere else.
Operations on the same project don’t overlap
Section titled “Operations on the same project don’t overlap”Speedwave serializes operations that change a project’s containers, such as starting, updating, or recreating it, so two of them on the same project never interleave, whether that’s a Desktop action or a speedwave update CLI run. The lock is per project, so one project’s update never blocks another project’s containers from starting, and reading a project’s containers or logs stays responsive during an update.
Switching the active project
Section titled “Switching the active project”In the Desktop app, a project switcher chooses which project is active. Switching commits the new active project to your config, starts the destination’s containers, and only then tears down the previous project’s containers in the background. One switch runs at a time.
The switch is a transaction: it reports success only once the destination is fully up, and only then hands the previous project to a background thread for teardown. If the destination fails to start, Speedwave tears down just the partially started destination and leaves the previous project untouched, so a failed switch never costs you your working project. Because that teardown happens after the switch already succeeded, Speedwave first records it as a pending teardown on disk. If the app is killed before teardown finishes, the next launch reads the record and finishes stopping the leftover project.
From the CLI, the working directory does not select the project. Plain speedwave uses the active project from your config. To target a specific project from any directory, pass --project <name>, which applies to speedwave, login, logout, and update.