--- title: 'Configuration' description: 'How to configure Stagehand' icon: 'gear' --- ## Stagehand constructor ```javascript // Basic usage // Defaults to Browserbase; if no API key is provided, it will default to LOCAL // Default model is gpt-4o const stagehand = new Stagehand(); // Custom configuration const stagehand = new Stagehand({ env: "LOCAL", verbose: 1, enableCaching: true, logger: (logLine: LogLine) => { console.log(`[${logLine.category}] ${logLine.message}`); }, localBrowserLaunchOptions: { headless: true, // Launches the browser in headless mode. executablePath: '/path/to/chrome', // Custom path to the Chrome executable. args: ['--no-sandbox', '--disable-setuid-sandbox'], // Additional launch arguments. env: { NODE_ENV: "production" }, // Environment variables for the browser process. handleSIGHUP: true, handleSIGINT: true, handleSIGTERM: true, ignoreDefaultArgs: false, // or specify an array of arguments to ignore. proxy: { server: 'http://proxy.example.com:8080', bypass: 'localhost', username: 'user', password: 'pass' }, tracesDir: '/path/to/traces', // Directory to store trace files. userDataDir: '/path/to/user/data', // Custom user data directory. acceptDownloads: true, downloadsPath: '/path/to/downloads', extraHTTPHeaders: { 'User-Agent': 'Custom Agent' }, geolocation: { latitude: 37.7749, longitude: -122.4194, accuracy: 10 }, permissions: ["geolocation", "notifications"], locale: "en-US", viewport: { width: 1280, height: 720 }, deviceScaleFactor: 1, hasTouch: false, ignoreHTTPSErrors: true, recordVideo: { dir: '/path/to/videos', size: { width: 1280, height: 720 } }, recordHar: { path: '/path/to/har.har', mode: "full", omitContent: false, content: "embed", urlFilter: '.*' }, chromiumSandbox: true, devtools: true, bypassCSP: false, cdpUrl: 'http://localhost:9222', }, }); // Resume existing Browserbase session const stagehand = new Stagehand({ env: "BROWSERBASE", browserbaseSessionID: "existing-session-id", }); ``` This constructor is used to create an instance of Stagehand. ### **Arguments:** [`ConstructorParams`](https://github.com/browserbase/stagehand/blob/ed318846479054b6c7e3862b6c0c8aaa0bb0f42a/types/stagehand.ts#L8-L23) Defaults to `'BROWSERBASE'` Your Browserbase API key. Defaults to `BROWSERBASE_API_KEY` environment variable Your Browserbase project ID. Defaults to `BROWSERBASE_PROJECT_ID` environment variable Configuration options for creating new Browserbase sessions. More information on browserbaseSessionCreateParams can be found [here](https://docs.browserbase.com/reference/api/create-a-session#body-browser-settings). The Browserbase Project ID. The Context ID. Whether or not to persist the context after browsing. Defaults to false. The uploaded Extension ID. See [Upload Extension](https://docs.browserbase.com/reference/api/upload-an-extension). See usage examples in the [Stealth Mode page](https://docs.browserbase.com/features/stealth-mode#fingerprinting). Available options: `1`, `2` Available options: `chrome`, `edge`, `firefox`, `safari` Available options: `desktop`, `mobile` Full list of locales available [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language). Note: `operatingSystems` set to `ios` or `android` requires `devices` to include `"mobile"`. Available options: `android`, `ios`,`linux`, `macos`, `windows` Enable or disable ad blocking in the browser. Defaults to `false`. Enable or disable captcha solving in the browser. Defaults to `true`. Enable or disable session recording. Defaults to `true`. Advanced Browser Stealth Mode. The uploaded Extension ID. See [Upload Extension](https://docs.browserbase.com/reference/api/upload-an-extension). Set to true to keep the session alive even after disconnections. This is available on the Browserbase Startup plan only. Proxy configuration. Can be true for default proxy, or an array of proxy configurations. The region where the Session should run. Available options: `us-west-2`, `us-east-1`, `eu-central-1`, `ap-southeast-1` Duration in seconds after which the session will automatically end. Defaults to the Project's defaultTimeout. Required range: `60 < x < 21600` Arbitrary user metadata to attach to the session. For more information about user metadata, see [UserMetadata](https://docs.browserbase.com/features/sessions#user-metadata) userMetadata.`{key}` `any` ID of an existing Browserbase session to resume Specifying the default language model to use Configuration options for the language model client (i.e. `apiKey`) Enables caching of LLM responses. When set to `true`, the LLM requests will be cached on disk and reused for identical requests. Defaults to `false` Specifies the timeout in milliseconds for waiting for the DOM to settle. Defaults to `30_000` (30 seconds) `message` is a `LogLine` object. Handles log messages. Useful for custom logging implementations. For more information, see the [Logging](/reference/logging) page Whether Pino should be disabled for logging. This is helpful for Next.js or test environments. Pino will automatically be disabled if a custom `logger` is defined. Enables several levels of logging during automation: `0`: limited to no logging, `1`: SDK-level logging, `2`: LLM-client level logging (most granular) A custom LLM client implementation that conforms to the [`LLMClient`](https://github.com/arihanv/stagehand/blob/main/lib/llm/LLMClient.ts) abstract class A custom system prompt to use for the LLM in addition to the default system prompt for act, extract, and observe methods. Enables self-healing mode. When set to `true`, Stagehand will attempt to recover from errors (eg. outdated cached element not resolving) by retrying the last action. Defaults to `true`. Set to `false` to disable LLM inference on cache errors. Provides comprehensive options for local browser instances. Additional command-line arguments to pass to the browser. Enable or disable Chromium’s sandbox. Open the browser’s developer tools on launch. Environment variables for the browser process. Path to the browser executable. Option to handle the SIGHUP signal. Option to handle the SIGINT signal. Option to handle the SIGTERM signal. Launches the browser in headless mode. Ignore all default arguments or specify an array to ignore. Proxy server URL. Hosts to bypass the proxy. Username for proxy authentication. Password for proxy authentication. Directory to store trace files. Custom user data directory. Allow file downloads. Directory where downloads are saved. Additional HTTP headers to send with each request. Latitude coordinate. Longitude coordinate. Accuracy of the geolocation measurement. Indicates if the device has touch capabilities. Whether to ignore HTTPS errors. Sets the browser’s locale. Array of permissions to grant (e.g., "geolocation", "notifications"). File path for the HAR. Mode for HAR recording. Whether to omit content in HAR recording. Content mode for HAR recording. Filter for URLs to include in the HAR. Directory to save videos. Width of the recorded video. Height of the recorded video. Width of the viewport. Height of the viewport. Device scale factor for high-DPI displays. Timezone to emulate (e.g., "America/Los_Angeles"). Whether to bypass Content Security Policy. Array of cookies to initialize the browser session. URL for the Chrome DevTools Protocol. Useful for connecting to a running browser instance. ### **Returns:** Stagehand object The constructor returns an instance of the `Stagehand` class configured with the specified options. However, to use Stagehand, you must still initialize it with [`init()`](#init). ## `stagehand.init()` ```javascript await stagehand.init(); ``` `init()` asynchronously initializes the Stagehand instance. It should be called before any other methods. ## `stagehand.close()` ```javascript await stagehand.close(); ``` `close()` is a cleanup method to remove the temporary files created by Stagehand. It's recommended that you call this explicitly when you're done with your automation.