V3Options
Main configuration object for initializing Stagehand.
interface V3Options {
env: V3Env;
apiKey?: string;
projectId?: string;
browserbaseSessionCreateParams?: BrowserbaseSessionCreateParams;
browserbaseSessionID?: string;
keepAlive?: boolean;
localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
model?: ModelConfiguration;
llmClient?: LLMClient;
systemPrompt?: string;
logInferenceToFile?: boolean;
experimental?: boolean;
verbose?: 0 | 1 | 2;
selfHeal?: boolean;
logger?: (line: LogLine) => void;
cacheDir?: string;
domSettleTimeout?: number;
disableAPI?: boolean;
disablePino?: boolean;
}
LocalBrowserLaunchOptions
Options for launching a local Chrome browser.
interface LocalBrowserLaunchOptions {
headless?: boolean;
executablePath?: string;
args?: string[];
ignoreDefaultArgs?: boolean | string[];
userDataDir?: string;
preserveUserDataDir?: boolean;
devtools?: boolean;
port?: number;
cdpUrl?: string;
viewport?: { width: number; height: number };
deviceScaleFactor?: number;
locale?: string;
hasTouch?: boolean;
ignoreHTTPSErrors?: boolean;
downloadsPath?: string;
acceptDownloads?: boolean;
proxy?: {
server: string;
bypass?: string;
};
connectTimeoutMs?: number;
}
Run browser in headless modeDefault: true
Path to Chrome executable
Additional Chrome launch arguments
Ignore default Chrome arguments
true: Ignore all default argsstring[]: Ignore specific args
Chrome user data directory
Keep user data directory after closing
Auto-open DevTools for each tab
Connect to existing Chrome instance via CDP URL
Initial viewport size{ width: number; height: number }
{ width: 1288, height: 711 } Device pixel ratioDefault: 1
Browser locale (e.g., “en-US”)
Enable touch event support
Ignore HTTPS certificate errors
Directory for downloaded files
Proxy configuration{
server: string; // e.g., "http://proxy.example.com:8080"
bypass?: string; // e.g., "*.example.com"
}
CDP connection timeout in milliseconds
Example
const stagehand = new Stagehand({
env: "LOCAL",
localBrowserLaunchOptions: {
headless: false,
viewport: { width: 1920, height: 1080 },
deviceScaleFactor: 2,
args: [
"--disable-blink-features=AutomationControlled",
"--disable-web-security",
],
ignoreHTTPSErrors: true,
downloadsPath: "./downloads",
},
});
BrowserbaseSessionCreateParams
Options for creating a Browserbase session.
interface BrowserbaseSessionCreateParams {
projectId?: string;
extensionId?: string;
browserSettings?: {
viewport?: { width: number; height: number };
advancedStealth?: boolean;
fingerprint?: Record<string, unknown>;
};
keepAlive?: boolean;
timeout?: number;
proxies?: boolean | object[];
region?: BrowserbaseRegion;
userMetadata?: Record<string, unknown>;
}
Browserbase project ID (overrides root projectId)
Chrome extension ID to load
Browser configuration
viewport
{ width: number; height: number }
Browser viewport dimensions
Enable advanced stealth mode
Custom browser fingerprint
Keep session alive after Stagehand closes
Session timeout in seconds
Geographic region for the sessionOptions: "us-west-2" | "us-east-1" | "eu-central-1" | "ap-southeast-1"
Custom metadata for the session
Example
const stagehand = new Stagehand({
env: "BROWSERBASE",
apiKey: process.env.BROWSERBASE_API_KEY,
projectId: process.env.BROWSERBASE_PROJECT_ID,
browserbaseSessionCreateParams: {
browserSettings: {
viewport: { width: 1920, height: 1080 },
advancedStealth: true,
},
keepAlive: true,
region: "us-west-2",
},
});
ModelConfiguration
Model configuration for LLM operations.
type ModelConfiguration =
| AvailableModel
| (ClientOptions & { modelName: AvailableModel });
type AvailableModel =
| "gpt-4.1"
| "gpt-4.1-mini"
| "gpt-4o"
| "gpt-4o-mini"
| "claude-3-5-sonnet-latest"
| "claude-3-7-sonnet-latest"
| "gemini-2.0-flash"
| "gemini-2.5-flash-preview"
| string;
String Format
const stagehand = new Stagehand({
env: "LOCAL",
model: "openai/gpt-4.1-mini",
});
Object Format
const stagehand = new Stagehand({
env: "LOCAL",
model: {
modelName: "anthropic/claude-3-5-sonnet-latest",
apiKey: process.env.ANTHROPIC_API_KEY,
temperature: 0.7,
},
});
ClientOptions
LLM client configuration options.
interface ClientOptions {
apiKey?: string;
baseURL?: string;
organization?: string; // OpenAI
provider?: "openai" | "anthropic" | "google";
waitBetweenActions?: number; // Agent delay in ms
thinkingBudget?: number; // Anthropic extended thinking
environment?: string; // CUA environment type
maxImages?: number; // Microsoft FARA
temperature?: number;
}
API key for the LLM provider
Delay between agent actions in milliseconds
Token budget for Anthropic extended thinking
Environment type for CUA agents: "browser", "mac", "windows", "ubuntu"
Maximum images for Microsoft FARA agent
Model temperature (0-1 or 0-2 depending on provider)
Example
const stagehand = new Stagehand({
env: "LOCAL",
model: {
modelName: "anthropic/claude-3-5-sonnet-latest",
apiKey: process.env.ANTHROPIC_API_KEY,
temperature: 0.8,
thinkingBudget: 10000,
},
});
AgentConfig
Configuration for creating an agent.
interface AgentConfig {
systemPrompt?: string;
integrations?: (Client | string)[];
tools?: ToolSet;
model?: string | AgentModelConfig;
executionModel?: string | AgentModelConfig;
stream?: boolean;
mode?: "dom" | "hybrid" | "cua";
}