How to run Supabase Locally for your AI agents?

Running Supabase locally is a great way to set up a local development environment for your AI agents or applications that require a database. Supabase is an open-source alternative to Firebase, offering a suite of tools including a PostgreSQL database, authentication, real-time subscriptions, and more. Running it locally allows you to develop and test your AI agents without relying on a remote server, ensuring privacy and faster iteration.

Here’s a step-by-step guide on how to run Supabase locally for your AI agents:

1. Prerequisites

Before you begin, ensure that you have the following installed on your machine:

• Docker: Supabase runs locally using Docker containers.

  • Install Docker from Docker's official website.
  • For Windows: Use Docker Desktop.
  • For macOS: Use Docker Desktop.
  • For Linux: Follow the installation instructions for your distribution.

• Git: To clone the Supabase repository.

  • Install Git from Git's official website.

• Node.js (Optional): If you plan to interact with Supabase via JavaScript/TypeScript, you may need Node.js.

  • Install Node.js from Node.js official website.

2. Clone the Supabase Repository

Supabase provides a Docker Compose setup for running the platform locally. You can clone the official Supabase repository to get started.

Step 1: Clone the Repository

git clone https://github.com/supabase/supabase.git
cd supabase/docker

This will download the Supabase Docker configuration files.

3. Start Supabase Locally

Supabase uses Docker Compose to manage multiple services (e.g., PostgreSQL, authentication, storage). You can start all the services with a single command.

Step 1: Start Docker Containers

Run the following command to start Supabase locally:

docker compose up

• This command will start all the necessary services, including:
  • PostgreSQL: The main database.
  • Authentication: Handles user sign-ups, logins, etc.
  • Storage: For file uploads and storage.
  • Realtime: Enables real-time subscriptions (e.g., WebSocket updates).

Step 2: Wait for Initialization

The first time you run this command, Docker will pull the necessary images and initialize the services. This may take a few minutes.

Once everything is up and running, you should see logs indicating that the services are ready.

4. Access the Supabase Dashboard

Supabase provides a web-based dashboard for managing your database, authentication, and other services.

Step 1: Open the Dashboard

Navigate to the following URL in your browser:

http://localhost:3000

Step 2: Log In

Use the default credentials to log in:

• Email: [email protected]
• Password: password

You can change these credentials later if needed.

5. Interact with the Database

Supabase uses PostgreSQL as its database. You can interact with the database directly or through the Supabase client libraries.

Option 1: Using SQL

You can execute SQL queries directly in the Supabase dashboard:

1. Go to the SQL Editor tab in the dashboard.
2. Write and execute SQL queries to create tables, insert data, etc.

Option 2: Using the Supabase Client Library

If you're building an AI agent, you can use the Supabase client library to interact with the database programmatically.

Install the Supabase Client

For JavaScript/TypeScript projects:

npm install @supabase/supabase-js

Initialize the Supabase Client

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

const supabaseUrl = 'http://localhost:3000'
const supabaseKey = 'your-anon-key'  // Found in the Supabase dashboard under API settings

const supabase = createClient(supabaseUrl, supabaseKey)

Example: Querying Data

async function fetchData() {
  const { data, error } = await supabase
    .from('your_table_name')
    .select('*')

  if (error) console.error('Error fetching data:', error)
  else console.log('Data:', data)
}

fetchData()

6. Configure Authentication (Optional)

Supabase comes with built-in authentication services, including email/password, OAuth (Google, GitHub, etc.), and magic links.

Step 1: Enable Authentication

In the Supabase dashboard:

1. Go to the Authentication section.
2. Configure the providers you want to use (e.g., email/password, Google OAuth).

Step 2: Use Authentication in Your AI Agent

You can use the Supabase client to handle user authentication in your AI agent.

Example: Sign Up a User

async function signUp(email, password) {
  const { user, error } = await supabase.auth.signUp({
    email,
    password,
  })

  if (error) console.error('Error signing up:', error)
  else console.log('User signed up:', user)
}

signUp('[email protected]', 'password123')

7. Real-Time Subscriptions

Supabase supports real-time subscriptions using WebSockets. This is useful for AI agents that need to react to changes in the database in real-time.

Example: Listening for Changes

const subscription = supabase
  .channel('public:your_table_name')
  .on(
    'postgres_changes',
    { event: '*', schema: 'public', table: 'your_table_name' },
    (payload) => {
      console.log('Change received!', payload)
    }
  )
  .subscribe()

8. Stop Supabase

When you're done working, you can stop the Supabase services.

Step 1: Stop Docker Containers

Press Ctrl+C in the terminal where Docker Compose is running to stop the services.

Step 2: Remove Containers (Optional)

If you want to clean up all containers and volumes, run:

docker compose down

9. Advanced: Customizing Supabase

9.1. Environment Variables

You can customize Supabase by editing the .env file in the docker directory. For example, you can change the default database name, user, or password.

9.2. Persistent Storage

By default, Docker containers are ephemeral, meaning data will be lost when you stop the containers. To persist data, you can configure Docker volumes in the docker-compose.yml file.

10. Conclusion

Running Supabase locally is a straightforward process thanks to Docker and the official Supabase repository. By following the steps above, you can set up a local development environment for your AI agents, complete with a PostgreSQL database, authentication, real-time subscriptions, and more.

Key benefits of running Supabase locally include:

• Privacy: Keep your data on your local machine.
• Speed: Faster iteration during development.
• Customization: Full control over the environment and configuration.

With Supabase running locally, you can focus on building and testing your AI agents without worrying about external dependencies or remote servers.