Quick start

This runbook gets your SaaS app running locally fast. If you ever get stuck, come back to this runbook.

0) Install Wasp

Pre-requisites

Node.js ≥ 22.12 (with npm) available in PATH
We recommend nvm to switch Node versions easily

Linux & macOS

Open terminal and run:

bash

curl -sSL https://get.wasp.sh/installer.sh | sh

Error: Bad CPU type in executable

Are you getting this error on a Mac (Apple Silicon)?

If you're on a Mac with Apple Silicon (M1, M2, ...), the Wasp binary is compiled for x86, not arm64, so you'll need install Rosetta on your Mac to run it. Rosetta translates Intel (x86) apps so they work on Apple Silicon. To install it, run:

    
    softwareupdate --install-rosetta
  

After installing Rosetta, Wasp should run normally.

Windows

Using Wasp on Windows requires WSL2 plus a Linux distribution (Ubuntu is our pick). Follow the linked guide for a full walkthrough, and reach out on Discord if you get stuck.

Be sure to complete the WSL2 Docker post installation steps so PostgreSQL and Docker work correctly with Wasp. See steps below:

It's best to run these post-install steps inside WSL, following Docker's official guidance. These work if you are experiencing an error similar to this one.

First, run command below to create the docker group in case it doesn't exist. If it exists, don't worry, just continue with next steps.

    
    sudo groupadd docker
  

After that, add your current user to docker group by running (where $USER is your username):

    
    sudo usermod -aG docker $USER
  

Then log out and log back in to apply the changes. Finally, run:

    
    su -s $USER
  

Once inside your WSL2 environment, run:

bash

curl -sSL https://get.wasp.sh/installer.sh | sh

Are you getting file system issues using WSL2?

If you are using WSL2, make sure that your Wasp project is not on the Windows file system, but instead on the Linux file system. Otherwise, Wasp won't be able to detect file changes, due to this issue in WSL2.

1) Finalize Installation

Verify Wasp is installed:

bash

wasp version

✍️

For best DX - syntax highlighting, scaffolding, autocomplete) - install the Wasp VSCode extension. Search "Wasp" in VS Code Extensions or visit the extension homepage.

2) Create Your App from the OpenSaaS Template

From the directory where you want your project:

bash

wasp new

Enter your project name, then choose [3] saas from the template list. This clones a clean copy of the Open SaaS template. 🎉

3) Start Your Database

You need a running Postgres instance.

Ensure Docker is installed and running
In a new terminal (inside your app directory):

bash

cd app

Start the database:

bash

wasp start db

Your app will spin up with a Postgres database already attached.

‼️

Keep this terminal window open while you work; closing it stops the process and your app will lose access to the DB.

Next, let’s create your first database migration to set the correct schema: open a new terminal tab/window and run the command below.

Create the first migration (installs deps on first run):

bash

wasp db migrate-dev

In the future, run wasp db migrate-dev whenever you change your Prisma schema.

Want a GUI to browse/edit your DB? Launch Prisma DB Studio with

Optional — Open Prisma Studio:

bash

wasp db studio

4) Start Your App

DB running? In app/? Perfect - go ahead and start the app.

Copy the .env.server.example file to .env.server.

Copy env template:

bash

cp .env.server.example .env.server

.env.server holds API keys for payments, email, etc. For now, the dummy keys are fine to boot the app.

Start the app:

bash

wasp start

If the browser doesn’t open automatically, visit http://localhost:3000.

At this point you should have:

DB running (likely on port 5432)
App running (client on 3000, server on 3001)

5) Run Docs & Blog (Optional)

This starter includes Astro (Starlight) docs/blog. Use it as a base or delete it if you don’t need it.

To run it:

bash

cd ../blog

Install dependencies:

bash

npm install

Start dev server:

bash

npm run dev

Check the terminal for the URL (typically https://localhost:4321/).

What’s Next?

You now have the app (and optional docs/blog) running locally. Next up: a quick guided tour of the app’s parts so you understand how everything fits together.

👾

If this template helps, consider ⭐ starring the GitHub repo — it keeps the project healthy and improving.
Need a hand or want to share ideas? Join our Discord or write is on X — we’re active and happy to help.