How do I run several local Supabase projects at once, one per coding agent or git worktree, with or without Docker?

By Ohad Krispin, founder of VibeRaven · LinkedIn

Since Supabase CLI v2.119.0, announced on October 14, 2026, you turn on the experimental stack setting (stack = true under [experimental] in supabase/config.toml, or SUPABASE_EXPERIMENTAL_STACK=1), remove the fixed ports from config.toml, and run supabase start in each git worktree: each gets its own Postgres, Storage, Edge Functions and MCP server on ports from 20000 to 32767 that stay the same across restarts, so one agent's supabase db reset never touches another's database. Where there is no Docker, supabase start --runtime native runs the services as plain processes on Linux amd64 or arm64 with glibc 2.35 or later and on macOS 14 or later on Apple silicon, not on Windows or Intel Macs; the stack commands are experimental and keep their data separate from the project the default supabase start created. Checked against Supabase's announcement and CLI guides on 2026-10-28.

Turn on the stack commands

Add stack = true to the [experimental] table that config.toml already has, or add the table if there is none. Without the setting, supabase stack fails with Unknown subcommand "stack". A second [experimental] table makes config.toml invalid, and commands then fail with failed to load config. The environment variable wins over the file, and SUPABASE_EXPERIMENTAL_STACK=0 turns it off for one session. Commit the file so every worktree gets it.

# supabase/config.toml
[experimental]
stack = true

# check: the help starts with "Manage an experimental, unstable local Supabase stack"
supabase stack --help

# a new app
SUPABASE_EXPERIMENTAL_STACK=1 supabase init

Remove the fixed ports, or two projects collide

The config.toml that supabase init creates has fixed ports, and the CLI treats a port in the file as an exact request, so two local projects that both ask for 54321 cannot run at once. Delete the port keys below. On a project you already started, stop it first; CLI v2.121.0 or later moves the ports and keeps the data, while earlier versions fail with The saved stack cannot adopt these changes, and you need a new --stack name or supabase stack destroy, which deletes the data.

port          under [api], [db], [db.pooler], [studio], [local_smtp], [analytics]
shadow_port   under [db]
inspector_port under [edge_runtime]
smtp_port, pop3_port (under [local_smtp]) and vector_port (under [analytics]), if you set them

Give each agent its own URLs and keys

Ports differ between local projects, so an agent should read them instead of assuming the defaults. supabase start --output-format json returns the project id, runtime and an env map; supabase status --env writes the same values to a dotenv file, and --override-name renames them for your framework.

git worktree add ../app-billing -b billing
cd ../app-billing && supabase start

supabase start --output-format json
supabase status --env --override-name API_URL=NEXT_PUBLIC_SUPABASE_URL,ANON_KEY=NEXT_PUBLIC_SUPABASE_ANON_KEY
supabase stack list

Without Docker: the native runtime

When no container engine answers, the CLI picks the native runtime on a supported platform, or you can ask for it. It runs all 13 services as processes at the same pinned versions, with the full Postgres extension set including pgvector. It does not run as root, because Postgres initdb cannot; in a root CI container, set SUPABASE_NATIVE_POSTGRES_USER to a non-root account. On first start it downloads archives from the supabase/slim-services GitHub releases, with an S3 fallback, and extracts them with tar, so a sandbox allowlist needs supabase-cli-artifacts.s3.us-east-1.amazonaws.com, or both github.com and release-assets.githubusercontent.com. Supabase calls native one project per sandbox; for several projects on one laptop, Docker isolates them better.

supabase start --runtime native

# download the archives ahead of time, for a sandbox image
supabase stack prepare --runtime native

# which runtime a local project uses
supabase stack status --output-format json

What still shares one local project

Identity is the project root, the git branch and an optional --stack name. Two agents in the same checkout on the same branch share one local project; give them separate worktrees or --stack names. The db, migration and other database commands do not accept --stack and use the default local project for the current branch, while supabase db push, db pull and db dump target the linked project unless you pass --local. Switching branches in one directory starts a different local project with its own data, and moving the directory creates a new one.

How much faster

Supabase's measurements: starting a project with artifacts cached went from 37 s to 5.2 s on Docker and 3.9 s native, idle memory from 2.6 GiB to 290 MiB, and the download from 1.9 GB to 550 MB (Docker) or 360 MB (native). Services other than Postgres sleep until their first request; pass --eager to start them all. Remote branches on a pull request, which need no setting, became ready in a median of 21 s instead of 102 s after the September rollout.

Checklist

One local Supabase project per agent

01
Update the CLI to v2.119.0 or later (v2.121.0 to move ports on an existing local project):
```
supabase --version
```
02Add stack = true under the existing [experimental] table in supabase/config.toml and commit it.
03Delete the fixed port keys from config.toml, then stop and start any local project that used them.
04Give each agent its own git worktree, run supabase start in each, and have it read its URLs from supabase start --output-format json.
05In a sandbox or CI runner with no Docker, run supabase start --runtime native as a non-root user and allow the archive download hosts.
06Remember that the new local projects start empty: run your migrations and seed in each.

Sources

Official docs behind this checklist

Browse all launch guides · Read resources · How to make and check your next change

FAQ

FAQ for builders before launch

Does supabase db reset in one worktree affect another?

No. Each worktree is a different directory, so it gets its own local project with its own database, Storage data and ports.

Does my existing local data carry over?

No. Turning on the stack setting does not copy the database from the project you started with the default supabase start, and does not stop it either.

Can I run Supabase locally on Windows without Docker?

Not with the native runtime. The runtimes guide lists Windows as not supported and says to use Docker.