Local Supabase per agent

For the Next.js and TanStack Supabase kits, use one local Supabase project per git worktree. Each agent can develop and test its database changes independently. This follows Supabase's project-per-agent approach.

1. Enable the stack engine

The engine is experimental and requires CLI 2.119.0 or later. These instructions target 2.121.0. In apps/database/package.json, set the supabase development dependency to the exact version "2.121.0", then install from the repository root:

pnpm install
pnpm --filter database exec supabase --version

In apps/database/supabase/config.toml, add the following to the existing experimental table, or create that table if it is absent:

[experimental]
stack = true

Remove explicit service ports so the CLI can allocate them. This includes port in the API, database, pooler, Studio, mail and Analytics sections; database shadow_port; mail smtp_port and pop3_port; Analytics vector_port; and Edge Runtime inspector_port. Older kits call the mail section [inbucket]; rename it to [local_smtp] and remove its ports too. Remove any equivalent SUPABASE_*_PORT overrides from your shell.

Keep the schema, Auth settings and migrations. Commit the config, package manifest and lockfile so new worktrees inherit the setup. Check Supabase's port-removal checklist and limitations if you have customized the config.

2. Start a project in each worktree

Create a worktree for each agent. For example, from your kit's repository:

git worktree add ../app-billing -b feature/billing
cd ../app-billing
pnpm install
pnpm --filter database exec supabase start --runtime docker

Use Docker or Podman when several agents work on the same computer. Each worktree has its own apps/database/supabase/ directory, so it gets its own project and assigned ports. Two agents in the same directory on the same branch still share a database.

For one project in a sandbox without a container engine, replace the start command with:

pnpm --filter database exec supabase start --runtime native

Native mode supports macOS 14+ on Apple silicon and Linux amd64/arm64 with glibc 2.35+. See the runtime guide for download access and non-root Postgres requirements. A project keeps the runtime selected when it was created.

3. Connect the web app to its project

Create the kit's env file only if it is missing, using the command on its installation page (Next.js + Supabase or TanStack + Supabase). Then inspect this worktree's connection details:

pnpm --filter database exec supabase status --output-format json

Copy the values from the JSON env object into the matching file. Update only these entries, preserving your other integrations:

Keep secret and service-role keys server-only. The output contains credentials; don't commit it. Use the returned STUDIO_URL, MAILPIT_URL and MCP_URL for local tools instead of assuming their ports.

Older starter copies have a supabase:sync-env script that uses --output json and expects top-level keys. Before using it with this engine, update it to use --output-format json, read env, and sync the API URL as well as the keys. Until then, use the mapping above. The nextbase-website-new repository already includes the updated sync script.

In a Next.js kit, replace any image remotePatterns entry fixed to port 54321 with an entry derived from NEXT_PUBLIC_SUPABASE_URL for /storage/v1/**. Preserve query-string support for signed and transformed images. Otherwise Storage images from the assigned port will fail image optimization.

Start the web app with pnpm dev. When running multiple web servers, select a different web port in each worktree and match the app origin and Supabase Auth redirect settings to it. Supabase allocates its own service ports; your web server's port remains your responsibility.

4. Work on the local database

Run local database commands through the database package so the CLI finds the right config:

pnpm --filter database exec supabase migration list --local
pnpm --filter database exec supabase test db
pnpm --filter database exec supabase gen types typescript --local --schema public

The last command prints types; use your kit's generation script to write them to its expected file. Follow its migration workflow and access-control tests. Commands such as db pull, db push and db dump require --local for local work.

Use the default project in each worktree. Named --stack projects need extra routing because database commands don't accept that flag. The local Supabase MCP manages the development backend; Nextbase's User and Admin MCP connections operate through the application's permissions.

5. Stop or switch projects

pnpm --filter database exec supabase stop

Stopping preserves this project's data. Branch changes select a different local project: start it, refresh the env values and restart the web server. Stop the previous project before switching branches if you no longer need it.

Enabling the engine starts with a fresh local database built from migrations and seed data. It doesn't import or delete your previous local database. Keep that database until you have exported anything you need. Avoid global stop commands while other agents are working, and use supabase stack destroy only when you intend to permanently remove the selected project's database.