Sessions

A session is the live browser connection behind a workspace. Workspaces persist state on disk. Sessions are the active runtime using that state right now.

Session lifecycle

The normal flow is:

1. open
2. navigate, snapshot, act, extract, inspect
3. close

If you want to detach from an SDK session without closing the browser, use disconnect().

Local session modes

The SDK supports three local browser modes:

Mode	What it does
persistent	Uses the workspace browser profile. This is the normal default when workspace is set.
temporary	Uses disposable browser state. This is the normal default when workspace is not set.
attach	Connects to an existing browser over CDP.

Examples:

new Opensteer({ workspace: "demo", browser: "persistent" });
new Opensteer({ browser: "temporary" });
new Opensteer({
  workspace: "demo",
  browser: {
    mode: "attach",
    endpoint: "ws://127.0.0.1:9222/devtools/browser/...",
  },
});

The CLI does not have a generic --browser switch. Stateful CLI commands use the workspace-backed browser by default. Attach mode is exposed through --attach-endpoint on compatible commands.

Cloud sessions

Cloud mode creates a managed remote session and records it separately in:

.opensteer/workspaces/<workspace>/live/cloud.json

Local sessions use:

.opensteer/workspaces/<workspace>/live/local.json

opensteer status shows both lanes so you can see whether the workspace currently has a live local session, a live cloud session, or both.

close() vs disconnect()

• close(): closes the active session
• disconnect(): detaches the SDK runtime without closing the underlying session

For persistent local sessions, close() also closes the owned browser manager. For cloud sessions, close() closes the managed cloud session.

Limits to remember

• Cloud mode does not support browser.mode="attach".
• record does not support attach mode.
• browser.clone(), browser.reset(), and browser.delete() require a persistent workspace browser.
• Local browser admin helpers are only available in local mode.