---
title: "AI SDK Dev Setup"
description: "Set up your local dev environment for the Vercel AI SDK: clone repo, install dependencies (pnpm), configure OpenAI API key (.env), and verify setup."
canonical_url: "https://vercel.com/academy/ai-sdk/ai-sdk-dev-setup"
md_url: "https://vercel.com/academy/ai-sdk/ai-sdk-dev-setup.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-04-10T17:11:30.774Z"
content_type: "lesson"
course: "ai-sdk"
course_title: "Builders Guide to the AI SDK"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# AI SDK Dev Setup

# Project Setup - Get Your Hands Dirty!

You've grasped some of the core LLM concepts. Now for the exciting part: setting up your local development environment and getting hands-on with the Vercel AI SDK. This is where you *really* get your hands dirty and prepare to build the cool AI features we've been talking about, like automatic summarization and building intelligent chatbots.

You will get the starter project running locally, securely configure the Vercel AI Gateway, and confirm everything works so you're ready to start coding AI in the next lesson.

Let's go!

\*\*Note: Prerequisites Check\*\*

Before starting, ensure you have Git, Node.js (v20+), and pnpm installed. If you missed any, check the prerequisites section at the beginning of the course for installation links.

## Step 1: Getting the Code

First, grab the [starter project code](https://github.com/vercel/ai-sdk-fundamentals-starter). This repository contains all the files and setup needed for the course. Open your terminal (or command prompt) and run this command to clone it:

```bash
git clone https://github.com/vercel/ai-sdk-fundamentals-starter.git
```

This copies the project files to your computer.

## Step 2: Navigating Into the Project

Now, move into the project directory you just cloned. Use the `cd` (change directory) command:

```bash
cd ai-sdk-fundamentals-starter
```

Your terminal prompt should now show you're inside the `ai-sdk-fundamentals-starter` folder.

## Step 3: Installing Dependencies

Next, install the necessary libraries (AI SDK, Next.js, etc.). This project uses `pnpm` for fast and efficient package management. Run:

```bash
pnpm install
```

\*\*Note: Using npm or Yarn?\*\*

While `pnpm` is recommended for this project (due to the lockfile), you can
*try* using `npm install` or `yarn install`. Be aware you might encounter
slight differences if dependency versions vary. To install pnpm globally, run:
`npm install -g pnpm`.

This might take a minute or two.

## Step 4: Setting Up the Vercel AI Gateway

AI models are accessed through API endpoints and typically this means you need to setup individual accounts and secure API keys for each provider. The [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) simplifies this and allows you to access models from multiple providers through a single endpoint.

\*\*Note: Why Use AI Gateway?\*\*

- **Free $5 credit:** Get started without needing an OpenAI account or dealing with their credit requirements
- **One endpoint, multiple providers:** Switch between OpenAI, Anthropic, Google, and others without code changes
- **Automatic failover:** If one provider fails, requests automatically retry with another
- **Cost tracking:** Monitor spending across all providers in one place
- **Rate limit handling:** Built-in retry logic and request queuing
- **Bring your own keys:** Use your existing provider API keys if needed

You have two options for authentication with the AI Gateway:

\*\*Option A: OIDC Token Setup (Recommended for Projects Already Deployed to Vercel)\*\*

This method uses secure OIDC federation and is ideal for projects deployed to Vercel.

**1. Install the Vercel CLI**

Install the Vercel CLI globally:

```bash
pnpm install -g vercel
```

This will allow you to use the `vc` command in your terminal and manage your Vercel projects.

**2. Deploy your Project**

Deploying your project will both create and deploy your project to Vercel:

```bash
vc deploy
```

Note that if you have an existing project already deployed to Vercel, you can use the `vc link` command to link your project.

**3. Enable OIDC and Get your Token**

Once your project is deployed, enable OIDC in your project settings:

1. Visit your project in the Vercel dashboard
2. Navigate to **Settings → Security**
3. Enable **"Secure Backend Access with OIDC Federation"**

Then get your token by running:

```bash
vc env pull
```

Check `.env.local` to see your OIDC token:

```bash
cat .env.local
```

\*\*Note: OIDC Token Expiration\*\*

OIDC tokens are only valid for 12 hours. You have two options:

- **Manual refresh:** Run `vc env pull` again to get a new token
- **Automatic refresh:** Use `vc dev` to run your application locally - it automatically refreshes the OIDC token when it runs

\*\*Option B: API Key Setup (Simpler for Local Development)\*\*

If you prefer using a persistent API key instead of OIDC tokens, you can create one directly in the Vercel dashboard:

**1. Create an API Key**

1. Go to your [Vercel dashboard](https://vercel.com/dashboard)
2. Navigate to the **AI Gateway** tab
3. Click **"API keys"** in the sidebar
4. Click **"Create key"** and follow the dialog
5. Copy your new API key

**2. Configure your Environment**

Create or update your `.env.local` file:

```bash
# For API key setup
AI_GATEWAY_API_KEY=your-api-key-here
```

\*\*Note: Which method should I use?\*\*

- **OIDC (Option A):** Best for production deployments and team projects. More secure but requires token refresh.
- **API Key (Option B):** Simpler for local development and learning. Persistent but requires careful key management.

For this course, either method works fine!

## Step 5: Making Sure It Works!

Let's verify your setup. The project has a simple script (env-check.ts) to confirm your authentication is configured correctly. Run it:

```bash
pnpm tsx env-check.ts
```

You should see this in your terminal:

**If using OIDC (Option A):**

```bash
🔍 Checking environment configuration...

✅ VERCEL_OIDC_TOKEN found - Vercel AI Gateway with OIDC auth
   Token preview: xxxxxxxxxxxxxxxxxxxxxxxx...
❌ AI_GATEWAY_API_KEY not found

📋 Summary:
✅ Environment is configured correctly!
   Using: Vercel AI Gateway (OIDC authentication)
   Note: OIDC tokens expire after 12 hours. Use 'vercel dev' for auto-refresh.
```

**If using API Key (Option B):**

```bash
🔍 Checking environment configuration...

❌ VERCEL_OIDC_TOKEN not found
✅ AI_GATEWAY_API_KEY found - Vercel AI Gateway with API key auth
   Key preview: xxxxxxxxxxxxxxxxxxxxxxxx...

📋 Summary:
✅ Environment is configured correctly!
   Using: Vercel AI Gateway (API key authentication)
```

\*\*Note: Token/Key Management\*\*

- **OIDC tokens:** Need refreshing every 12 hours. Run `vc env pull` again or use `vc dev` for automatic refresh
- **API keys:** Persistent and don't expire, but keep them secure and rotate periodically for best security practices

## Setup Checklist

- [ ] Project repository cloned and dependencies installed?

- [ ] .env.local file created and API key configured?

- [ ] env-check.ts ran successfully and showed your key?

- [ ] Ready to start building AI features?

## Common Setup Issues & Troubleshooting

\*\*Stuck? Click here for common solutions\*\*

- If you get an error about the git command not found, install Git. See the official [Git installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
- If you get an error about the pnpm command not found, install pnpm globally. See the official [pnpm installation guide](https://pnpm.io/installation).
- If you get an error about the Node.js version, install Node.js. See the official [Node.js installation guide](https://nodejs.org/en/download/package-manager).
- `env-check.ts` shows `undefined` or errors: Check your `.env.local` file name (leading dot, no extra extensions). For OIDC, the key name must be `VERCEL_OIDC_TOKEN`. For API Key, it must be `AI_GATEWAY_API_KEY`. Ensure you're running the command from the root of the `ai-sdk-fundamentals-starter` directory.
- Other install errors ("module not found", etc.): Delete `node_modules` and `pnpm-lock.yaml`, then run `pnpm install` again. If issues persist, check your Node.js and pnpm versions or seek help.

## Next Up: Your First AI Script

Congratulations! Your development environment is set up and ready.

Now you'll write and run code that uses the AI SDK to interact with an LLM and perform a practical task: extracting structured data from text. Time to start building.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)