Skip to content
Speedwave

Projects and sessions

A project in Speedwave represents a registered workspace: a descriptive identifier paired with a specific directory path on your host system. Project definitions are stored in your user configuration file at ~/.speedwave/config.json within the projects array. You can initialize a new workspace by running speedwave init inside your target project directory. See Creating your first project for a step-by-step walkthrough.

Workspace isolation architecture

Section titled “Workspace isolation architecture”

Every project is provisioned with an isolated container network, dedicated token storage, and an independent Claude home directory. Activities within one workspace remain segregated from other projects, ensuring that container operations remain confined to their intended scope.

Isolation is enforced through two primary mechanisms:

  • Network segregation: Each project operates on a dedicated bridge network (speedwave_<project>_network). Containers belonging to one project network cannot communicate directly with containers assigned to another project.
  • Credential scoping: Service credentials are stored within per-project token directories under ~/.speedwave/tokens/<project>/<service>/. An individual worker container mounts only its own service directory in read-only mode. Further architectural details are covered in the Isolation model.

In addition, each project maintains an independent Claude home folder at <data_dir>/claude-home/<project>/, storing Claude Code session history, credentials, and onboarding state. Because this data is scoped to the project, authentication states remain distinct across different workspaces.

Managing multiple projects

Section titled “Managing multiple projects”

Speedwave supports running multiple projects on a single machine. Operations modifying container configurations (such as starting or rebuilding containers) are serialized per project, ensuring that tasks across different projects do not block one another.

In the Desktop application, the project switcher in the header selects the active workspace. Switching projects initializes the target container topology while gracefully terminating the previous project’s services in the background.

When using the CLI, commands target the active project defined in your global configuration, or a specific registered workspace using the --project <name> argument regardless of your current shell working directory.