Multi-project workflows

Speedwave supports running and managing multiple workspaces on a single host machine. Each registered workspace executes within an isolated container environment while maintaining strict separation of network namespaces, credentials, and session state. See Projects and sessions for registration procedures.

Strict isolation boundaries across workspaces

Resource boundaries are strictly enforced across project environments:

• Isolated container networks: Each project executes within a dedicated bridge network (speedwave_<project>_network), preventing cross-project traffic between containers.
• Dedicated token storage: Service tokens reside under per-project paths (~/.speedwave/tokens/<project>/<service>/), where workers mount only their designated service credentials in read-only mode.
• Per-project session states: Claude Code configurations and session transcripts reside under <data_dir>/claude-home/<project>/, ensuring that authentication and workspace history remain separated.

For full architectural details, see the Isolation model.

Virtual machine sharing

All registered projects within a Speedwave instance run inside a shared Linux virtual machine (Lima on macOS, WSL2 on Windows). Network namespaces and filesystem permissions maintain strict logical isolation inside the virtual machine. Independent virtual machine instances can be established by configuring distinct SPEEDWAVE_DATA_DIR paths.

Concurrency control and serialized lifecycle operations

Speedwave serializes lifecycle operations modifying container topologies (such as starting, updating, or rebuilding services). Serialization locks are scoped strictly per project: an ongoing container update on one project never blocks another project from starting or handling queries, and status inspection remains non-blocking.

Transactional project switching

In the Desktop application, the project switcher in the header controls active workspace selection:

1. The target project’s container topology is initialized and validated.
2. Once the destination environment is verified healthy, the active project key is committed to config.json.
3. The previous project’s container topology is passed to a background process for graceful teardown.

This operation functions as an atomic transaction. If the target workspace fails to initialize, Speedwave terminates only the partially initialized containers and maintains the previous project intact. Pending background teardowns are recorded in persistent storage, ensuring that interrupted shutdowns are cleaned up automatically upon subsequent launches.

When working in the CLI, commands default to the globally active project or target a specific workspace using the --project <name> parameter across speedwave, login, logout, and update commands.