Before you start
Nefo offers residential proxies across 227 countries, reachable over HTTP, HTTPS, and SOCKS5 with username/password authentication. Generate a username and password from the dashboard proxy generator; creating credentials is free and only traffic consumes your prepaid bandwidth (from 5 GB for $4.50, non-expiring on flexible plans).
Because Chromium passes proxy credentials separately, Puppeteer supplies them through page.authenticate() rather than embedding them in the URL.
- Node.js 18+ with the puppeteer package installed
- A Nefo account with prepaid bandwidth
- A username/password from /dashboard/generator
- Your chosen protocol and port (HTTP 9000/10000)
- The target country token for your username
Puppeteer proxy and page.authenticate() example
Point the browser at the gateway host and authenticate on the first page. Example:
The username token USERNAME-country-us requests a rotating US residential IP. Swap us for any supported ISO country code, or extend it with state, city, or ASN tokens for tighter targeting.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
args: ['--proxy-server=http://gw.nefo.net:9000'],
});
const page = await browser.newPage();
await page.authenticate({
username: 'USERNAME-country-us',
password: 'PASSWORD',
});
await page.goto('https://api.ipify.org');Puppeteer rotating vs sticky proxy sessions
Rotating sessions assign a fresh residential IP on every request and use HTTP port 9000. They suit broad, parallel crawling where each page can come from a different exit.
Sticky sessions keep one IP for 1 minute up to 24 hours and use HTTP port 10000. Add a session and lifetime token, for example USERNAME-country-us-session-abc123-lifetime-30, to hold an IP for 30 minutes across a login or multi-step flow. Note that Chromium cannot authenticate SOCKS5, so use the HTTP ports with Puppeteer.
Geo-targeting by country, state and city in Puppeteer
Targeting is controlled entirely through username tokens: country for any of 227 countries, plus state and city within the US, or ASN/ISP within a country. Only the username changes, so you can spin up many geo profiles from one credential set.
Always scrape lawfully, respect each site's terms of service, and stay within applicable law and rate limits.
Frequently asked questions
Use HTTP port 9000 for rotating IPs or 10000 for sticky IPs. Chromium does not support authenticated SOCKS5, so avoid ports 11000 and 12000 with Puppeteer.
A 407 means proxy authentication failed. Confirm you call page.authenticate() with the exact username token and password from the proxy generator, and that you call it before navigating to the target page.
Use port 10000 and add a session token to the username, such as USERNAME-country-us-session-abc123-lifetime-30. One residential IP is then held for the lifetime you set, up to 24 hours.
Yes. US targeting goes down to state and city through additional username tokens, so you can request residential exits in a chosen city. See US city-targeted proxies.
No. Generating credentials is free; only the traffic you route through the proxy consumes your prepaid bandwidth.