Self-hosting guide

Your own Caboodle, without the server headache.

You do not need to be technical. We will create three free accounts, copy a few values, and check each part together. Start on Vercel Hobby and Supabase Free, with no custom domain required.

  Let Codex guide me Follow the manual guide

Free tiers have usage and eligibility limits. You can upgrade later; nothing in this guide requires a paid plan to get started.

Your starter stack $0 to start
GitHubYour copy of the codeFree
SupabaseAccounts, data & filesFree
VercelThe website & MCP endpointHobby
30–45minutes 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

Open these in separate tabs. Use accounts you control, because each service will hold one part of your Caboodle.

  • GitHub — keeps your own copy of the Caboodle code.
  • Supabase — provides sign-in, the database, and private file storage.
  • Vercel — runs the website and gives it a secure web address.
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 5 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 5–10 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 8 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 8 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 3 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
The payoff

Connect Codex or Claude Code

Your MCP address is always your Vercel address plus /mcp. Adding it to an agent should open a browser so you can sign in and approve access.

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 agent 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 agents 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.

Keep it small and free

What “$0 to start” means

The included architecture fits a personal or hobby-sized Caboodle without a dedicated server. Current plan rules can change, so check the linked plan pages before relying on exact limits.

Vercel Hobby

A free plan intended for personal projects, with automatic HTTPS and Git deployments. Keep Caboodle in your personal account for the Hobby path.

Read current Vercel plans →

Supabase Free

A free project includes a small Postgres database, authentication, and file storage. Free projects may pause after inactivity; return to the dashboard to restore one.

Read current Supabase limits →
Optional costs: a custom domain, heavier traffic, larger storage, guaranteed uptime, or branded invitation email delivery. None is required to learn Caboodle, use it yourself, or connect your own agent.
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