Run Locally

Use this after the first install whenever you start local development. The normal path uses app port 3000 and the checked-in Supabase ports. For a separate concurrent checkout, use Run another project as your complete setup path in place of the Daily workflow below.

Start Supabase, sync local env, and run the Next.js dev server.

Daily workflow

Start local Supabase

bunx supabase start

Supabase owns the local database and auth services. Keep Docker running while you use the app. Do not run supabase init; the repository already includes Supabase config, migrations and local auth settings.

Refresh local env

./coremvp env sync

Run this from the repository root after Supabase is running. It writes local Supabase values into so the app, webhook route, and local tests use the same local services.

Start the app

bun run dev

Open http://localhost:3000. Leave this terminal running while you test the app.

Check env without printing secrets

./coremvp env list

The env command reports set or missing; it does not print secret values. Read Configure Environment when you need to understand which values are generated locally and which values are production/provider configuration.

Stop services

bunx supabase stop

Stop the bun run dev terminal with Ctrl+C. Stop Supabase when you are done with local database services or before retrying a clean Supabase startup.

Reset local data

bunx supabase db reset

This deletes local application data and reapplies the checked-in migrations. Use it only when you want a clean database for this checkout. The current Supabase configuration disables automatic SQL seeds.

If local Supabase fails with a collation mismatch, recreate local Supabase data:

bunx supabase stop --no-backup
bunx supabase start

That recovery deletes local Supabase data for this checkout.

Run another project

Give a fresh checkout its own Supabase project and unused ports before its first start. Keep the existing project's services and database intact. Supabase owns these settings in ; see its configuration reference.

Choose a project and ports

Set a unique project_id, such as my-saas-dev, in . Change every enabled host listener in that file. These are the current defaults and an example alternate set; confirm your chosen ports are unused.

Setting	Default	Example alternate
`[api].port`	`54321`	`55321`
`[db].port`	`54322`	`55322`
`[db].shadow_port`	`54320`	`55320`
`[studio].port`	`54323`	`55323`
`[inbucket].port`	`54324`	`55324`
`[edge_runtime].inspector_port`	`8083`	`8183`
`[analytics].port`	`54327`	`55327`

The pooler and extra SMTP/POP listeners are disabled by default. Assign them unused ports too if you enable them.

Align the app and Auth origins

Choose an unused app port, such as 3300. Update these existing Auth settings in the same Supabase config:

supabase/config.toml (Auth settings)

[auth]
site_url = "http://localhost:3300"
additional_redirect_urls = ["http://localhost:3300/**", "http://127.0.0.1:3300/**"]

Keep the other [auth] settings. These URLs let account emails and Auth callbacks return to this app.

Start and verify the new database

In this checkout's terminal:

export COREMVP_WEB_PORT=3300
bunx supabase start
bunx supabase migration list --local

Follow Verify the local schema if an applied version is missing. Continue only when every checked-in migration has a matching applied version.

Sync and run this app

In that same terminal:

./coremvp env sync
bun run dev --port "$COREMVP_WEB_PORT"

Open http://localhost:3300. Env sync derives this checkout's actual Supabase API and database values rather than copying another project's environment. Check redacted key presence with ./coremvp env list, then run the Auth check below to verify the app is using its own services.

For later env sync and test commands, export COREMVP_WEB_PORT=3300 in that terminal too. TEST_BASE_URL alone changes a test target without changing the origin written by env sync. Forward your chosen provider's webhook listener to the same app port through the Stripe or Polar guide.

Continue with Test your application below. Keep this checkout on the chosen port for future sessions; use the exported variable and matching dev command above instead of returning to the default-port Daily workflow.

Test your application

Test auth

./coremvp e2e auth

This checks signup, signin, protected-route behavior, and signout against the local app. Read Auth for the Supabase Auth architecture, production auth checks, and auth-specific setup pages.

Test Projects

./coremvp e2e projects

This checks the included Project lifecycle, Organization authority, and local persistence. Read Projects for the dashboard path, extension points, and proof limits.

Test private files

bun test src/tests/storage.test.ts

This checks file validation and authenticated API behavior with controlled Storage responses. Follow Storage for Account controls and the two-account checks that prove real Storage policies.

Test billing

Choose Stripe or Polar, then follow that provider's lifetime or subscription setup. Each path keeps its account, offers, webhook listener and buyer checks together.

Common local fixes

Symptom	Command or next step
Supabase is down	`bunx supabase start`
Another app or Supabase project uses the default ports	Follow Run another project before starting this checkout
You need redacted env key presence	`./coremvp env list`
You need web logs	Read the terminal running `bun run dev`
You need clean local data	`bunx supabase db reset`
You are ready to test checkout	Follow the Billing setup and local test path

What's next

Was this page helpful?

Configure Environment

Use CoreMVP CLI

Deployment

On this page