Quickstart

This tutorial deploys a Stagehand script as a Function, gives it your API key through a Secret, then invokes it through the Browserbase API.

Functions are currently only available in the us-west-2 region.

Prerequisites

You need:

A Browserbase account
A Browserbase API key from Settings
Node.js and pnpm 10 or later
The browse CLI:

npm install -g browse

Create a Functions project

Initialize the project

Create the project:

browse functions init my-functions-project
cd my-functions-project

The initializer installs Stagehand and creates package.json, tsconfig.json, .env, and a starter index.ts.

Add your credentials

Export your Browserbase API key from Settings in the terminal where you run the development server:

export BROWSERBASE_API_KEY=your_api_key

Browserbase resolves the project from the API key. You don’t need a Project ID. You also don’t need a model API key, because Stagehand sends model calls through the Browserbase Model Gateway. Deployed Functions read the API key from a Secret instead.

Add the Stagehand extension

Stagehand needs its extension in the browser session. Upload the extension to your project:

browse cloud extensions upload node_modules/@browserbasehq/stagehand/dist/assets/stagehand-extension.zip

Copy the id from the output. The Function uses it in the next step. If you use Playwright, skip this step.

Define the Function

Replace index.ts with a Function that returns the title of a page. For Stagehand, replace your-extension-id with the id from the previous step:

Stagehand
Playwright

Node.js

import { defineFn } from "@browserbasehq/sdk-functions";
import { browserbase, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

defineFn(
  "page-title",
  async (context, params) => {
    const browser = await browserbase.connect({
      // The local dev server has no Secrets, so fall back to .env.
      apiKey: context.secrets.BROWSERBASE_API_KEY ?? process.env.BROWSERBASE_API_KEY!,
      sessionId: context.session.id,
    });
    // In this example, Stagehand uses the Model Gateway where Browserbase charges for the tokens
    const stagehand = await Stagehand.create({ browser });
    const page = (await browser.context.activePage())!;

    await page.goto(params.url);
    const { data } = await stagehand.extract(
      "Extract the page title",
      z.object({ title: z.string() }),
    );

    await stagehand.close();
    return { title: data.title };
  },
  {
    parametersSchema: z.object({
      url: z.string().url(),
    }),
    sessionConfig: { extensionId: "your-extension-id" },
  },
);

Node.js

import { defineFn } from "@browserbasehq/sdk-functions";
import { chromium } from "playwright-core";
import { z } from "zod";

defineFn(
  "page-title",
  async (context, params) => {
    const browser = await chromium.connectOverCDP(
      context.session.connectUrl,
    );
    const page = browser.contexts()[0]!.pages()[0]!;

    await page.goto(params.url);

    return { title: await page.title() };
  },
  {
    parametersSchema: z.object({
      url: z.string().url(),
    }),
  },
);

The initializer creates a pnpm-workspace.yaml file in the project directory. It holds the pnpm setting that approves the esbuild build script, which pnpm 11 and later require.

Test the Function locally

Start the development server

Run:

browse functions dev index.ts

The server listens on http://127.0.0.1:14113 and reloads when you change the Function files.

Invoke the local Function

In another terminal, invoke the Function by the name passed to defineFn:

curl --request POST \
  --url http://127.0.0.1:14113/v1/functions/page-title/invoke \
  --header 'Content-Type: application/json' \
  --data '{"params":{"url":"https://example.com"}}'

The local server runs the handler synchronously. The response contains:

{
  "title": "Example Domain"
}

Publish the Function

Publish the entrypoint:

browse functions publish index.ts

The command builds each Function reachable from index.ts and prints the Function IDs. Save the ID for page-title from builtFunctions[].id. See Deploy Functions for multi-file projects.

Add the Secret

The Stagehand version reads your Browserbase API key from a Secret. If you use Playwright, skip this section. Create a project Secret for your Browserbase API key. The --env flag reads the value from your shell environment, so export the key first:

export BROWSERBASE_API_KEY=your_api_key
browse cloud secrets create BROWSERBASE_API_KEY --env BROWSERBASE_API_KEY

Attach the Secret to the Function with the Function ID and the id of the Secret:

browse functions secrets attach FUNCTION_ID SECRET_ID
browse functions secrets list FUNCTION_ID

The list output must show the Secret. If the build fails, open the build in the Browserbase dashboard to see the build logs. The logs show the install and build errors.

Invoke the deployed Function

Production invocations run asynchronously. Start an invocation with the Function ID:

curl --request POST \
  --url https://api.browserbase.com/v1/functions/FUNCTION_ID/invoke \
  --header 'Content-Type: application/json' \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY" \
  --data '{"params":{"url":"https://example.com"}}'

The API returns 202 Accepted with an invocation object. Copy its id, then poll the invocation:

curl --request GET \
  --url https://api.browserbase.com/v1/functions/invocations/INVOCATION_ID \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"

When status is COMPLETED, results contains the value returned by the handler.

Next steps

Write a Function

Configure parameters, browser sessions, and multiple Functions.

Deploy Functions

Publish from the CLI or the Playground.

Invoke a Function

Override session settings and handle asynchronous results.

Welcome

Platform

Use cases

Optimization

Account

Prerequisites

Create a Functions project

Test the Function locally

Publish the Function

Add the Secret

Invoke the deployed Function

Next steps

Write a Function

Deploy Functions

Invoke a Function

​Prerequisites

​Create a Functions project

​Test the Function locally

​Publish the Function

​Add the Secret

​Invoke the deployed Function

​Next steps

Write a Function

Deploy Functions

Invoke a Function

Prerequisites

Create a Functions project

Test the Function locally

Publish the Function

Add the Secret

Invoke the deployed Function

Next steps