Control Social Browser from code

Architecture

How the developer flow works

A Social Browser Profile is a persistent browser environment. Your manual browsing and your automation can operate on the same Profile, so cookies, local storage, login state, proxy choice and supported browser settings can remain available between runs.

External tools

Set up an API / CDP client

1. 1
   Open API Clients

   Inside Social Browser open browser://local/settings/api-clients. This is the source of truth for the endpoint and security options supported by the installed build.

2. 2
   Enable only the client access you need

   Keep developer access local unless you deliberately configure a trusted network path. Treat any API key/token as a secret.

3. 3
   Copy the local endpoint from the browser

   The examples below use the standard local debugging address http://127.0.0.1:60101. If the API Clients screen shows another endpoint, use the value shown by your browser.

4. 4
   Discover the live browser and targets

   Query the Chromium discovery endpoints or connect with Puppeteer. Resolve live targets each time you connect.

curl http://127.0.0.1:60101/json/version curl http://127.0.0.1:60101/json/list

$base = "http://127.0.0.1:60101" $version = Invoke-RestMethod "$base/json/version" $targets = Invoke-RestMethod "$base/json/list" $version $targets | Select-Object id, type, title, url

const base = "http://127.0.0.1:60101"; const version = await fetch(`${base}/json/version`).then(r => r.json()); const targets = await fetch(`${base}/json/list`).then(r => r.json()); console.log("Browser:", version.Browser); console.table(targets.map(t => ({ id: t.id, type: t.type, title: t.title, url: t.url, }))); 

/json/version describes the running browser/debugging endpoint. /json/list returns currently discoverable targets. A target is runtime state, not a durable Profile identifier.

Node.js

Connect with Puppeteer

Social Browser uses the running Chromium debugging surface, so an external Node.js process can attach with puppeteer-core. Set defaultViewport: null so Puppeteer does not impose its normal 800×600 viewport on an existing Social Browser workspace.

const puppeteer = require("puppeteer-core"); const browser = await puppeteer.connect({ browserURL: "http://127.0.0.1:60101", defaultViewport: null, }); const pages = await browser.pages(); for (const page of pages) { console.log(await page.title(), page.url()); } // Disconnect your client without closing Social Browser. await browser.disconnect();

Find the page you actually want

const pages = await browser.pages(); const page = pages.find(p => p.url().startsWith("https://example.com/") ); if (!page) { throw new Error("Target page is not currently open"); } console.log({ title: await page.title(), url: page.url(), });

For multi-Profile workflows, do not assume the first page returned belongs to the intended Profile. Resolve and verify the target before changing it.

Simple read + action example

await page.waitForSelector("#search", { visible: true }); await page.type("#search", "Social Browser"); await page.click('button[type="submit"]'); await page.waitForSelector(".results", { visible: true }); const titles = await page.$$eval(".result-card h2", nodes => nodes.map(node => node.textContent.trim()) ); console.log(titles);

Trusted User Scripts

Use SOCIALBROWSER.page inside the current tab

Trusted Social Browser User Scripts receive the global SOCIALBROWSER object. SOCIALBROWSER.page gives you JavaScript-only, Puppeteer-inspired helpers for the exact tab where the script is running. You do not need a separate Node.js process for this path.

const page = SOCIALBROWSER.page; const email = await page.waitForSelector("#email", { visible: true, timeout: 10000, }); if (!email) return null; await page.type("#email", "name@example.com", { clear: true }); await page.type("#password", "placeholder-password", { clear: true }); await page.click('button[type="submit"]'); return await page.waitForSelector(".dashboard, .login-error", { visible: true, timeout: 15000, });

See the complete SOCIALBROWSER.page method reference and examples →

Main Process bridge

Run real Puppeteer against the exact current tab

SOCIALBROWSER.page.runPuppeteer() is intended for trusted User Scripts. The callback runs with real Puppeteer in the Main Process and Social Browser resolves the current renderer to the matching Puppeteer target.

const result = await SOCIALBROWSER.page.runPuppeteer( async (browser, page, args) => { await page.screenshot({ path: args.path }); return { title: await page.title(), url: page.url(), heading: await page.$eval("h1", node => node.textContent.trim()), }; }, { path: "C:/temp/social-browser-page.png" }, ); console.log(result);

The bridge connects Puppeteer with defaultViewport: null and resolves the exact target using the current Chromium debugger target information. The embedded debugger attaches through CDP protocol version 1.3 when needed.

Reliability

Lifecycle and target-selection rules

async function findTargetPage(browser, expectedUrlPrefix) { const pages = await browser.pages(); const page = pages.find(p => p.url().startsWith(expectedUrlPrefix)); if (!page) throw new Error("Target is not available"); return page; } let page = await findTargetPage(browser, "https://example.com/"); await page.goto("https://example.com/dashboard"); // Resolve/validate again when your workflow crosses a restart or reconnect boundary. page = await findTargetPage(browser, "https://example.com/");

Errors

Handle failures explicitly

The JavaScript page helpers are designed to fail safely for unavailable targets/actions and commonly resolve to null. Guard important results. The real Puppeteer bridge can also return structured automation errors such as invalid requests, unavailable bridge state, or a missing matching page.

const saveButton = await SOCIALBROWSER.page.click("#save"); if (!saveButton) { console.warn("Save button was not available"); return null; }

Security

Developer access is powerful — scope it carefully

• Keep the debugging/API endpoint bound to 127.0.0.1 unless you intentionally secure another network path.
• Do not publish API keys, client secrets or remote debugging endpoints in source control.
• Treat trusted User Scripts as privileged code; review them before enabling them.
• Use Profile-level separation so automation for one account/workspace does not accidentally act in another.
• Do not expose internal runtime IDs as durable database identifiers.
• Use these capabilities only on systems, pages and accounts you are authorized to operate.

Complete examples

Practical workflow patterns

Read a dashboard value

const page = SOCIALBROWSER.page; const dashboard = await page.waitForSelector(".dashboard", { visible: true, timeout: 15000, }); if (!dashboard) return null; return await page.$eval("[data-balance]", node => node.textContent.trim() );

Wait for a loader, then collect rows

const page = SOCIALBROWSER.page; await page.waitForGone(".loading-overlay", { timeout: 20000 }); return (await page.$$eval("table tbody tr", rows => rows.map(row => Array.from(row.cells, cell => cell.textContent.trim())) )) || [];

External QA check through Puppeteer

const puppeteer = require("puppeteer-core"); const browser = await puppeteer.connect({ browserURL: "http://127.0.0.1:60101", defaultViewport: null, }); try { const page = (await browser.pages()).find(p => p.url().includes("example.com") ); if (!page) throw new Error("Expected page is not open"); const result = { title: await page.title(), url: page.url(), hasMain: await page.$("main") !== null, }; console.log(result); } finally { await browser.disconnect(); }

Troubleshooting

Common setup problems