Supa Local GUI brings a web-based interface to your local Supabase development workflow. Rather than digging through documentation to remember every option, configure your services directly from the browser.
Warning
Supa Local GUI is currently in beta and breaking changes may occur between releases. It's recommended to keep your supabase directory under version control and review any changes before committing them.
- Features
- Prerequisites
- Getting Started
- Network configuration
- Image registries
- Environment Variables
- Opinionated Behavior
- Limitations
- FAQ
- Contributing
- License
- Auth - Modify all your auth configuration from the browser.
- Secure by default - Every sensitive value such auth hook secrets, OAuth provider secrets, captcha keys etc. is automatically written to your env file.
- Edge Functions - Add, rename, test, and configure functions, with a built-in Deno LSP for IntelliSense in code editor.
- Granular restarts - After making config changes, you'll get a visual indication that a restart is needed, and can restart the affected container(s) with a single button press. This avoids tearing down and restarting the entire stack as the Supabase CLI requires.
I feel auth and edge functions are what people configure most in local development, so I've started with these two. Other services may be supported over time.
Before you begin, make sure you have:
- Docker installed and running.
- A Supabase project with
config.toml, created by runningsupabase initusing Supabase CLI. - Optionally, your local stack running (
supabase start). You can make configuration changes without starting the local Supabase stack but if you plan to restart containers, at minimum the database container must be up, since restarted containers connect to it and their health checks depend on that.
Supa Local GUI ships as a Docker image. Mount your local supabase directory and the Docker socket, and you're ready to go.
Prefer to learn by watching? Here's the full walkthrough.
Create a named volume so the Deno LSP can cache modules and reuse them across container runs, instead of re-downloading them every time:
docker volume create slg_deno_modulesYou can name this volume anything you like - just keep it consistent with the -v flag in the run command below.
Important
Always pin a specific image tag (:<version>) instead of using latest. The correct version depends on your installed Supabase CLI version - see COMPATIBILITY.md to choose the right tag. Replace <version> in the commands below with that tag.
docker run `
-v .\supabase:/supabase `
-v /var/run/docker.sock:/var/run/docker.sock `
-v slg_deno_modules:/deno_modules `
-e SLG_HOST_CWD='C:\absolute\path\to\your\supabase\config.toml' `
-p 5000:5000 `
ghcr.io/singh-inder/supa-local-gui:<version>docker run \
-v ./supabase:/supabase \
-v /var/run/docker.sock:/var/run/docker.sock \
-v slg_deno_modules:/deno_modules \
-e SLG_HOST_CWD='/absolute/path/to/your/supabase/config.toml' \
-p 5000:5000 \
ghcr.io/singh-inder/supa-local-gui:<version>-v ./supabase:/supabase- Mounts your localsupabasedirectory into the container so the GUI can read and write your project files (config, functions, templates).-v /var/run/docker.sock:/var/run/docker.sock- Gives the container access to the host Docker daemon so it can inspect and restart your Supabase containers.-v slg_deno_modules:/deno_modules- Mounts the namedslg_deno_modulesvolume so the Deno LSP can cache modules and reuse them across container runs.-e SLG_HOST_CWD='...'- Passes an environment variable which tells the app the absolute host path to yourconfig.toml. Replace the placeholder with the absolute path to your ownconfig.toml. Required when restarting containers (see Environment Variables).-p 5000:5000- Exposes the web GUI onhttp://localhost:5000.
Once the container is running, open http://localhost:5000 in your browser.
If you plan to restart the edge-runtime or postgrest containers through the web interface, Supa Local GUI must run on the same Docker network as your Supabase stack. Health checks for these containers are performed via HTTP requests, so network-level access is needed to reach them.
Add --network supabase_network_<project_id> to the run command, where <project_id> is the project_id value defined in your config.toml:
docker run \
-v ./supabase:/supabase \
-v /var/run/docker.sock:/var/run/docker.sock \
-v slg_deno_modules:/deno_modules \
-e SLG_HOST_CWD='/absolute/path/to/your/supabase/config.toml' \
-p 5000:5000 \
--network supabase_network_<project_id> \
ghcr.io/singh-inder/supa-local-gui:<version>The only addition compared to the base command is the --network supabase_network_<project_id> line.
The image is published to both registries below. Use whichever you prefer:
- GitHub Container Registry:
ghcr.io/singh-inder/supa-local-gui - Docker Hub:
singhinder/supa-local-gui
Note
On Docker Hub the account namespace is singhinder (no hyphen). Docker Hub does not allow hyphens in account names, so the namespace differs from the GitHub one (singh-inder).
| Variable | Description | Example | Default | Required |
|---|---|---|---|---|
SLG_HOST_CWD |
Absolute path to the config.toml file on the host machine. You only need it if you want to restart container(s) after making config updates - it's then used to mount volumes into the recreated containers. |
/home/john/my-app/supabase/config.toml |
— | No |
SLG_ENV_FILE |
Path to the environment file used for reading and writing env vars. Set this to use a different env file. | .env.local |
.env |
No |
SLG_EXPERIMENTAL_PRESERVE_COMMENTS |
Experimental. When "true", attempts to preserve comments and original formatting when writing updates to config.toml. Some structure/formatting may still change during the merge. When disabled, the config file is rewritten without comments (faster, more predictable). |
"true" |
false |
No |
Tip
If you keep your config.toml under version control, you can also use a LLM to merge comments back in: pass the git diff and ask it to restore comments without changing any new values. This works well as an alternative to the SLG_EXPERIMENTAL_PRESERVE_COMMENTS option above.
Supa Local GUI is opinionated by design. The behaviors below are deliberate choices made to keep the software simple.
- Functions live inside
supabase/functions- Only functions insidesupabase/functionsare supported; you cannot import functions from outside this folder. This avoids mounting many volumes and keeps the setup simple. - Manage dependencies via
deno.json/deno.jsonc- Onlydeno.jsonordeno.jsoncare supported for managing dependencies. - Templates are relocated automatically - On startup, if your templates are not found at the expected opinionated path, Supa Local GUI will automatically copy them there, update your
config.toml, and restart the Kong container so the changes take effect. Auth templates are placed atsupabase/templates/auth/<template_name>and notification templates atsupabase/templates/notification/<template_name>.
- Self-hosted (Docker Compose) Supabase - Only the Supabase CLI workflow is supported. Docker Compose based self-hosted setups are not.
- Branching config - Per-remote
[remotes]config is currently not supported. - Services beyond auth and functions - Configuration for other services (storage, realtime, and so on) is not yet available.
What image versions are used and can I change them?
By default, the service image versions are the ones defined in the Dockerfile.
To override them, the recommended approach is to run supabase link, which pins your local image versions to match those running on your hosted Supabase project. This creates version files in the supabase/.temp folder, which Supa Local GUI reads and uses.
You can also create these files manually in supabase/.temp. Each file holds a single version tag - for example, to specify auth image version create a file supabase/.temp/gotrue-version containing:
v2.188.0
The supported version files are:
| File | Service |
|---|---|
rest-version |
PostgREST |
gotrue-version |
Auth (GoTrue) |
storage-version |
Storage |
edge-runtime-version |
Edge Runtime |
realtime-version |
Realtime |
When a container is restarted, if the specified image isn't already available locally, it will be downloaded automatically.
Does Supa Local GUI work with self-hosted (Docker Compose) Supabase?
No. It currently supports only the Supabase CLI workflow. Docker Compose based self-hosted setups are not supported.
Will it modify my config.toml directly?
Yes. Supa Local GUI writes your changes back to config.toml. This is why it's recommended to keep your supabase directory under version control, and to review changes before committing them.
Why can't I import functions from outside supabase/functions?
This is a deliberate, opinionated choice to avoid mounting many volumes and to keep the setup simple. It's a constraint of Supa Local GUI, not the Supabase CLI.
Do I need to restart my entire stack to apply changes?
No - that's one of the reasons Supa Local GUI exists. You can restart only the affected container(s) from the GUI, instead of tearing down and restarting the whole stack as the CLI requires.
Why do I need the --network flag?
You only need it if you plan to restart the edge-runtime or postgrest containers from the GUI. Their health checks run over HTTP, so Supa Local GUI must share their Docker network to reach them. See Network configuration.
Which version of Supa Local GUI should I use?
The image version depends on your installed Supabase CLI version. See COMPATIBILITY.md for the right tag.
Is this an official Supabase project?
No. Supa Local GUI is an independent, community project. For any information regarding Supabase itself you can refer to their docs.
Contributions are welcome! Please open an issue to discuss significant changes before submitting a pull request.
Portions of the code are adapted from the Supabase CLI, licensed under the MIT License.
This project is licensed under the Apache 2.0 License.