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.

V3 is the entry point to every Handstage session. You create an instance by calling one of the three static connect methods — connectLocal, connectTransport, or connectSession — and then interact with the browser through its context property or by calling create() to open an isolated context.

​
Static methods

​
V3.connectLocal

Launch or attach to a local Chrome browser over CDP. 
import { V3 } from "@handstage/core"

const browser = await V3.connectLocal({
  localBrowserLaunchOptions: { headless: true },
})

const page = await browser.context.activePage()
await page.goto("https://example.com")
await browser.close()
​
opts
HandstagesLocalOptions
Launch and session options. All fields are optional. See Configuration options reference for the full schema.
Returns Promise<V3>

​
V3.connectTransport

Connect using a custom CDP transport object. Use this when you supply your own WebSocket implementation or proxy layer. 
import { V3 } from "@handstage/core"

const browser = await V3.connectTransport(myTransport, {
  viewport: { width: 1280, height: 720 },
})
​
transport
CDPTransport
required
A CDP transport that implements send and exposes CDP events. Handstage wraps it in a CdpConnection internally.
​
opts
HandstagesConnectOptions
Session and viewport options. See Configuration options reference.
Returns Promise<V3>

​
V3.connectSession

Connect to an existing CDP session object — for example, a session handed off from another automation framework. 
import { V3 } from "@handstage/core"

const browser = await V3.connectSession(existingSession, {
  viewport: { width: 1280, height: 720 },
})
​
session
ExternalCDPSession
required
An existing CDP session that exposes send, on, and off.
​
opts
HandstagesConnectOptions
Session and viewport options. See Configuration options reference.
Returns Promise<V3>

​
Instance properties and methods

​
browser.context

Returns the default browser context for the session. This is the context that owns the initial pages opened at connect time. 
const ctx = browser.context
const page = ctx.activePage()
Type V3Context Throws if the instance has already been closed.

​
browser.create

Create a new isolated browser context — similar to an incognito profile. The new context shares the underlying CDP connection but has its own cookies, storage, and pages. disposeOnDetach defaults to true so Chrome auto-cleans the context if the connection drops. 
const isolated = await browser.create({ disposeOnDetach: true })
const page = await isolated.newPage("https://example.com")
await isolated.close()
​
options
CreateContextOptions
Options for the new context. See V3Context — browser context API reference for CreateContextOptions.
Returns Promise<V3Context>

​
browser.connectURL

Returns the browser-level CDP WebSocket URL for local connections. Returns an empty string when the instance was created via a custom transport or session. 
const wsUrl = browser.connectURL()
// e.g. "ws://127.0.0.1:9222/json/version"
Returns string

​
browser.close

Shuts down the browser session. Closes the active context, and — for local connections where keepAlive is not set — kills the Chrome process and cleans up any temporary profile directories. 
await browser.close()
// pass { force: true } to bypass the in-progress guard
await browser.close({ force: true })
​
opts.force
boolean
When true, bypasses the internal guard that prevents concurrent close calls. Use only when you need to force-close an already-closing instance.
Returns Promise<void>

​
browser.verbose

Controls the minimum log level emitted by this instance. Assign a LogLevel value to change verbosity at runtime. 
import { LogLevel } from "@handstage/core"

browser.verbose = LogLevel.Debug
Type LogLevel See Error types and error handling for the LogLevel enum values.

​
browser.logger

A function that receives every LogLine that passes the current verbose threshold. Assign a custom function to redirect logs to your own sink. 
browser.logger // (logLine: LogLine) => void
The getter returns a bound function that delegates to the configured log sink. To supply your own sink, pass a logger function in the options when calling a connect method. Type (logLine: LogLine) => void

Build docs developers (and LLMs) love

Get started for freeTalk to us