The cost review ended with the question nobody wanted to answer: how long would it take to move the browser fleet? The agent code was written against a vendor SDK months ago, and its options are scattered across the codebase. Before anyone commits to a date, someone has to know what breaks.
Moving from Browserbase to Solari is mostly a change of import and API key. Solari ships a compatibility package for Node and Python in which sessions, contexts, live view and recording work the same way, and an option outside its scope raises a clear error instead of quietly doing something different. This guide walks through what stays the same, what to change and how to test the switch.
What Stays the Same
The good news comes first, because it covers most of a typical codebase. The package keeps the old SDK's client shape: sessions.create, retrieve, list and update all work, and update with REQUEST_RELEASE releases the session. Statuses map to RUNNING, COMPLETED, TIMED_OUT and ERROR, so existing status checks still read correctly.
The connectUrl a session returns is a raw Chrome DevTools Protocol websocket URL, so Playwright, Puppeteer, Stagehand and browser-use all connect with no client version to pin. Treat that URL as a secret, because the session id inside it is the credential. With the surface unchanged, the actual switch is short.
How to Switch the Import and the Key
The switch is an install, an import and a key. Install @solarisdk/browserbase-compat from npm or solari-browserbase-compat from pip, then point the existing client at a Solari key:
Only keys that start with slr_ are used. An old key left in BROWSERBASE_API_KEY is skipped, never sent anywhere and never printed, so a half-migrated environment does not leak the previous credential. Once the import compiles, the next job is reading the options each session passes.
What to Change in Your Session Options
Most options map directly, and the figure below lists the ones worth a second look.
Recording is the change most teams notice. Recording is a DOM-event log: sessions.recording.retrieve returns the events a few seconds after release, with no HLS or MP4 file, so a pipeline that archives replays as video needs a new step.
Captcha solving stays off unless solveCaptchas: true is passed, where the previous setup had it on by default, so add the flag wherever a job depends on it. Proxies follow the same opt-in logic: geolocation options become a managed proxy in the country, state or city you pick, on the stealth browser the package switches on for you.
Viewport moves into the automation client: call page.setViewportSize instead of setting it at create. The blockAds, logSession and os options log a warning and change nothing; pass strict: true to turn them into errors.
Session lifetimes deserve a look too. Without keepAlive, a session whose client disconnects is released about 45 seconds after the disconnect, never sooner than 3.5 minutes after it was created, so jobs that reconnect should set keepAlive: true. Saved logins need the most care, so they get their own section.
How Saved Logins Carry Over
Logins are where a migration usually goes wrong, because an agent that loses its session fails quietly on the next run. Existing contexts become Solari profiles, which keep cookies and localStorage. A site that relies on IndexedDB or service workers for its login needs a separate check before it moves.
The code flow is unchanged. Create a context, start a session with browserSettings.context and persist: true, log in, then release through the same client to save it. The next session that names the context returns the saved login as storageState.
A detail trips people up here. Saved cookies land in the browser's default context, so browser.contexts()[0] is already signed in, but localStorage is applied only when a context is created from the session's storageState with browser.newContext({ storageState }). With logins in place, the last step is proving the migration before traffic moves.
How to Test the Migration
Testing starts by turning warnings into failures. Run the existing suite with strict mode on, so an ignored option stops the run instead of logging, and watch for SolariCompatUnsupported. The package raises it for features outside its scope, such as browser extensions, the Selenium endpoint, the downloads and uploads APIs, bring-your-own proxies and mobile profiles.
Next, run a representative job with recordSession: true and read the events back after release to confirm the agent did what it should. Tagging test runs with userMetadata then lets sessions.list filter them, which makes statuses easy to compare across runs. For anything this guide does not cover, each package's COMPAT.md lists every difference.
Choosing the Right Migration Path
For most codebases the migration is an import, a key and a short list of option changes: add the captcha flag where needed, move viewport into the client, rework video replay archiving and check logins stored outside cookies and localStorage. The compat package lets a team move traffic first and refactor later. Teams that then want every Solari option can move to the native sessions API, where every option is opt-in.
Get Started With Solari
Start by running the existing suite through the compat package with strict mode on. Solari has browsers ready in 8 ms and bills $0.07 per browser hour on the Professional plan (pricing), and the Free plan includes $3 in monthly credits, so the first test run costs nothing; the introduction to Solari covers the sandboxes and desktops on the same account. Create a free Solari account and run the first migrated session today.
