STAGEHAND + PROXIES.SX

RUNNABLE SAMPLE

Replace ACCOUNT_ID and PROXY_PASSWORD with the values from GET https://api.proxies.sx/v1/gateway/credentials (header X-API-Key: psx_...). The proxy password is set once in the portal and is not your login password.

// npm i @browserbasehq/stagehand zod
// Stagehand's local launch does not support authenticated proxies (docs.stagehand.dev/configuration/browser),
// so route the Browserbase session through the gateway with an external proxy.
import { Stagehand } from "@browserbasehq/stagehand";
import { randomUUID } from "node:crypto";
import { z } from "zod";

const sid = randomUUID().slice(0, 12);            // one session id per instance
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  browserbaseSessionCreateParams: {
    projectId: process.env.BROWSERBASE_PROJECT_ID,
    proxies: [{
      type: "external",
      server: "http://gw.proxies.sx:7000",
      username: `psx_ACCOUNT_ID-peer-us-rot-sticky-sid-${sid}`,
      password: "PROXY_PASSWORD",
    }],
  },
});
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://api.ipify.org?format=json");
const { ip } = await stagehand.extract("the ip field", z.object({ ip: z.string() }));
console.log(ip);
await stagehand.close();

Running Stagehand locally? Its local launch cannot take a username/password proxy yet, so use the Browserbase path above or a local unauthenticated forwarder in front of gw.proxies.sx.

ROTATION FOR STAGEHAND

Use: sticky per Stagehand instance. One Stagehand instance is one browser session; give it one session id at init and every act/extract in it shares the exit.

Sticky pins the device for that session id, not the exit IP - mobile carriers re-NAT on their own schedule, so a pinned modem can still surface a new address. Without a -sid-, sticky and auto modes do nothing across connections. Unknown tokens are dropped silently, so -session- is not a substitute for -sid-.

CHANGE COUNTRY OR POOL

Edit the username only: peer-us, peer-jp, mbl-gb. peer covers ~127 countries; mbl is carrier modems in US, GB, FR, NL, PL and GE (Georgia). Check stock before you pick: GET https://api.proxies.sx/v1/gateway/pool/stock. $4/GB, $2.40/GB at 250 GB+, duration free.

MORE

/pool/skill.md (full username DSL and API contract) · /pool/ (Pool Gateway) · all integrations · skill.md for this section