# 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.

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.

<DesktopFrame screen="switcher" />

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

```bash
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](/docs/security/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](/docs/get-started/first-session/) for those steps.

## Where files live

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

- ~/.speedwave/
  - config.json
  - tokens/
    - my-project/
      - slack/
      - gitlab/
      - llm/
  - claude-home/
    - my-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](/docs/understand/projects-and-sessions/).

[CLI reference](/docs/reference/cli-commands/)