How to Raise Supabase Locally – The Complete Guide to Vibcoders

It is convenient to work with cloud Supabase while the project is small and the Internet is stable. But as soon as real iterations begin – frequent schema edits, authorization test, Storage debugging – the cloud turns into a brake: long requests, a random limit on a free plan, the inability to work offline.

Local Supabase solves this completely. You get an exact copy of the entire stack – PostgreSQL, Auth, Storage, Realtime, Studio – right on your machine. This is the standard way to develop in 2026, and in this article I’ll show you how to do it right, from scratch to the first working query.

## 1. What exactly is running locally

Supabase is not a single program, but a set of services tied together by Docker Compose. When you pick it up locally, you start:

• PostgreSQL 15 is the primary database.
• *PostgREST automatically generates the REST API from your database scheme.
• GoTrue is an authorization service (email, OAuth, magic link).
• Realtime - WebSocket server for subscriptions to changes in tables.
• Storage API - S3-compatible file storage.
• Kong is the API gateway through which all requests pass.
• Supabase Studio is a web interface for managing the entire stack (at port 54323).
• Inbucket is a local email server for email testing (on port 54324).

All this is lifted by one team and works identically to the cloud. The migrations you write locally are applied in the cloud unchanged.

## 2. Pre-commencement requirements

Make sure that:

• Docker Desktop (or Docker Engine + Docker Compose on Linux) Version 20.10+.
• Node.js 18+ is required to install Supabase CLI via npm.
• Free ~4 GB of RAM (all containers together consume 2-3 GB).
• ~3 GB on the image drive.

You can check this:

docker-version
Docker version 26.1.0 or higher

node --version
# v20.x.x or higher

## ##3. Installation of Supabase CLI

Supabase CLI is the only utility you need. It manages the local stack, migrations and communication with the cloud.

macOS/Linux (via npm)

npm install -g supabase

macOS (via Homebrew)

brew install supabase/tap/supabase

Windows

# Через Scoop
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Checking the installation:

supabase --version
#1.200.x or higher

## 4. Project initialization

Go to the folder of your project and initialize Supabase:

cd my-project
supabase init

The team creates a supabase/ folder with the following structure:

supabase
Config.toml # Local Stack Configuration
ации ─ Migrations/ #SQL migration
ые ─ seed.sql # Initial data (optional)

The config.toml file is the main config. By default, it is already operational, but you can change ports if something conflicts:

[api]
port = 54321 # PostgREST + Kong

[db]
port = 54322 # PostgreSQL

[studio]
port = 54323 #Supabase Studio

[inbucket]
port = 54324 # Test mail

[storage]
file size limit = "50MiB"

## 5. Running a local stack

supabase start

The first run will take 3-7 minutes - Docker downloads all images (~2 GB). Subsequent launches - 15-30 seconds.

After a successful start in the terminal will be output with keys:

Started supabase local development setup.

         API URL: http://127.0.0.1:54321
     GraphQL URL: http://127.0.0.1:54321/graphql/v1
  S3 Storage URL: http://127.0.0.1:54321/storage/v1/s3
          DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
      Studio URL: http://127.0.0.1:54323
    Inbucket URL: http://127.0.0.1:54324
        anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Save these values – you’ll need them to connect from your app.

If you forget, you can get it again:

supabase status

## 6. Supabase Studio – Local Dashboard

Open in the browser http://127.0.0.1:54323.

You will see a full-fledged Supabase Studio, the same interface as in the cloud. Here you can:

• View and edit tables through Table Editor.
• Write SQL queries using SQL Editor.
• Manage users through Authentication.
• Upload files through Storage.
• View logs of all services.

Inbucket is available on http://127.0.0.1:54324. All emails from Auth (email confirmation, magic link, password reset) come here - no need to configure SMTP for development.

## 7. Connecting to a project from code

Environment variables (.env)

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Customer Initialization (JS/TS)

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

If you use Next.js with server components, add SUPABASE_SERVICE_ROLE_KEY for server operations:

Only on the server - never transfer to the browser
const supabaseAdmin = createClient
process.env.NEXT PUBLIC SUPABASE URL!
process.env.SUPABASE SERVICE ROLE KEY!
)

## 8. Migration is the right way to change the scheme

Never change the base schema directly through Studio on long-term projects – changes will be lost when reset or will not make it to the cloud. Use migration.

Create a new migration

supabase migration new create_posts_table

The supabase/migrations/20260527120000_create_posts_table.sql file is created. Write SQL in it:

create table posts
id uuid default gen random uuid() primary key,
title text not null,
content text,
user id uuid references auth.users(id) on delete cascade,
created at timestamptz default now()
);

Enable Row Level Security
alter posts enable row level security;

Policy: Users only see their posts
create a policy "Users can view own posts"
on posts for select
using (auth.uid() = user id);

Policy: Users can create posts
create a policy "Users can insert own posts"
on posts for insert
with check (auth.uid() = user id);

Apply migration

supabase db reset

This command resets the local database and applies all migrations again + seed.sql. Use it when you need to get a clean state.

Apply only new migrations without dumping:

supabase migration up

Generate TypeScript Types from the Scheme

supabase gen types typescript --local > src/types/database.types.ts

After that, you’ll have full types for all tables – the AI assistant will work with them much more accurately.

## 9. Seed-data - test filling of the database

The supabase/seed.sql file is executed at each supabase db reset. Add the test data:

-- Создаём тестового пользователя (только для локальной разработки)
insert into auth.users (id, email, encrypted_password, email_confirmed_at)
values (
  '00000000-0000-0000-0000-000000000001',
  'test@example.com',
  crypt('password123', gen_salt('bf')),
  now()
);

-- Тестовые посты
insert into posts (title, content, user_id) values
  ('Первый пост', 'Привет, мир!', '00000000-0000-0000-0000-000000000001'),
  ('Второй пост', 'Supabase локально — это просто.', '00000000-0000-0000-0000-000000000001');

## 10. Stack stop and control

# Stop (data retained)
supabase stop

# Stop and delete all data (full reset)
supabase stop --no-backup

# View the status of all services
supabase status

# Logs of a particular service
supabase logs db # PostgreSQL
supabase logs auth #GoTrue
supabase logs realtime #realtime
supabase log storage # Storage

## 11. Synchronization with the cloud project

When local development is ready, you can link the local project to the cloud

# Log in to Supabase
supabase login

# Link to the cloud project
supabase link --project-ref your-project-ref

# Apply all local migrations in the cloud
supabase db push

project-ref can be found in your project URL at supabase.com: https://app.supabase.com/project/ваш-project-ref.

**Important: supabase db push applies only new migrations. It does not affect migration already used in the cloud.

## 12. Typical problems and solutions

Docker doesn't start

# Make sure that Docker Desktop is running
docker info

# If the “port already in use” error is found and stopped
lsof -i:54321
kill -9 <PID >>

Studio won't open

Wait 30 to 60 seconds after supabase start – Studio starts last. If it didn't help:

supabase stop && supabase start

Mistake in migration

If the migration broke the scheme, reset the base:

supabase db reset

Auth doesn't send letters

Emails in the local environment are not sent to real email. Open Inbucket: http://127.0.0.1:54324 - all letters there.

Port Conflict on Windows/Mac

Change ports to supabase/config.toml and restart the stack.

## 13. Tips for working with an AI assistant

If you are using Cursor, Claude Code or a similar tool, add to AGENTS.md or system prompt:

#Supabase

Local stack launched via `supabase start`
- URL: http://127.0.0.1:54321
All schema changes only through migration to `supabase/migrations/`
Types generated in `src/types/database.types.ts`
RLS is enabled on all tables – always add policies when creating a table
- For base drop: `supabase db reset`

The AI will understand the structure of the project and will not offer to change the scheme directly through Studio.

## Conclusion

Local Supabase is not a “complex setup”, but a standard workflow that takes 10 minutes at first launch and speeds up development at times. You get full control of the stack, work offline, test migrations without fear of breaking the cloud base and apply everything to the product with one team.

Short route:

1. npm install -g supabase - install CLI.
2. supabase init - initialize the project.
3. supabase start - run the stack.
4. Studio on http://127.0.0.1:54323 - manage data.
5. Migration through supabase migration new - change the scheme.
6. supabase db push – roll out to the cloud.

If you already have a cloud project and you want to tighten its scheme locally, write in the comments, we will analyze this scenario separately.