---
title: "Project Setup"
description: "Clone the starter repo, link it to Vercel, pull environment variables, and explore the pre-built UI and demo data you'll work with throughout the course."
canonical_url: "https://vercel.com/academy/filesystem-agents/filesystem-project-setup"
md_url: "https://vercel.com/academy/filesystem-agents/filesystem-project-setup.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-04-11T09:48:28.861Z"
content_type: "lesson"
course: "filesystem-agents"
course_title: "Building Filesystem Agents"
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>

# Project Setup

# Project Setup

You're building a file system agent for analyzing call transcripts. This pattern could be extended to analyzing legal documents, coding agents, financial analysis, or SQL generation and execution.

For this project you'll use:

- **[Vercel Sandbox](https://vercel.com/docs/functions/sandbox)** - Secure, isolated environment for running untrusted code (bash commands)
- **[AI SDK](https://sdk.vercel.ai)** - Unified API for building AI applications with streaming, tools, and agents
- **[AI Gateway](https://vercel.com/ai-gateway)** - Routes requests to AI providers with automatic fallbacks, caching, and rate limiting

## Outcome

You have a linked Vercel project with environment variables pulled locally, and you understand which files are pre-built and which you'll create.

## Hands-on Exercise 1.1

Set up the starter project and verify you have everything you need to start building the agent.

**Requirements:**

1. Deploy the starter with the **Deploy with Vercel** button, then clone your fork and run `pnpm install`
2. Link your local clone to the Vercel project with `vc link`
3. Pull environment variables with `vc env pull`
4. Add your AI Gateway API key to `.env.local`

**Prerequisites:**

For this project, you'll need:

- [Node.js](https://nodejs.org/) 18+ installed
- [pnpm](https://pnpm.io/) package manager
- Vercel account
- [Vercel CLI](https://vercel.com/docs/cli)
- [AI Gateway API Key](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway%2Fapi-keys\&title=AI+Gateway+API+Keys)

### Deploy to Vercel

Click the button below to fork the starter and deploy it to Vercel:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/vercel-labs/fs-agent-course\&project-name=filesystem-agent\&repository-name=filesystem-agent)

This will:

1. **Fork the repository** to your GitHub account
2. **Create a Vercel project** linked to your fork
3. **Deploy to production** with a working landing page

Link your local repo to the Vercel project you just created:

```bash
vc link
```

Select your team and choose **Link to existing project**, then pick `filesystem-agent`.

Pull the automatically created environment variables to use locally. This handles [OIDC token authentication](https://vercel.com/docs/vercel-sandbox/concepts/authentication#vercel-oidc-token-recommended) automatically in your project.

```bash
vc env pull
```

You can now inspect the OIDC token in `.env.local` in your project.

Add your AI Gateway API Key to `.env.local`:

```
AI_GATEWAY_API_KEY=your_ai_gateway_api_key
```

### Repository Overview

The starter repo comes with all necessary files pre-created.

**Existing files:**

- `app/form.tsx` - A component that accepts a user query and sends to an API route, then renders the stream as it's returned
- `app/api/route.ts` - A route handler that calls the agent and streams back to the UI
- `lib/calls/` - A directory with pre-loaded dummy call transcripts

**Files you will edit in this course:**

- `lib/agent.ts` - Where you will define the agent
- `lib/tools.ts` - Where you will define the bash tool for the agent to use

```
app/
├── page.tsx           # Renders the Form component
├── form.tsx           # Chat input, streams responses from /api
├── api/route.ts       # POST handler that calls agent.stream()
├── layout.tsx         # Root layout
└── globals.css        # Tailwind styles

lib/
├── calls/             # Demo call transcripts (3 files)
│   ├── 1.md
│   ├── 2.md
│   └── 3.md
├── agent.ts           # Empty — you build this
└── tools.ts           # Empty — you build this
```

The API route already imports from `lib/agent.ts`, so once you build the agent, the UI will work automatically.

## Try It

1. **Verify the link worked:**
   ```bash
   cat .env.local
   ```
   You should see `VERCEL_OIDC_TOKEN` (or similar sandbox auth variables) and your `AI_GATEWAY_API_KEY`.

2. **Check the demo data:**
   ```bash
   ls lib/calls/
   ```
   ```
   1.md  2.md  3.md
   ```

3. **Peek at a transcript:**
   ```bash
   head -10 lib/calls/1.md
   ```
   You should see call metadata: ID, title, participants, and timestamps.

\*\*Note: Don't start the dev server yet\*\*

The app won't compile until `lib/agent.ts` exports an `agent`. You'll create that in the next lesson.

## Commit

```bash
git add -A
git commit -m "feat(setup): link project and pull env vars"
```

## Done-When

- [ ] `vc link` completed successfully and `.vercel/` directory exists
- [ ] `.env.local` contains OIDC auth variables and your AI Gateway API key
- [ ] You can list the three call transcript files in `lib/calls/`
- [ ] You understand which files are pre-built and which you'll create


---

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