Skip to main content
Version: Next

StagehandOptions

Stagehand-specific configuration options.

Index

Properties

Properties

optionalapiKey

apiKey?: string

API key - interpreted based on the env setting:

  • When env: 'LOCAL': LLM provider API key (OpenAI, Anthropic, or Google)
  • When env: 'BROWSERBASE': Browserbase API key

For LOCAL env, can also be set via environment variables:

  • OpenAI: OPENAI_API_KEY
  • Anthropic: ANTHROPIC_API_KEY
  • Google: GOOGLE_API_KEY
@example
// Local with OpenAI
stagehandOptions: {
  env: 'LOCAL',
  model: 'openai/gpt-4.1-mini',
  apiKey: 'sk-...',
}

// Browserbase cloud
stagehandOptions: {
  env: 'BROWSERBASE',
  apiKey: 'bb-...',
  projectId: 'proj-...',
}

optionalcacheDir

cacheDir?: string

Cache directory for observation caching to improve performance.

optionaldomSettleTimeout

domSettleTimeout?: number = 30000

Time to wait for DOM to stabilize before performing AI operations (ms).

optionalenv

env?: LOCAL | BROWSERBASE = LOCAL | BROWSERBASE

Environment to run Stagehand in.

  • 'LOCAL': Use local browser (default)
  • 'BROWSERBASE': Use Browserbase cloud browsers

optionalllmClient

llmClient?: LLMClient

Custom LLM client for AI operations.

optionallogInferenceToFile

logInferenceToFile?: boolean = false

Enable logging of AI inference details to file for debugging.

optionalmodel

model?: ModelConfiguration = ModelConfiguration

AI model to use for act(), extract(), observe() operations. Can be a string like "openai/gpt-4.1-mini" or a detailed ModelConfiguration object.

@example
"openai/gpt-4.1-mini"
@example
"anthropic/claude-sonnet-4-20250514"

optionalprojectId

projectId?: string

Browserbase project ID (required when env is 'BROWSERBASE').

optionalselfHeal

selfHeal?: boolean = true

Enable automatic error recovery for failed AI operations.

optionalsystemPrompt

systemPrompt?: string

Custom system prompt for AI operations.

optionalverbose

verbose?: 0 | 1 | 2 = 0 | 1 | 2

Logging verbosity level.

  • 0: Minimal logging
  • 1: Standard logging
  • 2: Debug logging
Page Options