---
title: "Using Supabase with Hoplite"
description: "Run a repository's local Supabase stack inside a cloud thread."
canonical_url: "https://hoplite.sh/docs/sandboxes/supabase"
markdown_url: "https://hoplite.sh/docs/sandboxes/supabase.md"
---

# Using Supabase with Hoplite
URL: /docs/sandboxes/supabase
LLM index: /llms.txt
Description: Run a repository's local Supabase stack inside a cloud thread.
Related: /docs/sandboxes, /docs/sandboxes/scripts, /docs/sandboxes/previews

# Using Supabase with Hoplite

Hoplite runs a Supabase CLI project's local stack (Postgres, Auth, the REST and Realtime APIs, Storage, edge functions, and Studio) inside the thread's own workspace, so agents build and test against a real database without touching your hosted project.

## How the runtime is chosen

The local stack runs in Docker, and only the Docker Compose runtime has a Docker daemon. Hoplite selects it automatically when the repository contains `supabase/config.toml`, either at the root or in a nested app directory such as `web/supabase/config.toml` or `apps/web/supabase/config.toml`. You don't need a setup script for this; the file is enough.

To force the runtime for every new thread regardless of detection, select **Docker Compose** under **Settings → Project → Sandbox**. If a thread started on the standard runtime before detection saw the file, the agent switches that thread onto Docker Compose itself and keeps its worktree. See [Docker Compose workspaces](/docs/sandboxes#docker-compose-workspaces).

## Start the stack

Run the CLI from the directory that contains `supabase/`:

```sh
npx supabase start -x vector
```

`-x vector` skips the log-shipping container, which needs a privileged Docker security option that Hoplite refuses by design. Every other service starts normally. To start the stack in every new workspace, put the command in your setup script:

```json title=".hoplite/settings.json (scripts excerpt)"
{
  "scripts": {
    "setup": "pnpm install && npx supabase start -x vector"
  }
}
```

`npx supabase status -o env` prints the API URL, the anon and service-role keys, and the database URL. Server-side code reaches the API at `http://127.0.0.1:54321` and Postgres at `postgresql://postgres:postgres@127.0.0.1:54322/postgres`.

## Nested Compose stacks

Repositories that run self-hosted Supabase through their own `docker compose` file work the same way, including bind mounts such as `./supabase/volumes/db/jwt.sql`.

## Current limitations

- The managed Preview serves your app's port. Supabase's API port (`54321`) and Studio (`54323`) are not yet reachable from the Preview browser, so browser-side Supabase calls from the Preview need to go through your app's own server for now.

## Sitemap

Sitemap discovery is not enabled for this deployment.