Your first project

You do your work inside a project. A project is a registered workspace with a name and a host directory, and everything in Speedwave, from container networks to credentials, is organized per project.

Create a project

Both front ends register a project the same way underneath. Use whichever you prefer.

Desktop

1. Click the project pill in the top right of the header bar to open the project switcher.
2. Click + add project… and pick the directory you want to work in.

If the directory you pick sits inside a OneDrive, Dropbox, or Google Drive sync folder, Speedwave warns you before adding it: macOS may block access to a cloud-synced folder until you grant permission. If that happens, a follow-up dialog walks you through opening the Files & Folders privacy pane and retrying.

Chat my my-project

my my-project i

pa payments-api i

+ add project...

CLI

Open a terminal in the directory you want to work in, then run:

speedwave init

This registers the current directory as a project and sets it active. If you omit a name, Speedwave uses the directory name. To choose a different name, run speedwave init my-project instead.

Project names must be lowercase, using the letters a to z, digits 0 to 9, and the characters _, ., and -. A name must start with a letter or digit and be at most 63 characters.

On Windows, Speedwave rejects a WSL distribution root as a project directory, since that’s the whole distro, not a project. Pick a subdirectory instead, such as \\wsl.localhost\<distro>\projects\<name>.

What Speedwave sets up around it

Registering a project adds an entry to the projects array in your user config at ~/.speedwave/config.json, with a name and a dir. From then on, the project gets its own:

• A container network, so its containers cannot talk to another project’s containers.
• A tokens directory, holding the credentials for each service the project connects to.
• A Claude home directory, holding your Claude Code credentials, sessions, and onboarding state for that project.

Running speedwave init also sets the new project as the active one. Plain speedwave, with no --project flag, always runs the active project, not whatever project matches your current directory. Once your project exists, log in to Claude for it: see your first session for those steps.

Where files live

Everything Speedwave keeps for a project sits under your data directory, ~/.speedwave/ by default:

• Directory~/.speedwave/

  • config.json
  • Directorytokens/

    • Directorymy-project/

      • Directoryslack/

        • …
      • Directorygitlab/

        • …
      • Directoryllm/

        • …
  • Directoryclaude-home/

    • Directorymy-project/

      • …

Your project’s own files stay where they already are, on the host directory you ran speedwave init in. Speedwave mounts that directory into the container as /workspace.

Removing a project

Removing a project deletes only the Speedwave-managed directories above (tokens, Claude home, and the rest). It never touches your source tree. You can’t remove the project you’re currently on. Switch to a different project first, or Speedwave refuses with an error telling you to do so.

For the full picture of how projects stay isolated from each other and how the active project is chosen, see projects and sessions.

CLI reference The --project flag, init, and project resolution in detail.