Running the Vercel AI SDK course locally

Use this page to run the extracted customer-support agent on your computer. You connect its Express server to OpenAI and the Supabase data created in the course, then make one start-script change so Node loads those values from .env. The Embeddings and Vector Databases guide runs a related project against the same kind of Supabase vector setup.

What you need first

Install a supported LTS version of Node.js. Node 24 is recommended. You also need:

• an OpenAI API key with billing and model access;
• the Supabase project and data created during the course;
• a key with server-side database access: either a Supabase secret key (it starts with sb_secret_) or the legacy service_role key.

A Supabase secret key and the legacy service_role key both bypass Row Level Security. A key of either type belongs only in this server-side .env, never in browser code. Supabase is deprecating the legacy keys by the end of 2026; they still work, but a secret key is the one that will last. See Supabase API keys.

JunoWhat you need first Install Node.js LTS, then gather your OpenAI key, the Supabase project from the course, and its secret key.

That Supabase key works like a master key to the whole database, so it only ever goes in the server's .env file.

JunoWhat you need first The server reads Supabase with a key that has elevated permissions, and retrieval returns nothing useful without the rows created during the course. Both services and that data have to exist before your first run.

JunoWhat you need first A secret key and the legacy service_role key both bypass Row Level Security, so whoever holds one acts with the server's full database permissions. In browser code, every visitor who opens devtools would hold it too. Keep it in Express only.

Open and install the project

Open a terminal in the extracted folder containing package.json, then install the locked packages:

$ cd path-to-your-downloaded-project
$ npm ci

JunoOpen and install the project Run npm ci in the extracted folder, the one containing package.json. It installs exactly the package versions the course was built with, so there is nothing to choose here.

JunoOpen and install the projectnpm ci installs from the included lockfile, so your versions match the extracted customer-support project exactly. That matters because the AI SDK and the model code were written against those versions.

JunoOpen and install the project Install from the downloaded lockfile before touching anything else. Then change only the start script, so an unrelated dependency update cannot be mistaken for the environment-file fix.

Make Node load .env

Open package.json and change the start script from:

"start": "node server.js"

to:

"start": "node --env-file=.env server.js"

The code uses the legacy variable name SUPABASE_SERVICE_ROLE_KEY. You can store a current Supabase secret key in that variable without renaming anything in the code. The value has to be a secret key or the legacy service_role key, not a publishable key.

Create .env beside package.json:

OPENAI_API_KEY=your-openai-api-key
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-server-side-secret-key
PORT=3000

Create .gitignore:

.env
node_modules/

The Git handbook covers this habit in ignoring files and good habits.

Keep the Supabase key on the server

Never rename the Supabase secret key with a VITE_ prefix or move it into client.js. That key has elevated database access. Do not commit .env or share it in a ZIP.

JunoMake Node load .env Add --env-file=.env to the start script, create .env with all four values, and keep it out of Git.

Create the .gitignore before your first commit, so the key never has a chance to reach the repository.

JunoMake Node load .env Node does not read .env on its own, so the extracted project starts with no configuration. The --env-file flag is built into Node: no extra package, and the values stay on the server where Express reads them.

JunoMake Node load .env The flag loads the four existing variable names into process.env before server.js runs. Only Express reads them, so the OpenAI and Supabase secrets never appear in code sent to the browser, and no dotenv dependency is needed.

Keep the supplied models

The downloaded constants.js uses gpt-4o for answer generation and classification and text-embedding-3-small for embeddings. Local setup does not require changing either model. Keep them unchanged unless OpenAI rejects one for your project.

If you later replace a model, test the complete agent flow. Replacing the embedding model needs extra care: a model with the same dimension count but a different vector space returns poor matches and reports no error, so regenerate the stored Supabase vectors after changing it.

JunoKeep the supplied models Leave both model names in constants.js as they are. If your OpenAI project rejects one, check the current model list before editing the code, and retest the whole agent afterward.

JunoKeep the supplied models The answer, classification, and embedding roles have different compatibility needs, so replacing a model is never a one-line change. A replacement has to work with this SDK and stay compatible with the vectors already stored in Supabase.

JunoKeep the supplied models Query embeddings are compared against the stored vectors, so both must come from the same model. A different embedding model with the same dimension count breaks retrieval silently: answers get worse and nothing errors. Changing it means regenerating the stored vectors, not only editing constants.js.

Run the agent

$ npm start

Open http://localhost:3000, or use the port you set in .env. Stop the server with Ctrl+C.

The page loading shows that the local server is running. Ask a question covered by the course data: a useful answer shows that Supabase retrieval and OpenAI generation are working too. The RAG chapter explains why the agent bases its answers on retrieved course data.

JunoRun the agent Run npm start and open the local address in your browser. The page loading proves the server runs.

A full answer also needs OpenAI and the course's Supabase data, so treat those as a second, separate check.

JunoRun the agent Treat server startup and answer generation as separate checks: a running server with failing answers points to OpenAI, Supabase, or the keys you gave them, not to the code. Stop with Ctrl+C and set PORT in .env if another process already uses port 3000.

JunoRun the agent One Express process serves the page and the API, so a loaded page proves only HTTP serving. Answers still depend on OpenAI calls and Supabase retrieval, and either can fail long after startup succeeded.

Troubleshooting

Missing OPENAI_API_KEY: Confirm that the start script includes --env-file=.env, that .env is beside package.json, and that the variable name matches exactly.

Supabase authentication or relation error: Confirm the URL and the Supabase secret key belong to the same project, then complete the course's schema and data steps. This server-side operation needs a secret key or the legacy service_role key; a publishable key, which is meant for browser code, does not have the access it requires.

Port 3000 is already in use: Change PORT in .env, restart the server, and open the new port.

The page loads but answers fail: Check the server terminal for the first provider or database error. The page loading does not prove that OpenAI or Supabase will answer.

JunoTroubleshooting A missing key points to the start script or .env, a Supabase error points to the project or its data, and a loaded page with failed answers points to an external service. Match the symptom to one of those first.

JunoTroubleshooting Read the first server-terminal error, not the last one; later failures are usually consequences of it. That first error tells environment loading, database access, port binding, and OpenAI access apart.

JunoTroubleshooting Check in order: did Node load .env, did Supabase return the course data, did OpenAI generate an answer? Never swap in a publishable key to make an error go away; that hides a missing table or policy instead of fixing it.