Self-hosting guide

Setup Caboodle in 20 minutes, running completely free.

You do not need to be technical. In about 20–30 minutes, you will create three free accounts, copy a few values, and check each part together. Vercel Hobby and Supabase Free are completely sufficient.

  Let Codex guide me Follow the manual guide

Caboodle is open source and this guide uses free GitHub, Vercel, and Supabase accounts.

Your starter stack Free to run
GitHubYour copy of the codeFree
SupabaseAccounts, data & filesFree
VercelThe website & MCP endpointHobby
20–30minutes 3accounts 8checkpoints
First, choose your comfort level

You can do this with a guide beside you

Both paths create the same private Caboodle. The guided path is easiest: Codex checks the project, explains each screen in plain language, and waits at the moments where you need to sign in or approve a change.

Recommended

Use the setup skill

Best if words like migration, OAuth, or environment variable are new to you.

  Download the skill
  1. Unzip it into your personal Codex skills folder: ~/.codex/skills on Mac/Linux or %USERPROFILE%\.codex\skills on Windows.
  2. Restart Codex or open a new task.
  3. Say: “Use $caboodle-self-host to set up my own Caboodle.”
Manual

Follow this page

Every click and value is below. The one database step uses four copy-and-paste commands.

Start the checklist

You can switch to the guided skill at any point. It will inspect what is already complete and continue from there.

Before you begin

Gather three free accounts

Create these accounts before continuing. Open each link in a separate tab and use accounts you control.

  1. Create a free GitHub account, or sign in if you already have one. GitHub keeps your own copy of the Caboodle code.
  2. Create a free Supabase account. Continue with email or a provider you already use. The Free option is completely sufficient for Caboodle’s database, sign-in, and file storage.
  3. Create a free Vercel account. Continuing with GitHub makes the deployment step easiest. Choose a personal account and the Hobby option; it is completely sufficient to host Caboodle and its MCP endpoint.
What is an environment variable? Just a named setting. Vercel shows a box for the name and a box for its value. You will copy the names exactly; you do not need to write code.
1
About 2 minutes

Make your own copy of Caboodle

On GitHub, a copy is called a fork. It belongs to your account, so future changes are under your control.

  1. Open Fork Caboodle on GitHub.
  2. Leave the repository name as Caboodle. Keep “Copy the main branch only” selected.
  3. Choose Create fork. Wait until GitHub shows a Caboodle page under your username.
No code changes are needed. Vercel will use the ready-to-deploy app inside the folder named production.
2
About 3 minutes

Create Caboodle’s Supabase project

This is the private home for your accounts and packages. Caboodle already includes the permissions that keep one user’s data away from another’s.

  1. Open New Supabase project and choose your personal organization.
  2. Name it Caboodle. Choose the Free plan and a region near you.
  3. Create a strong database password and save it in your password manager. You need it once in the next step. Do not place this password in Vercel.
  4. Choose Create new project and wait until the project dashboard opens.
  5. Open Settings → API Keys. Copy the Project URL and the Publishable key that begins with sb_publishable_.
Project URLhttps://your-project-ref.supabase.co
Publishable keysb_publishable_... — safe for this web app
Project referenceThe short text between https:// and .supabase.co
Database passwordKeep private; use only while preparing the database
Stop if you see “secret” or “service_role.” Caboodle does not need either key. The low-privilege publishable key is the correct one.
3
About 4–6 minutes

Prepare the database

Caboodle includes a small, ordered set of database setup files called migrations. Applying them creates the tables, roles, storage bucket, and security rules. The setup skill can do this for you and show you exactly what will change before it runs anything.

Easiest path: open the fork on your computer in Codex, load the setup skill, and say “Continue from the database step. My Supabase project is ready.” Codex will use the included files in order and pause before changing the remote database.
Show the manual command-line path

Open a terminal in your fork. These commands install the project’s tools, sign you in to Supabase, connect this folder to your project, and apply the included migrations.

cd production npm install npx supabase login npx supabase link --project-ref YOUR_PROJECT_REF npx supabase db push

Replace YOUR_PROJECT_REF with the short reference you saved. Your browser may open for Supabase sign-in. When asked for the database password, paste the one you saved. A successful final message says the linked project is up to date.

What this creates: private package tables, sign-in profiles, role-based access rules, audit records, full-text search, an OAuth audience hook, and a private caboodle-source storage bucket. It does not add sample users or publish anything.
4
About 5 minutes

Put your Caboodle on Vercel

Vercel turns the production folder into a secure website. Its free address is enough; a custom domain is optional.

  1. Open Add New Project in Vercel. Connect GitHub if asked.
  2. Find your fork named Caboodle and choose Import.
  3. Open Root Directory, choose production, and confirm. Vercel should recognize Next.js.
  4. Before deploying, expand Environment Variables and add the five rows below. Use your Supabase values for the first two.
NEXT_PUBLIC_SUPABASE_URLYour Supabase Project URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEYYour sb_publishable_... key
NEXT_PUBLIC_APP_URLhttps://YOUR-VERCEL-NAME.vercel.app
MCP_RESOURCE_URIhttps://YOUR-VERCEL-NAME.vercel.app/mcp
CABOODLE_ALLOW_TEST_TOKENSfalse
But I do not know my Vercel address yet. That is normal. Pick the project name first—for example, my-caboodle—and Vercel normally offers https://my-caboodle.vercel.app. If the final address differs, update the two URL values after the first deploy and choose Redeploy.
  1. Apply the variables to Production, Preview, and Development for the simplest setup.
  2. Choose Deploy. When the celebration screen appears, open the provided .vercel.app address.
  3. If the address differs from the one you entered, go to Project Settings → Environment Variables, correct NEXT_PUBLIC_APP_URL and MCP_RESOURCE_URI, then redeploy.
Skip these for now: RESEND_API_KEY and CABOODLE_EMAIL_FROM. They are only for optional branded invitation emails. Supabase still handles your account confirmation email on its own.
5
About 5 minutes

Tell Supabase where Caboodle lives

These settings make account confirmation and secure agent sign-in return to your website instead of somewhere else. Use the same Vercel address everywhere, with https:// and no trailing slash.

A. Website sign-in

  1. In Supabase, open Authentication → URL Configuration.
  2. Set Site URL to https://YOUR-VERCEL-NAME.vercel.app.
  3. Add both https://YOUR-VERCEL-NAME.vercel.app/auth/callback and https://YOUR-VERCEL-NAME.vercel.app/oauth/consent to Redirect URLs, then save.

B. Modern signing keys

  1. Open Project Settings → JWT Keys. Confirm the active signing key is asymmetric, such as ES256 or RS256.
  2. If the page only shows a legacy shared secret, use Supabase’s Migrate JWT secret flow, then rotate to the new asymmetric standby key. New projects may already be set up correctly.

C. Agent sign-in (OAuth)

  1. Open Authentication → OAuth Server and enable OAuth 2.1 server capabilities.
  2. Set Authorization Path to /oauth/consent.
  3. Enable Dynamic Client Registration so compatible MCP clients can connect. Keep user approval required.
  4. Open Authentication → Hooks. For Custom Access Token, choose the Postgres function public.custom_access_token_hook and enable it.

D. Bind tokens to your Caboodle

In Supabase, open SQL Editor, choose New query, paste this, replace the address, and choose Run:

update public.oauth_resource_config set resource_uri = 'https://YOUR-VERCEL-NAME.vercel.app/mcp' where singleton;

A success message may say “Success. No rows returned.” That is expected for an update command.

6
About 2 minutes

Test the two important doors

First test the human door, then the agent door. If both open, the hard part is finished.

  1. Open https://YOUR-VERCEL-NAME.vercel.app/signin, choose Create account, and use your email plus a password of at least eight characters.
  2. Open Supabase’s confirmation email. The link should return to your Caboodle dashboard.
  3. Open https://YOUR-VERCEL-NAME.vercel.app/.well-known/oauth-protected-resource/mcp. A small page of structured text should appear and include your /mcp address.
  4. In Supabase, open Table Editor. You should see tables such as profiles, workspaces, and packages. You do not need to edit them.
You are live. Your Caboodle is now a real, private web app backed by your own Supabase project. GitHub holds the code, and future changes to your fork can deploy automatically through Vercel.
7
About 3–5 minutes

Connect Claude or ChatGPT

Your custom MCP address is your Vercel address plus /mcp. For example: https://YOUR-VERCEL-NAME.vercel.app/mcp. Choose either Claude or ChatGPT below.

Works with a free Claude account

Add Caboodle to Claude

  1. In Claude, open Customize → Connectors.
  2. Choose +, then Add custom connector.
  3. Name it Caboodle and paste your complete https://...vercel.app/mcp address. You do not need the optional advanced client ID or secret.
  4. Choose Add, then Connect. Sign in to your Caboodle account and approve access when the browser opens.
  5. Start a new chat. Choose the + beside the message box, open Connectors, and turn on Caboodle for that conversation.
Official Claude connector guide →
ChatGPT on the web

Add Caboodle to ChatGPT

  1. Open ChatGPT on the web. Go to Settings → Apps → Advanced Settings and turn on Developer mode.
  2. Return to Settings → Apps and choose Create. Workspace administrators can instead use Workspace settings → Apps → Create.
  3. Name the app Caboodle, enter your complete https://...vercel.app/mcp endpoint, and use the server’s OAuth authentication.
  4. Choose Scan Tools. Complete the Caboodle sign-in and approval window, wait for the scan to finish, then choose Create.
  5. Start a new chat, open the tools or Apps menu, and select Caboodle before asking it to search or manage your packages.
If Developer mode is missing: custom MCP app access is not enabled for that ChatGPT account or workspace yet. Use Claude or Codex instead; your Caboodle setup is still complete.
Official ChatGPT MCP guide →
Prefer Codex or Claude Code?

Codex

codex mcp add caboodle --url https://YOUR-VERCEL-NAME.vercel.app/mcp

Claude Code

claude mcp add --transport http caboodle https://YOUR-VERCEL-NAME.vercel.app/mcp

After connection, ask the assistant to search Caboodle or create a private package. Caboodle checks your account and role again on every operation, so sharing and revocation take effect without giving the assistant a master database key.

0 of 8 checkpoints completeSaved only in this browser.
The simple mental model

What talks to what?

Think of Caboodle as a front desk, a locked records room, and a trusted caller.

Your agentAsks to search, use, or manage a package.
VercelRuns Caboodle’s site, API, and /mcp front door.
SupabaseVerifies the person, role, data, and storage access.
GitHub is the source copy.
Vercel reads the production folder from your fork. A future commit can trigger a fresh deployment.
No master key in the app.
Caboodle uses the publishable key plus each signed-in user’s token. Supabase’s Row Level Security makes the final decision.
If something does not look right

Most problems are one copied value

The Vercel deployment failed

Open the deployment, then its build log. Confirm the Root Directory is exactly production. If the log names a missing NEXT_PUBLIC_... value, add all five environment variables under Project Settings, then redeploy.

The confirmation email returns to localhost

In Supabase, change Authentication → URL Configuration → Site URL to your exact https://...vercel.app address. Add the exact /auth/callback redirect URL, save, then request a new confirmation email.

Sign-in works, but the dashboard shows a database error

The migrations probably did not finish. Run npx supabase link --project-ref YOUR_PROJECT_REF and then npx supabase db push again from the production folder. It is safe to rerun: completed migrations are skipped.

The agent says OAuth discovery or registration failed
  • Confirm Authentication → OAuth Server is enabled.
  • Confirm Dynamic Client Registration is enabled.
  • Confirm Authorization Path is exactly /oauth/consent.
  • Open the /.well-known/oauth-protected-resource/mcp test address again.
The agent signs in, then receives “invalid token”
  • Confirm the active JWT key is ES256 or RS256.
  • Confirm the Custom Access Token hook is enabled and points to public.custom_access_token_hook.
  • Confirm the SQL resource URI, Vercel MCP_RESOURCE_URI, and the agent’s MCP URL are the exact same HTTPS address ending in /mcp.
  • Disconnect and reconnect the agent after correcting the values so it receives a fresh token.
I changed a Vercel setting, but nothing changed

Environment variable changes apply only to new deployments. Open Vercel → Deployments, use the menu on the latest deployment, and choose Redeploy.

Free service notes

Everything you need to run Caboodle

Caboodle is open source and free. The included architecture uses the free services from GitHub, Vercel, and Supabase, so a personal Caboodle does not need a dedicated server.

Vercel Hobby

Hosts your Caboodle with automatic HTTPS and Git deployments. Keep Caboodle in your personal account for this setup.

Read the deployment guide →

Supabase Free

Provides the Postgres database, authentication, and file storage Caboodle needs. If an inactive project pauses, open its dashboard to restore it.

Read the platform guide →
No special infrastructure: the default service addresses work as-is, so you do not need to configure a custom domain or run a server.
Ready when you are

Let the setup skill keep your place

It recognizes completed checkpoints, explains what each service is doing, protects private values, and will not run the database or deployment changes without showing you first.

Vercel Git deploymentsOfficial reference Supabase migrationsOfficial reference MCP authenticationOfficial reference Use CaboodleContinue to the product guide