Stagehand

Complete API reference for initializing Stagehand

Constructor Signature

TypeScript

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  // ... other options
});
await stagehand.init();

ConstructorParams Interface:

interface ConstructorParams {
  env: "BROWSERBASE" | "LOCAL";
  apiKey?: string;
  projectId?: string;
  verbose?: 0 | 1 | 2;
  llmProvider?: LLMProvider;
  logger?: (message: LogLine) => void | Promise<void>;
  domSettleTimeoutMs?: number;
  browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & { projectId?: string };
  enableCaching?: boolean;
  browserbaseSessionID?: string;
  modelName?: AvailableModel;
  llmClient?: LLMClient;
  modelClientOptions?: ClientOptions;
  systemPrompt?: string;
  useAPI?: boolean;
  waitForCaptchaSolves?: boolean;
  localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
  logInferenceToFile?: boolean;
  selfHeal?: boolean;
  disablePino?: boolean;
  experimental?: boolean;
}

Python

from stagehand import Stagehand

stagehand = Stagehand(
    env: Literal["BROWSERBASE", "LOCAL"] = "BROWSERBASE",
    api_key: str = None,
    project_id: str = None,
    api_url: str = None,
    model_name: str = None,
    model_api_key: str = None,
    model_client_options: Dict[str, Any] = None,
    verbose: int = 1,
    logger: Callable = None,
    use_rich_logging: bool = True,
    dom_settle_timeout_ms: int = 3000,
    browserbase_session_create_params: Dict = None,
    browserbase_session_id: str = None,
    enable_caching: bool = False,
    self_heal: bool = True,
    wait_for_captcha_solves: bool = False,
    system_prompt: str = None,
    local_browser_launch_options: Dict[str, Any] = None,
    use_api: bool = True,
    experimental: bool = False,
)
await stagehand.init()

Model Configuration

Learn how to configure different LLM models for Stagehand

Parameters

Required Parameters

env · 'BROWSERBASE' | 'LOCAL' · required

The environment to use for Stagehand.

• BROWSERBASE - Run browser on Browserbase cloud infrastructure
• LOCAL - Run browser locally on your machine

Default: "BROWSERBASE" (Python only)

Browserbase Configuration

apiKey · string

Your Browserbase API key. Required when env is BROWSERBASE.

projectId · string

Your Browserbase project ID. Required when env is BROWSERBASE.

browserbaseSessionID · string

The ID of an existing Browserbase session to resume. Useful for continuing previous browser sessions.

browserbaseSessionCreateParams · object

Parameters to use when creating a Browserbase session. See Browserbase API documentation for available options.

waitForCaptchaSolves · boolean

Wait for captchas to be solved after navigation when using Browserbase environment.

Default: false

Local Browser Configuration

localBrowserLaunchOptions · LocalBrowserLaunchOptions

Configuration options for launching a local browser. Only used when env is LOCAL.

See the full interface definition for all available options.

LLM Configuration

Model Configuration

Learn how to configure different LLM models for Stagehand

modelName · AvailableModel

The LLM model to use for Stagehand operations.

Examples: gpt-4o, gpt-4o-mini, claude-sonnet-4-6

Python Default: "gpt-4o"

modelApiKey · string

API key for the LLM model provider. Python only.

In TypeScript, use modelClientOptions.apiKey instead.

llmProvider · LLMProvider

The LLM provider to use for Stagehand. Custom provider implementation. TypeScript only.

llmClient · LLMClient

Custom LLM client instance to use for Stagehand operations. TypeScript only.

modelClientOptions · ClientOptions

LLM client configuration options. Useful for parameterizing LLM API keys and other settings.

Common options: apiKey (TypeScript), api_base, temperature, maxTokens

enableCaching · boolean

Enable caching of LLM responses to reduce API calls and costs.

TypeScript Default: true Python Default: false

Logging and Debugging

Security tip: Use verbose: 0 when your automation handles secrets to prevent sensitive data from appearing in logs.

verbose · 0 | 1 | 2

The verbosity level of the Stagehand logger.

• 0 - Minimal (ERROR only)
• 1 - Medium (INFO level)
• 2 - Detailed (DEBUG level)

Default: 1

logger · (message: LogLine) => void | Promise<void>

Custom logger function to handle log messages from Stagehand.

useRichLogging · boolean

Whether to use Rich for colorized logging output. Python only.

Default: true

disablePino · boolean

Disable Pino logger. Helpful for Next.js or test environments where Pino causes issues. TypeScript only.

Default: false

logInferenceToFile · boolean

Log LLM inference details to a file for debugging purposes. TypeScript only.

Default: false

Performance and Behavior

domSettleTimeoutMs · number

Default timeout to wait for the DOM to settle before performing operations.

TypeScript Default: 10000 (10 seconds) Python Default: 3000 (3 seconds)

selfHeal · boolean

Enable self-healing capabilities to automatically recover from failures.

Python Default: true

systemPrompt · string

Customize the Stagehand system prompt used for LLM interactions.

useAPI · boolean

Offload Stagehand method calls to the Stagehand API.

Default: true

experimental · boolean

Enable the latest experimental features. Use with caution in production.

Default: false

Returns InitResult

After calling stagehand.init(), you receive an InitResult object:

debugUrl · string · required

URL for debugging the browser session (e.g., Chrome DevTools).

sessionUrl · string · required

URL of the browser session (especially useful with Browserbase).

sessionId · string · required

Unique identifier for the browser session.