Connect external tools to Social Browser

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);

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.