Reconnect to the original browser ID when a worker loses its connection and the provider still reports the original session as ready.
Issue short-lived credentials for that session, confirm its identity, and keep the business API key out of the browser connection.
Select the original tab by approved URL and a job-specific checkpoint. Treat a missing or ambiguous tab as a decision for reconciliation.
Read a durable business receipt before retrying an action whose response was lost.
An ended browser session requires a fresh session if work can safely resume. Rebuilding a browser cannot establish what happened in the application.
Check task acceptance and session shutdown independently. A new WebSocket and a stopped browser prove different things.
When can you reconnect to a remote browser?
You can reconnect to a remote browser when the original runtime is still available and you can obtain current connection credentials for that same session. A network disconnect tells you what the worker observed. The browser may still have its pages open, and the target app may already have accepted the last action. Nstdata documents an attachment flow for existing Cloud Browser sessions as part of its browser automation service.
Suppose a release reviewer has reached a staging report and the worker disconnects just after clicking an approval control. The browser platform can report whether the session exists. The report can show which revision is on screen. The authoritative application record determines whether the approval committed. Those are three distinct pieces of evidence. The worker should restore observation before it decides to act.
The browser session lifecycle guide covers creating and terminating sessions. Recovery starts later, with an existing job and a persisted session ID. The retry and idempotency guide covers the different case where a create response may have been lost and the worker never learned which session was allocated.
Which state should a worker preserve before any disconnect?
Store the job and session identities, the expected page boundary, and the application checkpoint before entering a step that could change business state. A small record might contain a job ID, workspace label, browser session ID, approved origin, expected route, safe checkpoint value, and an application operation reference. Keep its access policy separate from browser credentials.
Keep reconciliation active until shutdown is confirmed
Avoid persisting the signed WebSocket address or an access token in the job record. Store the identifier used to request fresh credentials through the supported interface. That approach gives a replacement worker a durable starting point without exposing a reusable connection in a queue, ticket, or trace. See the OWASP secret lifecycle guidance.
How do you recover the original session and locate its tab?
Inspect the existing session, establish a bounded CDP connection, and verify the exact page and checkpoint before taking another action. The workflow assumes access to the original workspace, the recorded session ID, and a safe view of the target app. The local example uses Node.js 22, playwright-core@1.65.1, and the companion fixture. Install Chromium with npx playwright-core install chromium for the local branch.
Step 1. Read the session record
Open Cloud Browser β Session History in the intended workspace and find the original session. In code, inspect GET /sessions/{sessionId} under the documented Cloud Browser API base. Treat ready as permission to proceed to credential issuance, subject to authorization. If a stop is already in progress, observe until the platform settles. If the session is ended, use an application checkpoint to decide whether a new session can safely continue. Cloud Browser Browser Automation documentation.
[Screenshot: Show a test session in Session History, its state, and the matching job reference. Mask account and session identifiers.]
Step 2. Obtain current connection credentials
For a ready session, request POST /sessions/{sessionId}/automation-credentials with the business API credential and the correct workspace context. Verify the returned session ID and expiration. Supply the returned CDP address and header to the client using the documented header construction. Never log a full signed address or the authentication header. Use the Playwright BrowserType documentation for connectOverCDP() options and protocol limits.
Step 3. Find the original tab without creating a new one
Run node recover.mjs with a loopback LOCAL_CDP_URL and an APP_ORIGIN that serves the companion fixture. Start node fixture.mjs and open its /recover route once in the test browser. The attached client searches existing contexts for a single exact match, then reads the expected fixture marker. The companion verifier provisions a temporary Chromium profile, checks that the original page survives the client disconnect, and verifies that two matching tabs cause a refusal. The managed branch requires an authorized Nstdata key and an existing ready session with an equivalent approved application checkpoint. Use a staging checkpoint reachable within the managed browserβs authorized environment.
const root ='https://api.nstdata.io/api/v1/cloud-browser';exportasyncfunctionapi(method, path, body){const key = process.env.NSTDATA_API_KEY;if(!key)thrownewError('Set NSTDATA_API_KEY');const headers ={'x-api-key': key };if(process.env.NSTDATA_TEAM_ID) headers['x-team-id']= process.env.NSTDATA_TEAM_ID;if(body) headers['content-type']='application/json';let response;try{ response =awaitfetch(root + path,{ method, headers,redirect:'error',body: body ?JSON.stringify(body):undefined,signal:AbortSignal.timeout(20_000),});}catch{throwObject.assign(newError('API transport failed; reconcile the original operation'),{retryable:true});}const retryable = response.status===429|| response.status>=500;let result;try{ result =await response.json();}catch{throwObject.assign(newError('Invalid API JSON'),{ retryable });}if(!response.ok|| result.err===true|| result.success===false){throwObject.assign(newError(`Cloud Browser API HTTP ${response.status}`),{ retryable });}if(!result.data)thrownewError('Missing API data');return result.data;}exportasyncfunctionconnection(id){if(!id)thrownewError('Set NSTDATA_SESSION_ID');const path =`/sessions/${encodeURIComponent(id)}`;const session =awaitapi('GET', path);if(session.state!=='ready')thrownewError(`Session is ${session.state}, not ready`);const c =awaitapi('POST', path +'/automation-credentials');if(c.sessionId!== id ||!c.headerName||!c.accessToken||!(Date.parse(c.expiresAt)>Date.now())||newURL(c.cdpUrl).protocol!=='wss:'){thrownewError('Invalid or expired CDP credentials');}return{endpoint: c.cdpUrl,headers:{[c.headerName]: c.headerName.toLowerCase()==='authorization'?`Bearer ${c.accessToken}`: c.accessToken},};}exportasyncfunctionendpoint(){// An isolated local CDP endpoint can test the client without managed credentials.if(process.env.LOCAL_CDP_URL){const url =newURL(process.env.LOCAL_CDP_URL);if(!['127.0.0.1','localhost','[::1]'].includes(url.hostname)){thrownewError('LOCAL_CDP_URL must use loopback');}return{endpoint: url.href,headers:{}};}returnconnection(process.env.NSTDATA_SESSION_ID);}
The expected fixture result contains only the safe job label, observed checkpoint, and next decision. The result is intentionally reconcile, because seeing a page marked reviewed cannot prove that a later application write completed. When a real workflow normally navigates or opens a new tab, define the exact approved routes and markers for each transition. The Playwright guide to pages and tabs explains the relationship between pages and browser contexts.
Step 4. Check the application before replaying a write
Look for the business receipt or status using a read-only application path. If the result already exists for the original operation, mark the task accepted from that evidence and schedule cleanup. If the result is absent, confirm the original request has settled before deciding to repeat it. Where the target app supports an idempotency key, keep the original operation reference and follow that app's rules. An ambiguous result goes to the operator or reconciliation queue with a bounded deadline.
What should happen if a recovery step fails?
A failed recovery step should preserve the existing state and report which layer prevented verification. A session lookup that fails cannot establish whether the browser still exists. A successful WebSocket without a matching page is an attachment success and a page-selection failure. These states call for different next actions.
Symptom
Likely cause to check
Next action
Original session is terminal
Timeout, explicit stop, or provider lifecycle outcome
Read the durable checkpoint before allocating a replacement
Connection rejected
Wrong workspace, expired credentials, or bad header construction
Inspect the original state and issue current credentials once the configuration is corrected
Two pages match the URL
Duplicate tab or parallel ownership
Stop automation and require a stronger task marker or explicit tab selection
Page shows a completed screen without a receipt
Incomplete state or stale UI
Verify the application-side operation record
Cleanup stays pending
Stop outcome unconfirmed
Keep the session tracked and inspect its terminal state
If a new worker can start while an old one is still connected, use an application lease or ownership check before issuing any write. Release browser capacity only after cleanup is confirmed according to the provider's lifecycle. The CDP authentication guide helps isolate a configuration failure before the worker touches the page.
How does Nstdata Cloud Browser fit a recovery runbook?
Nstdata Cloud Browser provides managed cloud browsers for browser automation and AI agents, with session state and documented CDP attachment. A team can use the same service for routine task execution and supervised recovery while maintaining its own application checkpoints. Use existing-session attachment when the workspace still owns a ready runtime. Live View can help an authorized operator validate a page that automation cannot uniquely identify. The service's session information cannot establish whether a staging approval or other application action committed.
Session lookup. Use the prior ID to inspect lifecycle state and avoid allocating a replacement on a transport error.
Short-lived attachment. Request current credentials for the session, keep them inside the worker, and persist only the safe operation reference.
Operator evidence. Use available observations to understand which page was active or stuck. Keep sensitive screenshots, URLs, and logs out of routine tickets.
Explicit cleanup. Assign the controller that will stop the managed browser. Closing the attachment and ending the managed session are separate operations.
A recovery drill should prove that a replacement worker can find the right page, recognize uncertain business state, and stop the original session under known ownership. Begin with an authorized staging report, disconnect the worker before a read-only checkpoint, and verify that the replacement reads the same task marker. Repeat with a competing tab and a checkpoint that cannot resolve the business outcome. The first run should continue observation, while the other runs should stop or escalate with an actionable reason.
Record elapsed time from disconnect to verified disposition and count cases that required a human. Track job success and browser cleanup separately. When a failure needs forensic review, consider session recording and replay for synthetic test cases with approved retention.
Q: Does a dropped WebSocket mean the original browser stopped?
The browser state is determined by the provider's session record. Query the original ID before reconnecting or replacing the browser.
Q: Can an ended Cloud Browser session be reopened?
Treat the ended session as terminal. Use persistent application state to choose a safe next step in a new session.
Q: Should a recovery worker create a fresh page?
Select the existing page when you need its state. Open a new page only for a workflow that explicitly permits rebuilding context.
Q: Can an old CDP address be reused after a disconnect?
Request current credentials for the original ready session and check the documented expiration. Store only a safe session reference for subsequent recovery.
Q: What should an operator see in an escalation?
Provide the job ID, safe phase, browser state, outcome evidence, and cleanup owner. Share protected artifacts through the approved incident channel.
Marcus Chen
Nov. 20th 2026
Launch cloud browsers on demand
Handle fingerprints and CAPTCHAs
Automate workflows and power AI agents
From web scraping and testing to AI-driven automation, run it all in the cloud.