Deploying Stagehand

🌟 Preview: Browser Functions - Deploy your web automation code directly on Browserbase with browser functions. Scale your act() automations in the cloud with zero infrastructure setup. Reach out to hello@browserbase.com to get beta access.

Deploy on Vercel

Securely run Stagehand on Browserbase inside a Vercel Function. This guide shows a minimal, production-safe HTTP endpoint you can call directly or on a schedule.

1. Install Vercel CLI

To download and install Vercel CLI, run one of the following commands:

pnpm i -g vercel

yarn global add vercel

npm i -g vercel

bun add -g vercel

2. Project layout

your-project/
  api/
    run.ts
  package.json
  tsconfig.json
  vercel.json

Create the structure with:

mkdir -p api
touch api/run.ts package.json vercel.json tsconfig.json

3. `api/run.ts` (Node.js runtime)

// api/run.ts
import type { VercelRequest, VercelResponse } from "@vercel/node";
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

export default async function handler(req: VercelRequest, res: VercelResponse): Promise<void> {
  try {
    const stagehand = new Stagehand({
      env: "BROWSERBASE",
      apiKey: process.env.BROWSERBASE_API_KEY!,
      disablePino: true,
      model: "google/gemini-2.5-flash",
      // optional session params
      browserbaseSessionCreateParams: {
        region: "us-west-2",
        browserSettings: {
          blockAds: true,
        },
      },
    });

    await stagehand.init();
    const page = stagehand.context.pages()[0];

    await page.goto("https://www.stagehand.dev/");
    await stagehand.act("click the evals button");

    const fastestModel = await stagehand.extract("extract the fastest model", z.string());

    await stagehand.close();

    res.status(200).json({ ok: true, data: fastestModel });
  } catch (err: unknown) {
    const msg = err instanceof Error ? err.message : String(err);
    res.status(500).json({ ok: false, error: msg });
  }
}

4. `package.json`

{
    "name": "bb-stagehand-on-vercel",
    "private": true,
    "type": "module",
    "engines": { "node": ">=18" },
    "dependencies": {
      "@browserbasehq/stagehand": "^3.0.0"
    },
    "devDependencies": {
      "@types/node": "^20.12.12",
      "@vercel/node": "^3.2.20",
      "typescript": "^5.2.2"
    }
}

5. `tsconfig.json`

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "node",
    "outDir": ".vercel/output/functions",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["api/**/*.ts"]
}

6. `vercel.json`

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "functions": {
    "api/run.ts": {
      "maxDuration": 60
    }
  }
}

See Vercel’s configuring functions docs for more details.

7. Link your project

Link your local folder to a Vercel project before configuring environment variables:

# authenticate if needed
vercel login

# link the current directory to a Vercel project (interactive)
vercel link

8. Environment variables

Do not commit .env in production. Add variables via Vercel CLI:

vercel env add BROWSERBASE_API_KEY
# (and your model key if needed)
vercel env add GOOGLE_API_KEY

See also: Browser Environment for details on required variables.

9. Test locally

Replicate the Vercel environment locally to exercise your Function before deploying. Run from the project root.

# ensure dependencies are installed
npm install

# start the local Vercel dev server
vercel dev --listen 5005

10. Deploy

vercel
vercel --prod

Execute the function

Configure Protection Bypass for Automation

Before invoking the production URL, create a Protection Bypass for Automation:

Generate a 32-character secret (you can use openssl rand -hex 16)
Go to your project in Vercel
Navigate to Settings → Deployment Protection
Add the secret to “Protection Bypass for Automation”

Then invoke the function with the bypass header:

curl -X POST \
  -H "x-vercel-protection-bypass: <your-32-character-secret>" \
  https://<your-deployment>/api/run

Optional: Cron on Vercel

Hit the same endpoint on a schedule by extending vercel.json:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "functions": {
    "api/run.ts": {
      "maxDuration": 60
    }
  }
  },
  "crons": [
    { "path": "/api/run", "schedule": "0 * * * *" }
  ]
}

Features

No local browsers needed with env: "BROWSERBASE". Browserbase provides the browsers.
Fast functionality: Offload browser work to Browserbase and return JSON promptly.
Long-running tasks: Raise maxDuration and/or consider Edge runtime limits depending on plan.

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Migration Guides

Deploying Stagehand

Deploy on Vercel

1. Install Vercel CLI

2. Project layout

3. `api/run.ts` (Node.js runtime)

4. `package.json`

5. `tsconfig.json`

6. `vercel.json`

7. Link your project

8. Environment variables

9. Test locally

10. Deploy

Execute the function

Configure Protection Bypass for Automation

Optional: Cron on Vercel

Features

​Deploy on Vercel

​1. Install Vercel CLI

​2. Project layout

​3. api/run.ts (Node.js runtime)

​4. package.json

​5. tsconfig.json

​6. vercel.json

​7. Link your project

​8. Environment variables

​9. Test locally

​10. Deploy

​Execute the function

​Configure Protection Bypass for Automation

​Optional: Cron on Vercel

​Features

Deploy on Vercel

1. Install Vercel CLI

2. Project layout

3. `api/run.ts` (Node.js runtime)

4. `package.json`

5. `tsconfig.json`

6. `vercel.json`

7. Link your project

8. Environment variables

9. Test locally

10. Deploy

Execute the function

Configure Protection Bypass for Automation

Optional: Cron on Vercel

Features