Installation
Installing the Supabase CLI
Before doing anything else, you’ll want to install the Supabase CLI as it will – besides other great features – allow us to spin up a local Supabase instance with no effort.
In theory, you can install the Supabase CLI globally with package managers such as brew or scoop. However, from my experience, I advise against them as they usually confuse more than they help, particularly when you have multiple projects, as well as a different version of the Supabase CLI than other people in your team.
In short, install the Supabase CLI via npm install supabase --save-dev as a development dependency in every project where you want to use Supabase.
Afterward, you can test if the installation succeeded by running npx supabase --help. Running this command should not result in you being asked to install
the CLI –since you’ve done that already, it should quickly output helpful information about the CLI.
Running your first Supabase instance on your machine
When you go on supabase.com, sign in, and create a new project, that’s your Supabase instance. However, we want to run an instance locally on our computer. Let’s see how to do that.
⭐ Initializing a new local Supabase instance
Having a local installation is crucial in development as it allows us to test things before we deploy them. Hence, even if you plan to use the awesome supabase.com platform, you’ll be better off also having a local installation.
The command also creates a config.toml file in that new directory, which contains a complete, working configuration that the CLI uses to run your local setup. You can have a peek at it but don’t expect to understand it just yet.
⭐ Starting your first Supabase instance
Now that you’ve initialized the required files for a local instance, you’ll want to get it up and running so that you get the information from Supabase about the services it started, as well as the credentials it was deployed with.
This will contain everything we need to make a connection to Supabase.
So, inside your /your-path/my-project/supabase project folder, call npx supabase start. This will automatically trigger the underlying Docker setup, pull all the required Docker images, and spin them up – in other words, the command creates and starts a fully running Supabase instance without you having to configure it.
Digest: sha256:8ace6e32e26d30a352b55170ff9953b554baa831d7ab61cd0520316793cb3de1
Status: Downloaded newer image for public.ecr.aws/supabase/studio:2025.06.02-sha-8f2993d
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
JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU
S3 Access Key: 625729a08b95bf1b7ff351a663f3a23c
S3 Secret Key: 850181e4652dd023b7a98c58ae0d2d34bd487ee0cc3254aed6eda37307425907
S3 Region: local
This means your local instance is running. I recommend that you just copy all of the output you receive and save it somewhere for easy access later.
Tip
The Terminal output provides a summary of the things you’ll need to connect to Supabase (it is not a list of services started). Let’s go through them one by one:
-
API URL: The connection URL for our Supabase instance. It is the unified URL that takes all your API calls and, depending on the path, forwards them to the correct service to be processed.
-
GraphQL URL: When explaining the PostgREST service in Chapter 1, I mentioned that Supabase allows you to work with GraphQL if that is your preferred way of working. This is the URL you’ll need if you want to fetch data via GraphQL.
-
DB URL: This is the connection URL of the database itself, bypassing the other services. It is already in the form of a PostgreSQL connection string and includes the PostgreSQL protocol, username, and password. For most use cases, you won’t need this DB URL as you will be using the API URL – or more specifically, the Supabase client – for everything related to your project.
-
Studio URL: This is the dashboard where we will conveniently manage and structure data within Supabase.
-
Inbucket URL: This is a special service that’s deployed to simplify your local development process. Every application that interacts with users needs to send emails – for example, when logging in, when changing an email address, or when resetting a password. To send emails, you need an email server. In development mode, you usually don’t want to send out real emails to real people. Instead, you’ll want to check and verify that the content in those emails is correct and functional.
Inbucket is a dummy mail server.
-
JWT secret: JWT is the short form of JSON Web Token and is an encrypted JSON-formatted value that usually contains authentication data.
-
anon key: This is the anonymous key that, complementary to the API URL, allows us to connect to our instance with the Supabase library.
-
service_role key: The service role key sounds non-threatening but is the superadmin key and allows any kind of manipulation. You should never use it in the frontend as someone could steal it.
Managing multiple local Supabase instances
Developers often work on many different projects. Running multiple servers of any kind at the same time can be done by changing the port configuration (one on localhost:3000, the other on localhost:3001, and so on). But what if you have three projects, all using their own Supabase instances? Can we have three local Supabase instances run in parallel at the same time? Let’s have a look at the options for how to handle this.
❇️ Option 1 – the start-stop technique
This is the recommended option when the projects are separated and you can spare a minute to switch between instances.
Imagine that you have two projects. If you currently run the instance from project 1, then go to the project directory and run npx supabase stop, it will automatically back up your data locally.
Now, if you go to project 2 and run npx supabase start, the project 2 instance will be running and consider the project 1 instance to be in sleep mode.
❇️ Option 2 – change ports
Inside config.toml, you can change the ports that Supabase uses for its services. For example, for Studio, you’ll see something like this:
Change port to something unique, such as port=9100. Upon doing this, for this project, your Supabase Studio service will run on localhost:9100.
Change port to something unique, such as port=9100. Upon doing this, for this project, your Supabase Studio service will run on localhost:9100.