Parallel local projects

The Supabase CLI can run more than one local Supabase project on the same machine. Each local project belongs to its project directory and git branch. Every app or git worktree gets its own Postgres database, Auth, Storage, and other services, with separate ports and data.

With the default ports, a second supabase start on the same machine fails with a port conflict. The experimental supabase stack commands assign ports automatically and keep them stable across restarts. One app can also run several named local projects, such as dev and test, so a destructive test run never touches your development data.

Key benefits

1. One local project per worktree: Run coding agents in separate git worktrees, each against its own database.
2. Automatic ports: The CLI assigns ports from a shared range and keeps them across restarts. Remove the fixed ports from config.toml once, or create the project with the stack commands turned on.
3. Named environments: Start --stack dev and --stack test side by side in one app.
4. Docker or native runtime: Run in containers, or as processes on your machine without Docker on Linux and on macOS on Apple silicon. Use Docker when you run several local projects on one machine.
5. Services start on demand: Postgres starts right away. Other services start on their first request and stop when idle, which keeps idle local projects light.

Parallel local projects are valuable for:

• Developers running coding agents in git worktrees
• Teams that keep separate development and test databases on one machine
• Freelancers and consultants switching between several client apps
• CI jobs and agent sandboxes that run without a Docker daemon

The supabase stack commands are experimental. Their interface can change between releases. See the documentation for the full workflow and limitations.