# How do I run Supabase locally with my AI-built app?

> Start the Supabase CLI stack, connect the local app to its actual project URL and keys, and verify a test record stays off production.

Canonical HTML: https://canopyide.dev/guides/run-supabase-locally-with-ai-built-app
Article date: 2026-09-28

Your app runs at localhost, but its Supabase URL still points to a hosted project. To test without changing live data, start a separate local Supabase stack and make the app use its local URL and keys. A local browser address alone does not choose the database. Verify the actual request and a disposable record before giving an agent permission to import data, run migrations, or fix the feature.

## Check what the repository already has

Open the app's repository in Canopy and identify its package manager, frontend or backend run command, existing `supabase/` directory, and environment-variable names. Do not run `supabase init` in an existing initialized project merely because a setup guide says to. Supabase's CLI is project-scoped: most commands expect the directory containing `supabase/config.toml`. If the app has no Supabase folder, decide with its owner whether local development is being added to this repository and where its schema and migrations will live. A project-installed CLI runs through its package manager; a globally installed CLI uses `supabase` directly. Supabase currently documents Node.js 20 or later for its npm-installed CLI and a running Docker-compatible container runtime for the local stack.

- Read the repository's own setup instructions and lockfile before installing a second CLI version.
- Record the exact working directory for the app and the Supabase command.
- Keep production connection strings and secret keys out of an agent prompt or public screenshot.

## Start Supabase and read its actual local status

For a new local project, Supabase documents `supabase init` once, then `supabase start` from that project directory. If the CLI is a project dependency, use the matching package-runner form, such as `npx supabase start` or `pnpm supabase start`. The first start downloads container images and can take longer. After startup, run `supabase status` in the same directory to see the current local Project URL, database URL, Studio and Mailpit URLs, and keys. Treat that output as sensitive because it includes credentials. The start command sets up containers; the app's development server is a separate process. A finished startup command in Canopy is not proof the database stopped, and a saved Canopy command is not proof it is running now. Use status and a real app request to check.

*The local stack and the app have different owners and checks.*

| Component | Command or owner | Evidence it is ready |
| --- | --- | --- |
| Container runtime | Docker-compatible runtime on this machine | Supabase start completes without container errors |
| Supabase stack | CLI command in the initialized repository | `supabase status` shows the intended local project and URLs |
| App server | Repository's documented dev command in Canopy Servers | Printed local URL and a successful browser request |
| App data path | App configuration and network request | Disposable write appears in local Studio or a verified local read |

## Connect the app to the local project, not just localhost

Find every place the app reads its Supabase URL and keys: browser client, server routes, background worker, test runner, and any generated configuration. Compare those values with the current local `supabase status` output, using redacted identifiers when recording evidence. Replace development settings with the local Project URL and appropriate local keys through the app's documented environment mechanism; keep live settings in their separate deployment environment. The variable names depend on the framework, so do not copy a generic `.env` snippet blindly. Public or publishable keys may be used where the client framework expects them; secret or service-role credentials belong only on the server. Restart any process that read the old variables at startup. If a browser request still reaches a hosted Supabase domain, the app is not using local data even if the local Studio opens correctly.

- Check the frontend's request host and the backend's configured target separately.
- If a worker or scheduled job writes data, give it the same intended development target and verify its own run.
- Do not paste full `supabase status` output into an issue, agent chat, or screenshot because it includes local credentials.

## Prove one safe write and one fresh read

Create a disposable test record with a unique label through the running app. Confirm the browser request or backend log targets the local Project URL, then find that record in local Studio or through a fresh local read. Reload the page and check the behavior the product promises. If Save only updates component state, the local stack cannot fix persistence on its own; trace the app handler and response. If a record appears in hosted Supabase instead, stop tests and correct the endpoint before asking an agent to change schema or data. Test a failed request as well as a successful one so the UI does not claim a save when the backend rejected it. Use separate test users if authorization is part of the feature.

- Record app URL, request host, local project identifier, test label, and observed read-back without exposing private data.
- Ask the agent to show changed environment names, code paths, migrations, and exact tests, then inspect the final diff.
- A green local app and a green Supabase status are inputs to the test, not proof the app uses that stack.

## Make the next startup repeatable

Save the app's real run command and working directory in Canopy Servers. You can save the Supabase startup or status command as a project action if your installed Canopy version supports the needed command behavior, but confirm its result with `supabase status`; the containers outlive the startup command. Label the local Project URL and which checkout's `supabase/config.toml` owns it in a short project note, without recording secret keys. On the next day, check the container runtime and `supabase status` before starting the app, and verify one read. Supabase documents `supabase stop` as a normal stop that preserves local data, whereas reset or no-backup options can remove it. Do not run destructive cleanup merely to make an agent's setup command appear fresh. If two agent worktrees share one local Supabase project, coordinate mutating tests and migrations; worktrees alone do not isolate containers or data.

- Keep startup commands, expected URLs, and a safe test account documented for the team.
- Review schema and migration changes before applying them to shared or hosted projects.
- Check the installed Canopy release before relying on a newer main-branch service control.

## Copyable resources

### Local Supabase connection check

Use redacted identifiers. Keep real keys in the app's approved environment configuration.

````text
Repository and checkout/branch: [ ]
App command, working directory, and printed URL: [ ]
Supabase CLI install method and command form: [ ]
Initialized supabase/config.toml location: [ ]
Container runtime ready and supabase start result: [ ]
Redacted local Project URL from supabase status: [ ]
Browser/client configured host; backend/worker configured host: [ ]
Disposable test record and write request host: [ ]
Fresh local read or Studio evidence: [ ]
Failure-path result and production target checked separately: [ ]
Saved startup commands, final diff, tests, and owner: [ ]
````

## Frequently asked questions

### Does running my app at localhost automatically use local Supabase?

No. The app can call a hosted Supabase URL. Check the configuration used by its browser, backend, and workers, then verify a real request and record in the intended local project.

### Why did supabase start finish while the database still runs?

The CLI starts a containerized local stack and reports its URLs. The startup command can finish while containers continue; use `supabase status` and an app request to check current state.

### Should I replace my production Supabase keys in the repository?

Keep production settings in their deployment environment and use separate local development configuration. Do not commit secret keys or copy a live service-role key into browser code.

### Will two agent worktrees get separate local Supabase databases?

Not automatically. Different checkouts can still point to the same local URL and containers. Compare their actual configuration and coordinate writes and migrations.

## Sources and further reading

- [Supabase CLI: init, start, local URLs and credentials](https://supabase.com/docs/guides/local-development/cli/getting-started)
- [Supabase local development workflow and data-preserving stop](https://supabase.com/docs/guides/local-development/cli-workflows)
- [Supabase CLI status reference](https://supabase.com/docs/reference/cli/supabase-status)
- [Supabase API keys: publishable and server-only secret keys](https://supabase.com/docs/guides/getting-started/api-keys)
- [Canopy app README: project components and development services](https://github.com/FluidWorksApp/canopy-ide/blob/main/README.md)

## Related Canopy pages

- [Is my local AI-built app using the production database?](https://canopyide.dev/guides/is-local-ai-built-app-using-production-database.md)
- [How do I start my website, API, and worker with one click?](https://canopyide.dev/use-cases/one-click-local-dev-stack.md)
- [Run a website, API, and background worker in one workspace](https://canopyide.dev/guides/run-local-development-servers.md)
- [Why does my AI-built app lose data when I refresh?](https://canopyide.dev/guides/ai-built-app-loses-data-on-refresh.md)
- [Can two coding agents use the same development database?](https://canopyide.dev/guides/parallel-coding-agents-share-development-database.md)

Canopy runs installed coding CLIs; CLI accounts, model selection, and provider billing remain separate. Check the installed release before relying on version-specific behavior.