Skip to main content

​
Constructor Signature

  • TypeScript
  • Python
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;
}

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-3-5-sonnet-20241022Python 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.