Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/l-xiaoshen/handstage/llms.txt

Use this file to discover all available pages before exploring further.

Handstage exposes a layered option system. HandstagesSharedOptions applies to every connection mode. HandstagesLocalOptions and HandstagesConnectOptions extend it with mode-specific fields. LocalBrowserLaunchOptions contains the full set of flags forwarded to the Chrome launcher.

​
HandstagesSharedOptions

Applies to all three connection modes: connectLocal, connectTransport, and connectSession.
​
sessionId
string
Optional external session identifier used to correlate logs and traces with your own tracking system. When omitted, Handstage generates an internal UUID.
​
keepAlive
boolean
When true, the browser process is not killed when close() is called and SIGINT handling is relaxed so the parent process can exit while Chrome keeps running. Useful for long-lived or reusable browser instances.
​
verbose
LogLevel
default:"LogLevel.Info"
Minimum log level to emit. LogLevel.Error is quietest (errors only), LogLevel.Info adds informational messages, and LogLevel.Debug emits everything. See Error types and error handling for enum values.
​
logger
(line: LogLine) => void
Custom log sink. When omitted, Handstage uses a default console logger. The function receives every LogLine that passes the verbose threshold.

​
HandstagesLocalOptions

Passed to V3.connectLocal(). Extends HandstagesSharedOptions.
​
localBrowserLaunchOptions
LocalBrowserLaunchOptions
Full set of Chrome launch and connection flags. See LocalBrowserLaunchOptions below.

​
HandstagesConnectOptions

Passed to V3.connectTransport() and V3.connectSession(). Extends HandstagesSharedOptions.
​
viewport
{ width: number; height: number }
Viewport dimensions to apply after connecting. Overrides any default viewport set by the browser.
​
deviceScaleFactor
number
Device pixel ratio for the viewport. Affects screenshot resolution and layout scaling.
​
downloadsPath
string
Directory where downloaded files are saved. Requires acceptDownloads to also be set when using this field.
​
acceptDownloads
boolean
When true, downloads are accepted and written to downloadsPath (or Chrome’s default download directory). When false, downloads are denied.

​
LocalBrowserLaunchOptions

Configures how Handstage launches or attaches to a local Chrome process. All fields are optional.

​
Browser binary and process

​
executablePath
string
Absolute path to the Chrome or Chromium executable. When omitted, Handstage uses the system Chrome found by chrome-launcher.
​
port
number
Remote debugging port for Chrome’s CDP WebSocket. Defaults to a random available port when omitted.
​
headless
boolean
Run Chrome in headless mode. When omitted, Chrome uses its own default (headless in CI environments).
​
devtools
boolean
Automatically open DevTools for every new tab (--auto-open-devtools-for-tabs). Only applies in headed mode.
​
chromiumSandbox
boolean
Enable or disable the Chromium sandbox. Defaults to the Chrome launcher’s default.
​
args
string[]
Additional command-line flags to pass to the Chrome process, appended after Handstage’s default flags.
​
ignoreDefaultArgs
boolean | string[]
When true, suppress all of Handstage’s default Chrome flags. When an array of strings, suppress only the flags whose text contains any of the provided strings.

​
User profile

​
userDataDir
string
Path to the Chrome user data directory. When omitted, a temporary directory is created in $TMPDIR/handstages-v3/ and deleted on close.
​
preserveUserDataDir
boolean
When true, the user data directory is not deleted when the session closes, even if it was created as a temporary directory.

​
Viewport and display

​
viewport
{ width: number; height: number }
Initial browser window size. Handstage passes --window-size to Chrome and sets Emulation.setDeviceMetricsOverride for each page. Defaults to { width: 1288, height: 711 }.
​
deviceScaleFactor
number
Device pixel ratio (--force-device-scale-factor). Affects screenshot resolution and CSS layout.
​
hasTouch
boolean
Enable touch event emulation (--touch-events=enabled).
​
locale
string
Browser locale passed via --lang (e.g., "en-US", "de-DE").

​
Network

​
proxy
{ server: string; bypass?: string; username?: string; password?: string }
Proxy configuration for all connections.
  • server: Proxy server URL (e.g., "http://proxy.example.com:8080").
  • bypass: Comma-separated hostnames to bypass the proxy.
  • username: Proxy authentication username.
  • password: Proxy authentication password.
​
ignoreHTTPSErrors
boolean
Ignore TLS certificate errors (--ignore-certificate-errors). Useful for testing against self-signed certificates.

​
Downloads

​
downloadsPath
string
Directory where Chrome saves downloaded files.
​
acceptDownloads
boolean
When true, downloads are accepted automatically. When false, they are denied.

​
Connecting to an existing browser

Use cdpUrl to skip launching a new Chrome process and connect to one that is already running.
​
cdpUrl
string
WebSocket URL of an existing Chrome DevTools Protocol endpoint (e.g., "ws://127.0.0.1:9222/json/version"). When set, executablePath, port, headless, and related launch flags are ignored.
​
cdpHeaders
Record<string, string>
Additional HTTP headers to include in the WebSocket upgrade request when connecting via cdpUrl. Has no effect if cdpUrl is not set.
​
connectTimeoutMs
number
Maximum time in milliseconds to wait for the CDP WebSocket connection to be established. Applies both to new launches and cdpUrl connections.

​
CreateContextOptions

Passed to browser.create() and context.createBrowserContext().
​
disposeOnDetach
boolean
default:"true"
When true, Chrome automatically disposes the browser context and its storage if the CDP connection drops unexpectedly.
​
proxyServer
string
Proxy server URL for requests originating from this context (e.g., "http://proxy.example.com:8080").
​
proxyBypassList
string
Comma-separated list of hosts that bypass the context’s proxy.
​
originsWithUniversalNetworkAccess
string[]
Origins granted unrestricted network access from within this context, bypassing CORS and mixed-content restrictions.

​
Usage examples

import { V3, LogLevel } from "@handstage/core"

// Local launch with full options
const browser = await V3.connectLocal({
  verbose: LogLevel.Debug,
  logger: (line) => myLogger.log(line.level, line.message, line.attributes),
  localBrowserLaunchOptions: {
    headless: false,
    viewport: { width: 1440, height: 900 },
    deviceScaleFactor: 2,
    args: ["--disable-extensions"],
    proxy: { server: "http://proxy.example.com:8080" },
    downloadsPath: "/tmp/downloads",
    acceptDownloads: true,
  },
})

// Connect to a running browser
const browser2 = await V3.connectLocal({
  localBrowserLaunchOptions: {
    cdpUrl: "ws://127.0.0.1:9222/json/version",
  },
})

// Isolated context with a per-context proxy
const isolated = await browser.create({
  disposeOnDetach: true,
  proxyServer: "http://eu-proxy.example.com:8080",
})

Build docs developers (and LLMs) love

Get started for freeTalk to us