From bf633521b423f2e9b925dd367e2a2d70202d929c Mon Sep 17 00:00:00 2001
From: Fabrizio <fabri.feno@gmail.com>
Date: Fri, 12 Jun 2026 10:09:31 +0200
Subject: [PATCH] fix: add vector bucket local CLI section (#46646)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Docs update

## What is the nee current behavior?

Added new section to explain how  vector buckets works locally

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added a "Local Development" guide for Vector Buckets covering
alpha-status cautions, local vs hosted behavior, steps to enable local
vector storage, declarative bucket configuration, and how to create
buckets for local testing.
* Updated site navigation to include the new Local Development guide in
the Storage → Vector docs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
---
 .../NavigationMenu.constants.ts               |  5 +++
 .../storage/vector/local-development.mdx      | 45 +++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 apps/docs/content/guides/storage/vector/local-development.mdx

diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
index e6a75d5cc5c..ee15f6ff838 100644
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
@@ -2189,6 +2189,11 @@ export const storage: NavMenuConstant = {
           name: 'Querying Vectors',
           url: '/guides/storage/vector/querying-vectors' as `/${string}`,
         },
+        {
+          name: 'Local Development',
+          url: '/guides/storage/vector/local-development' as `/${string}`,
+          enabled: billingEnabled,
+        },
         {
           name: 'Limits',
           url: '/guides/storage/vector/limits' as `/${string}`,
diff --git a/apps/docs/content/guides/storage/vector/local-development.mdx b/apps/docs/content/guides/storage/vector/local-development.mdx
new file mode 100644
index 00000000000..e81fbab3e91
--- /dev/null
+++ b/apps/docs/content/guides/storage/vector/local-development.mdx
@@ -0,0 +1,45 @@
+---
+title: 'Vector Bucket Local Development'
+subtitle: 'Develop and test vector bucket integrations in your local environment with the Supabase CLI.'
+---
+
+<Admonition type="caution" title="This feature is in alpha">
+
+Expect rapid changes, limited features, and possible breaking updates. [Share feedback](https://github.com/orgs/supabase/discussions/40116) as we refine the experience and expand access.
+
+</Admonition>
+
+You can now develop and test Vector Bucket integrations in your local environment using the Supabase CLI.
+
+This allows you to build and iterate on your vector search applications without needing to deploy to a live environment.
+Make sure you have the latest version of the Supabase CLI installed to access this feature.
+
+<Admonition type="note" title="Local driver">
+
+In local development, vector buckets uses pg_vector as the underlying storage engine under the hood.
+The Hosted version uses S3Vectors as the Storage engine for vectors, which is optimized for large-scale vector storage and similarity search. This means that while you can develop and test your vector bucket integrations locally, there may be differences in performance and behavior compared to the cloud environment.
+
+The API remain consistent between local and hosted environments, so you can build your application logic against the local pg_vector implementation and expect it to work with the S3Vectors engine in production.
+
+</Admonition>
+## Setting up local vector buckets
+
+Make sure you have the feature enabled in your `config.toml` file:
+
+```toml
+
+# Store vector embeddings in S3 for large and durable datasets
+[storage.vector]
+enabled = true
+```
+
+### Declarative configuration
+
+You can define your vector buckets in the `config.toml` file using the following syntax:
+
+```toml
+[storage.vector.buckets.documents-openai]
+[storage.vector.buckets.images]
+```
+
+Then use `supabase seed buckets` to create the buckets in your local environment or linked project.