Skip to main content
skill CX Codex

vercel · vercel-labs — Claude Code skill: what it does, how to install

Emulates the Vercel REST API locally to test deployments, OAuth flows, and projects without touching real infrastructure.

Apache-2.0 220 installs ★ 2,075 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add vercel-labs/emulate --skill vercel -a claude-code
Open on GitHub

What vercel does

This skill spins up a stateful mock server matching Vercel REST API responses with cursor-based pagination. By default, the listener binds to 127.0.0.1 on port 4000, though --host 0.0.0.0 exposes it to external containers. Outbound URLs adapt when you supply --base-url.

The mock handles operations across projects, members, teams, and OAuth flows such as /login/oauth/token or /login/oauth/userinfo. You can pre-seed users, tokens, and build configurations through a YAML setup file. Deleting a project cascades down to its deployments, custom domains, and environment keys.

The agent relies on npx emulate:* and curl:* under Bash permissions to operate the emulator.

What it helps with

  • Test Vercel REST API calls locally without hitting live endpoints
  • Simulate Vercel OAuth login in Auth.js or NextAuth
  • Mock project creation with custom build settings and encrypted env vars
  • Preload test accounts, teams, and tokens using seed files

Example prompts for the agent

  • Run the local Vercel API emulator via npx emulate
  • Query http://localhost:4000/v10/projects using a test bearer token
  • Configure Auth.js OAuth URLs to point to the local Vercel emulator

How to install vercel

1Skills CLI (Vercel)

npx skills add vercel-labs/emulate --skill vercel -a claude-code

2Manually: put the files in place

~/.claude/skills/vercel/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/vercel/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about vercel

How to install vercel in Claude Code?

Run npx skills add vercel-labs/emulate --skill vercel -a claude-code in your terminal.

What does the vercel skill do?

It spins up an in-memory Vercel API service on your machine to test team management, project configurations, and OAuth logins locally.

How do you scope requests to a specific team?

Pass either teamId or slug as a query parameter in your HTTP request, alongside the Authorization: Bearer <token> header.

Source text

SKILL.md · Apache-2.0
---
name: vercel
description: Emulated Vercel REST API for local development and testing. Use when the user needs to interact with Vercel API endpoints locally, test Vercel integrations, emulate projects/deployments/domains, set up Vercel OAuth flows, manage environment variables, create API keys, configure protection bypass, emulate Vercel Blob storage, or test without hitting the real Vercel API. Triggers include "Vercel API", "emulate Vercel", "mock Vercel", "test Vercel OAuth", "Vercel integration", "Vercel Blob", "local Vercel", or any task requiring a local Vercel API.
allowed-tools: Bash(npx emulate:*), Bash(curl:*)
---

# Vercel API Emulator

Fully stateful Vercel REST API emulation with Vercel-style JSON responses and cursor-based pagination.

## Start

Local listeners bind to `127.0.0.1` by default. For access from containers or other machines, pass `--host 0.0.0.0` to the CLI or `hostname: '0.0.0.0'` to `createEmulator`. Configure `--base-url` or `baseUrl` for advertised URLs reachable by those clients.

```bash
# Vercel only
npx emulate --service vercel

# Default port
# http://localhost:4000
```

Or programmatically:

```typescript
import { createEmulator } from 'emulate'

const vercel = await createEmulator({ service: 'vercel', port: 4000 })
// vercel.url === 'http://localhost:4000'
```

## Auth

Pass tokens as `Authorization: Bearer <token>`. All endpoints accept `teamId` or `slug` query params for team scoping.

```bash
curl http://localhost:4000/v2/user \
  -H "Authorization: Bearer test_token_admin"
```

Team-scoped requests resolve the account from the `teamId` or `slug` query parameter. User-scoped requests resolve the account from the authenticated user.

## Pointing Your App at the Emulator

### Environment Variable

```bash
VERCEL_EMULATOR_URL=http://localhost:4000
```

### Vercel SDK / Custom Fetch

```typescript
const VERCEL_API = process.env.VERCEL_EMULATOR_URL ?? 'https://api.vercel.com'

const res = await fetch(`${VERCEL_API}/v10/projects`, {
  headers: { Authorization: `Bearer ${token}` },
})
```

### OAuth URL Mapping

| Real Vercel URL | Emulator URL |
|-----------------|-------------|
| `https://vercel.com/integrations/oauth/authorize` | `$VERCEL_EMULATOR_URL/oauth/authorize` |
| `https://api.vercel.com/login/oauth/token` | `$VERCEL_EMULATOR_URL/login/oauth/token` |
| `https://api.vercel.com/login/oauth/userinfo` | `$VERCEL_EMULATOR_URL/login/oauth/userinfo` |

### Auth.js / NextAuth.js

```typescript
{
  id: 'vercel',
  name: 'Vercel',
  type: 'oauth',
  authorization: {
    url: `${process.env.VERCEL_EMULATOR_URL}/oauth/authorize`,
  },
  token: {
    url: `${process.env.VERCEL_EMULATOR_URL}/login/oauth/token`,
  },
  userinfo: {
    url: `${process.env.VERCEL_EMULATOR_URL}/login/oauth/userinfo`,
  },
  clientId: process.env.VERCEL_CLIENT_ID,
  clientSecret: process.env.VERCEL_CLIENT_SECRET,
  profile(profile) {
    return {
      id: profile.sub,
      name: profile.name,
      email: profile.email,
      image: profile.picture,
    }
  },
}
```

## Seed Config

```yaml
tokens:
  test_token_admin:
    login: admin
    scopes: []

vercel:
  users:
    - username: developer
      name: Developer
      email: [email protected]
  teams:
    - slug: my-team
      name: My Team
      description: Engineering team
  projects:
    - name: my-app
      team: my-team
      framework: nextjs
      buildCommand: next build
      outputDirectory: .next
      rootDirectory: null
      nodeVersion: "20.x"
      envVars:
        - key: DATABASE_URL
          value: postgres://localhost/mydb
          type: encrypted
          target: [production, preview]
  integrations:
    - client_id: oac_abc123
      client_secret: secret_abc123
      name: My Vercel App
      redirect_uris:
        - http://localhost:3000/api/auth/callback/vercel
```

## Pagination

Cursor-based pagination using `limit`, `since`, and `until` query params. Responses include a `pagination` object:

```bash
curl "http://localhost:4000/v10/projects?limit=10" \
  -H "Authorization: Bearer $TOKEN"
```

## API Endpoints

### User & Teams

```bash
# Registration check
curl http://localhost:4000/registration

# Authenticated user
curl http://localhost:4000/v2/user -H "Authorization: Bearer $TOKEN"

# Update user
curl -X PATCH http://localhost:4000/v2/user \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Name", "email": "[email protected]"}'

# List teams (cursor paginated)
curl http://localhost:4000/v2/teams -H "Authorization: Bearer $TOKEN"

# Get team (by ID or slug)
curl http://localhost:4000/v2/teams/my-team -H "Authorization: Bearer $TOKEN"

# Create team
curl -X POST http://localhost:4000/v2/teams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "new-team", "name": "New Team"}'

# Update team (name, slug, description)
curl -X PATCH http://localhost:4000/v2/teams/my-team \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Team", "description": "New description"}'

# List members
curl http://localhost:4000/v2/teams/my-team/members -H "Authorization: Bearer $TOKEN"

# Add member (by uid or email, with role)
curl -X POST "http://localhost:4000/v2/teams/team_id/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "role": "MEMBER"}'
```

Roles: `OWNER`, `MEMBER`, `DEVELOPER`, `VIEWER`.

### Projects

```bash
# Create project (with optional env vars, git, and build config)
curl -X POST http://localhost:4000/v11/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "framework": "nextjs", "buildCommand": "next build", "outputDirectory": ".next", "nodeVersion": "20.x", "environmentVariables": [{"key": "API_KEY", "value": "secret", "type": "encrypted", "target": ["production"]}]}'

# List projects (search, cursor pagination)
curl "http://localhost:4000/v10/projects?search=my-app" \
  -H "Authorization: Bearer $TOKEN"

# Get project (includes env vars)
curl http://localhost:4000/v9/projects/my-app \
  -H "Authorization: Bearer $TOKEN"

# Update project (framework, buildCommand, devCommand, installCommand,
#   outputDirectory, rootDirectory, nodeVersion, serverlessFunctionRegion,
#   publicSource, autoAssignCustomDomains, gitForkProtection,
#   commandForIgnoringBuildStep)
curl -X PATCH http://localhost:4000/v9/projects/my-app \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"framework": "remix"}'

# Delete project (cascades deployments, domains, env vars, protection bypasses)
curl -X DELETE http://localhost:4000/v9/projects/my-app \
  -H "Authorization: Bearer $TOKEN"

# Promote aliases status
curl http://localhost:4000/v1/projects/my-app/promote/aliases \
  -H "Authorization: Bearer $TOKEN"

# Protection bypass: generate, revoke, regenerate
curl -X PATCH http://localhost:4000/v1/projects/my-app/protection-bypass \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"generate": {"note": "CI preview", "scope": "deployment"}}'

# Revoke protection bypass secrets
curl -X PATCH http://localhost:4000/v1/projects/my-app/protection-bypass \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"revoke": ["secret_to_revoke"]}'

# Regenerate protection bypass secrets
curl -X PATCH http://localhost:4000/v1/projects/my-app/protection-bypass \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"regenerate": ["old_secret"]}'
```

### Deployments

```bash
# Create deployment (auto-transitions to READY)
curl -X POST http://localhost:4000/v13/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "target": "production", "meta": {"commit": "abc123"}, "regions": ["iad1"], "gitSource": {"type": "github", "ref": "main", "sha": "abc123", "repoId": "123", "org": "my-org", "repo": "my-app", "message": "Deploy", "authorName": "dev", "commitAuthorName": "dev"}}'

# Targets: "production", "preview", "staging"

# Get deployment (by ID or URL)
curl http://localhost:4000/v13/deployments/dpl_abc123 \
  -H "Authorization: Bearer $TOKEN"

# List deployments (filter by projectId, app, target, state; cursor paginated)
curl "http://localhost:4000/v6/deployments?projectId=my-app&target=production&limit=10" \
  -H "Authorization: Bearer $TOKEN"

# List deployments (filter by commit SHA)
curl "http://localhost:4000/v7/deployments?sha=abc123" \
  -H "Authorization: Bearer $TOKEN"

# Delete deployment
curl -X DELETE http://localhost:4000/v13/deployments/dpl_abc123 \
  -H "Authorization: Bearer $TOKEN"

# Cancel building deployment
curl -X PATCH http://localhost:4000/v12/deployments/dpl_abc123/cancel \
  -H "Authorization: Bearer $TOKEN"

# List deployment aliases
curl http://localhost:4000/v2/deployments/dpl_abc123/aliases \
  -H "Authorization: Bearer $TOKEN"

# Get build events/logs (supports direction, limit)
curl "http://localhost:4000/v3/deployments/dpl_abc123/events?direction=forward&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# List deployment files
curl http://localhost:4000/v6/deployments/dpl_abc123/files \
  -H "Authorization: Bearer $TOKEN"

# Upload file (by SHA digest)
curl -X POST http://localhost:4000/v2/files \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "x-vercel-digest: sha256hash" \
  --data-binary @file.txt
```

### Domains

```bash
# Add domain (with optional redirect, gitBranch, customEnvironmentId)
curl -X POST http://localhost:4000/v10/projects/my-app/domains \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com", "redirect": null, "redirectStatusCode": null, "gitBranch": null}'

# *.vercel.app domains are auto-verified

# List domains (cursor paginated)
curl http://localhost:4000/v9/projects/my-app/domains \
  -H "Authorization: Bearer $TOKEN"

# Get, update, remove domain
curl http://localhost:4000/v9/projects/my-app/domains/example.com \
  -H "Authorization: Bearer $TOKEN"

# Verify domain
curl -X POST http://localhost:4000/v9/projects/my-app/domains/example.com/verify \
  -H "Authorization: Bearer $TOKEN"
```

Redirect status codes: `301`, `302`, `307`, `308`.

### Environment Variables

```bash
# List env vars (with decrypt option; filter by gitBranch, customEnvironmentId)
curl "http://localhost:4000/v10/projects/my-app/env?decrypt=true" \
  -H "Authorization: Bearer $TOKEN"

# Create env vars (single, batch, or upsert)
curl -X POST "http://localhost:4000/v10/projects/my-app/env?upsert=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_KEY", "value": "secret123", "type": "encrypted", "target": ["production", "preview"], "comment": "API key for service"}'

# Get env var
curl http://localhost:4000/v10/projects/my-app/env/env_abc123 \
  -H "Authorization: Bearer $TOKEN"

# Update env var
curl -X PATCH http://localhost:4000/v9/projects/my-app/env/env_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "newsecret"}'

# Delete env var
curl -X DELETE http://localhost:4000/v9/projects/my-app/env/env_abc123 \
  -H "Authorization: Bearer $TOKEN"
```

Env var types: `system`, `encrypted`, `plain`, `secret`, `sensitive`.

### Blob

Implements the Vercel Blob API used by the `@vercel/blob` SDK (`put`, `head`, `list`, `del`). Point the SDK at the emulator with two environment variables:

```bash
VERCEL_BLOB_API_URL=http://localhost:4000/api/blob
BLOB_READ_WRITE_TOKEN=vercel_blob_rw_mystore_secret
```

Any token of the form `vercel_blob_rw_<storeId>_<secret>` is accepted; the store id is parsed from the token.

```typescript
import { put, head, list, del } from '@vercel/blob'

const blob = await put('avatars/user.png', data, { access: 'public' })
// blob.url serves the bytes from the emulator
await head(blob.url)
await list({ prefix: 'avatars/' })
await del(blob.url)
```

Direct HTTP:

```bash
BLOB_TOKEN="vercel_blob_rw_mystore_secret"

# Upload (honors x-add-random-suffix, x-allow-overwrite, x-content-type,
#   x-cache-control-max-age, x-if-match headers)
curl -X PUT "http://localhost:4000/api/blob?pathname=docs/readme.txt" \
  -H "Authorization: Bearer $BLOB_TOKEN" \
  --data-binary @readme.txt

# Copy (x-if-match is compared with the source blob's ETag;
#   an existing destination is always replaced)
curl -X PUT "http://localhost:4000/api/blob?pathname=docs/copy.txt&fromUrl=docs/readme.txt" \
  -H "Authorization: Bearer $BLOB_TOKEN"

# Metadata (head)
curl "http://localhost:4000/api/blob?url=docs/readme.txt" \
  -H "Authorization: Bearer $BLOB_TOKEN"

# List (prefix, limit, cursor, mode=folded; folded pages share one
#   sorted cursor across folders and root blobs)
curl "http://localhost:4000/api/blob?prefix=docs/" \
  -H "Authorization: Bearer $BLOB_TOKEN"

# Delete
curl -X POST http://localhost:4000/api/blob/delete \
  -H "Authorization: Bearer $BLOB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["docs/readme.txt"]}'

# Start a multipart upload (returns { key, uploadId })
curl -X POST "http://localhost:4000/api/blob/mpu?pathname=docs/large.bin" \
  -H "Authorization: Bearer $BLOB_TOKEN" \
  -H "x-mpu-action: create"

# Serve content (public, no auth; ?download=1 forces attachment)
curl http://localhost:4000/blob/mystore/docs/readme.txt
```

Upload and deletion rules:

- A single leading slash is removed from the pathname, so `/docs/readme.txt` is stored as `docs/readme.txt`. As in the real service, `//` is otherwise accepted over HTTP, so `//a.txt` is stored as `/a.txt` (the `@vercel/blob` SDK rejects `//` before sending a request). This also applies to copy destinations and multipart uploads.
- The content type is taken from `x-content-type`, then the pathname extension when it is a known type, then the request `Content-Type` header, then `application/octet-stream`.
- `x-cache-control-max-age` has a minimum of 60 seconds (`0` is stored as `public, max-age=60`). Absent or invalid values default to 30 days.
- Deleting with a missing or empty `urls` array returns 400 `Missing urls in request body`. Malformed JSON returns 400 `Cannot delete more than 1,000 urls at once or body is malformed`, more than 1,000 urls returns 400 `Cannot delete more than 1,000 urls at once`, and any non-string entry returns 400 `Some urls are malformed`. Nothing is deleted in any of these cases.

Multipart uploads can be created, but uploading parts and completing the upload are not supported yet and return 400. Client (browser) uploads are not supported yet.

### API Keys

```bash
# Create API key (optional teamId scope)
curl -X POST "http://localhost:4000/v1/api-keys?teamId=team_abc123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Deploy Key"}'

# List API keys (optional teamId filter)
curl "http://localhost:4000/v1/api-keys?teamId=team_abc123" \
  -H "Authorization: Bearer $TOKEN"

# Delete API key
curl -X DELETE http://localhost:4000/v1/api-keys/ak_abc123 \
  -H "Authorization: Bearer $TOKEN"
```

Created API keys are automatically registered in the token map and can be used as Bearer tokens for all endpoints.

### OAuth / Integrations

```bash
# Authorize (browser flow, shows user picker)
# GET /oauth/authorize?client_id=...&redirect_uri=...&scope=...&state=...

# Token exchange (supports PKCE; accepts JSON or form-urlencoded)
curl -X POST http://localhost:4000/login/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id": "oac_abc123", "client_secret": "secret_abc123", "code": "<code>", "redirect_uri": "http://localhost:3000/api/auth/callback/vercel"}'

# User info (returns sub, email, email_verified, name, preferred_username, picture)
curl http://localhost:4000/login/oauth/userinfo \
  -H "Authorization: Bearer $TOKEN"
```

## Common Patterns

### Create Project and Deploy

```bash
TOKEN="test_token_admin"
BASE="http://localhost:4000"

# Create project
curl -X POST $BASE/v11/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "framework": "nextjs"}'

# Add env var
curl -X POST $BASE/v10/projects/my-app/env \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "DATABASE_URL", "value": "postgres://...", "type": "encrypted", "target": ["production"]}'

# Create deployment
curl -X POST $BASE/v13/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "target": "production"}'
```

### OAuth Integration Flow

1. Redirect user to `$VERCEL_EMULATOR_URL/oauth/authorize?client_id=...&redirect_uri=...&state=...`
2. User picks a seeded user on the emulator's UI
3. Emulator redirects back with `?code=...&state=...`
4. Exchange code for token via `POST /login/oauth/token`
5. Fetch user info via `GET /login/oauth/userinfo`

PKCE is supported. Pass `code_challenge` and `code_challenge_method` on authorize, then `code_verifier` on token exchange.

### Team-Scoped Requests

All endpoints accept `teamId` or `slug` query params:

```bash
curl "http://localhost:4000/v10/projects?teamId=team_abc123" \
  -H "Authorization: Bearer $TOKEN"

curl "http://localhost:4000/v10/projects?slug=my-team" \
  -H "Authorization: Bearer $TOKEN"
```

## Custom emulators alongside built-ins

Use `npx emulate init --custom inventory` to scaffold a third-party API emulator and test. Register it in `emulate.config.ts` with `defineConfig` from `emulate`, alongside built-in entries such as `{ emulator: "vercel" }`. Run `npx emulate start --watch` to reload imports and inspect custom state at the printed `/_emulate` URL. Successful reloads reset the run to seed. Existing flat seed configs still work; `--config` selects an explicit file. For authoring and testing third-party API emulators, see https://emulate.dev/docs/custom-emulators.

© vercel-labs · Apache-2.0 · vercel-labs/emulate

Similar skills

All skills for Backend and APIs →

vercel by other authors comes first.

vercel membrane Skill for working with Vercel through Membrane: create projects, manage deployments, environment variables, and domains directly from your agent. Requires a Membrane account (free tier supported). CX Codex +1 258installs vercel acedatacloud Inspects Vercel projects, streams build logs, and monitors deployment statuses via the Vercel REST API directly from your coding assistant. CX Codex +1 176installs vercel hoodini This skill guides Vercel project configuration and deployment, including Next.js apps and serverless or edge functions. Use it when a project needs deployment settings or Vercel integrations. CX Codex +1 ★ 301repo stars vercel-labs-emulate reason-machines vercel-labs-emulate spins up local HTTP servers that stand in for Vercel, GitHub and Google APIs. Useful when CI or a sandbox has no network but tests still need real state. CX Codex +1 925installs vercel-api official Vercel Labs vercel-api connects Codex to Vercel via OAuth and REST API. It helps inspect deployments, fetch build logs, and manage project environment variables directly. CX Codex GP ChatGPT +1 5installs sign-in-with-vercel official Vercel Labs sign-in-with-vercel walks your agent through adding user login with a Vercel account over OAuth 2.0 and OpenID Connect. Useful when you hand passwords and sessions to an identity provider. CX Codex GP ChatGPT +1 4installs crontap-replace-vercel-cron Crontap crontap-replace-vercel-cron moves a Vercel Cron schedule to Crontap while keeping the deployed HTTP route, timezone intent, and rollback plan. Use it for external scheduling. CX Codex +1 1,300installs vercel-edge-function davila7 Generate a TypeScript starter for a Vercel Edge Function, with request handlers and examples for geolocation or JWT checks. Use it when adding an edge API route to a Next.js project. CX Codex +1 364installs api-testing kindlmann The api-testing Claude Code skill helps write REST and GraphQL API tests. It comes into play for schema, auth, error, and pagination checks. CX Codex +1 1,800installs

From the same set12

The whole set →

Project sponsors

Companies that keep this analytics open