Supabase Local Manager

macOS

Node, Docker and the cross-platform launcher. The terminal steps, the ports and the data locations.

On this page
  1. What is supported
  2. Open and sign in
  3. Where data lives
  4. If it goes wrong

What is supported

The manager runs on macOS as a Node application. You need Node.js 18 or later, npm, a Docker runtime, and the Supabase CLI through npx. Docker Desktop is the usual choice; a compatible Docker runtime works if the docker command is available. The setup script checks Node strictly and warns about Docker and the CLI.

The launcher and the scripts are Node and shell scripts, not Windows-specific. Use the same commands as on Linux; the PowerShell helpers are for Windows only.

Install on macOS

  1. Check Node and npm

    Use the official installer, Homebrew or a version manager, then confirm the versions.

    node --version
npm --version

  2. Start Docker

    Start Docker Desktop, or your Docker runtime, and wait until the daemon responds.

    docker info

  3. Check the Supabase CLI

    Confirm that npx can resolve the CLI. The first call may download it.

    npx supabase --version

  4. Install the workspaces

    From the repository root, change into the product folder and install.

    cd my-supabase-app
npm install

  5. Generate the environment file

    Setup writes .env and prints the administrator credential once.

    npm run setup

  6. Start the dev stack

    The launcher starts the backend and Vite without the npm wrapper chain.

    node scripts/start.mjs

Open and sign in

Open http://localhost:5173 and sign in with the administrator account printed by setup. The manager API and WebSocket listen on PORT, bound to 127.0.0.1; the example file uses 24084 and the code fallback is 24085. The front door defaults to 6000, the subdomain proxy to 9000 and the shared pooler to 6432.

Where data lives

The manager uses the platform data directory through env-paths. On Windows the documented location is %APPDATA%\supabase-local-manager\Config\supabase-manager.db; on Linux and macOS the same library resolves the platform's data directory. The log directory follows the platform log location. The manager database is loaded into memory, so stop the manager before copying the file.

If it goes wrong

  • Docker is not running. docker info fails; start Docker Desktop.
  • The Vite proxy points at the wrong port. Launch through node scripts/start.mjs so Vite runs with the correct working directory.
  • A port is already in use. The launcher frees PORT and PROXY_PORT; the front-door and pooler ports must be freed manually.
  • The backend refuses to boot. Run npm run setup to generate the required keys.

Useful commands

<code>node scripts/start.mjs --prerequisites-only</code>
Check Node, npm and Docker without starting the stack.
<code>npm start</code>
Production launcher; builds missing bundles and serves the interface on the manager port.
<code>npm test</code>
Runs the web workspace tests and the Playwright configuration.
<code>npm run lint</code>
Runs the secret-file and shell-usage checks.