For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/web/local-setup.md (or send Accept: text/markdown).
Local setup
Run the Web demonstration on your computer with exact Windows and macOS commands, no paid provider credentials, and a clear path to real database-backed accounts.
1. Prepare your computer and open the project
First complete Before you start: accept the GitHub invitation, install Node.js 22 or newer, Git, an editor and Corepack, then clone your Web repository or the All Platforms monorepo. Open the supastack folder in the editor and select Terminal → New Terminal. You should see package.json in the editor's top-level file list. All commands below run from this repository root.
This starts the local demonstration without accounts at AI, billing or email providers and without Docker. Allow extra time for first-time dependency downloads. Follow only the Windows block or only the macOS/Linux block in the next steps; do not run both.
2. Create configuration files — macOS / Linux
In your terminal, run each line below. The first copy creates .env for later migration commands. The second creates apps/web/.env.local, which the Web server actually reads. Both contain the example's local settings. If either destination file already exists, keep it and skip that copy command; do not overwrite saved settings. Windows users use the next section instead.
corepack pnpm install downloads the libraries the app needs. If Corepack asks to download pnpm, answer y. Wait until it finishes and the terminal prompt returns. A final Done message without an error means you can continue.
cp .env.example .env
cp .env.example apps/web/.env.local
corepack pnpm install2. Create configuration files — Windows PowerShell
Use these commands in PowerShell from the folder containing package.json. If .env or apps/web/.env.local already exists, skip its copy line and keep your settings. Wait for installation to finish before starting the server. If script execution is blocked, use corepack.cmd instead of corepack as explained in Before you start.
Copy-Item .env.example .env
Copy-Item .env.example apps/web/.env.local
corepack pnpm install3. Start the Web server — leave this terminal open
Run the command below from the repository root. It starts only the Web app, so it works in both the Web-only repository and the All Platforms monorepo. Wait for the terminal to show Local: http://localhost:3000 and Ready. The first page may take a little longer to compile. The terminal should keep running; that is expected.
In the All Platforms monorepo, corepack pnpm dev starts the available development workspaces together. If apps/docs is present, that separate docs app uses http://localhost:3001. The public guides you are reading are part of the Web app at http://localhost:3000/docs. You do not need port 3001 to follow this tutorial.
corepack pnpm --filter @supastack/web dev4. Open the app and complete one local task
In your browser's address bar, open http://localhost:3000 to see the homepage. Then open http://localhost:3000/dashboard. Keep the prefilled name and email, or enter your own test values, and click Start local reference flow. This creates an in-memory demonstration workspace; it does not create a persistent account or send a real email.
In the demonstration, open AI task from the sidebar, enter a short request such as Summarize the local acceptance criteria, and click Queue local task. When its status is queued, click Run local task, then View result. You should see completed output and an Email queued state. The AI response is deliberately fake and repeatable; the queued email is local. Restarting the server clears this demonstration data.
To use /auth for real sign-up, first start Postgres and apply migrations using the Database and migrations guide. After that, sign-up or OTP messages from EMAIL_PROVIDER=local can be inspected at http://localhost:3000/mail-preview; they do not reach an external inbox. Mobile sign-in also uses this database-backed authentication, rather than the demonstration session.
5. Stop, restart and fix common first-run problems
Success means the homepage loads, the local workspace opens and a queued task reaches completed. When you finish, click the server terminal and press Ctrl + C. To resume later, reopen a terminal in the repository root and repeat the server command from step 3; you do not reinstall dependencies every time.
If localhost:3000 does not open, check that the server terminal is still running and shows Ready. If port 3000 is in use, stop the other development server with Ctrl + C and retry. If you see a database error after opening /auth, return to /dashboard for the demonstration or complete the database guide. If the local demonstration is missing, check APP_ENV=local, AI_PROVIDER=fake, BILLING_PROVIDER=local, EMAIL_PROVIDER=local and JOB_PROVIDER=local in apps/web/.env.local, then restart.
To customize the name and marketing text, open apps/web/src/marketing/site-config.ts in the editor. Follow Branding for the exact fields and verification steps. For the real account's appearance settings, complete database setup first, then open /settings/appearance. Automated acceptance commands take longer than this first-run walkthrough; find them under Workspace commands.
If you want to continue setup, read Set up database.