--- title: 'Stagehand' description: 'Complete API reference for initializing Stagehand' icon: 'wand-magic-sparkles' --- ### Constructor Signature ```typescript import { Stagehand } from "@browserbasehq/stagehand"; const stagehand = new Stagehand({ env: "BROWSERBASE", // ... other options }); await stagehand.init(); ``` **ConstructorParams Interface:** ```typescript interface ConstructorParams { env: "BROWSERBASE" | "LOCAL"; apiKey?: string; projectId?: string; verbose?: 0 | 1 | 2; llmProvider?: LLMProvider; logger?: (message: LogLine) => void | Promise; domSettleTimeoutMs?: number; browserbaseSessionCreateParams?: Omit & { 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() ``` Learn how to configure different LLM models for Stagehand ### Parameters #### Required Parameters 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 Your Browserbase API key. Required when `env` is `BROWSERBASE`. Your Browserbase project ID. Required when `env` is `BROWSERBASE`. The ID of an existing Browserbase session to resume. Useful for continuing previous browser sessions. Parameters to use when creating a Browserbase session. See [Browserbase API documentation](https://docs.browserbase.com/reference/api/create-a-session) for available options. Wait for captchas to be solved after navigation when using Browserbase environment. **Default:** `false` #### Local Browser Configuration Configuration options for launching a local browser. Only used when `env` is `LOCAL`. See the [full interface definition](https://github.com/browserbase/stagehand/blob/v2/types/stagehand.ts#L174) for all available options. #### LLM Configuration Learn how to configure different LLM models for Stagehand The LLM model to use for Stagehand operations. **Examples:** `gpt-4o`, `gpt-4o-mini`, `claude-sonnet-4-6` **Python Default:** `"gpt-4o"` API key for the LLM model provider. **Python only.** In TypeScript, use `modelClientOptions.apiKey` instead. The LLM provider to use for Stagehand. Custom provider implementation. **TypeScript only.** Custom LLM client instance to use for Stagehand operations. **TypeScript only.** LLM client configuration options. Useful for parameterizing LLM API keys and other settings. **Common options:** `apiKey` (TypeScript), `api_base`, `temperature`, `maxTokens` 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. The verbosity level of the Stagehand logger. - `0` - Minimal (ERROR only) - `1` - Medium (INFO level) - `2` - Detailed (DEBUG level) **Default:** `1` Custom logger function to handle log messages from Stagehand. Whether to use Rich for colorized logging output. **Python only.** **Default:** `true` Disable Pino logger. Helpful for Next.js or test environments where Pino causes issues. **TypeScript only.** **Default:** `false` Log LLM inference details to a file for debugging purposes. **TypeScript only.** **Default:** `false` #### Performance and Behavior Default timeout to wait for the DOM to settle before performing operations. **TypeScript Default:** `10000` (10 seconds) **Python Default:** `3000` (3 seconds) Enable self-healing capabilities to automatically recover from failures. **Python Default:** `true` Customize the Stagehand system prompt used for LLM interactions. Offload Stagehand method calls to the Stagehand API. **Default:** `true` Enable the latest experimental features. Use with caution in production. **Default:** `false` ### Returns `InitResult` After calling `stagehand.init()`, you receive an `InitResult` object: URL for debugging the browser session (e.g., Chrome DevTools). URL of the browser session (especially useful with Browserbase). Unique identifier for the browser session.