brightdata-proxy

What this skill does

# Bright Data Proxy

Generate working code and configuration for Bright Data's four proxy networks. This skill covers usage and integration — it does **not** walk users through control-panel UI setup. If the user hasn't created a zone yet, tell them to sign up at https://brightdata.com and use the in-app proxy creation helper (the control panel guides them through zone type, pool type, and credentials interactively — that's the right surface for setup, not this skill).

## Quick reference (canonical facts)

These are the values to use in generated code. They are easy to hallucinate wrong, so anchor on them.

- **Proxy host**: `brd.superproxy.io`
- **HTTP/HTTPS proxy port**: `33335` (current, paired with the **new** SSL CA — expires Sept 2034)
  - Legacy port `22225` exists for the old CA (expires Sept 2026, deprecated). Use 33335 unless the user explicitly says otherwise.
- **SOCKS5 port**: `22228`
- **Username format**: `brd-customer-CUSTOMER_ID-zone-ZONE_NAME` plus optional `-key-value` parameters appended (see Targeting below).
- **Password**: the zone password from the control panel (not the account password).
- **Test endpoint** (use in code samples, not against real targets): `https://geo.brdtest.com/mygeo.json` — returns exit IP, country, city, and ASN as JSON.
- **SSL CA**: bundled with this skill at `assets/brightdata_proxy_ca.crt` (Bright Data Proxy Root CA, valid until Sept 2034). Generated code should reference this path, not tell the user to go download it. The public download is at `https://brightdata.com/static/brightdata_proxy_ca.zip` if they ever need to fetch it independently.

The line `https://brightdata.com/cp/zones/proxy_examples` in the control panel shows live, account-specific code samples for every framework — point the user there for ground truth when uncertain.

## Bundled tools (in this skill)

- **`assets/brightdata_proxy_ca.crt`** — the Bright Data Root CA. Use this in `verify=`, `--cacert`, `ca:`, or `NODE_EXTRA_CA_CERTS` instead of having the user download it.
- **`scripts/smoke_test.sh`** — cURL-based credential smoke test. Run `./smoke_test.sh CUSTOMER_ID ZONE_NAME ZONE_PASSWORD [COUNTRY] [SESSION_ID]` (or set `BD_CUSTOMER_ID`/`BD_ZONE`/`BD_PASSWORD` env vars). Auto-locates the bundled CA, returns parsed JSON geo, distinct exit codes for auth vs HTTP vs network failure. Recommend this as the first thing the user runs after creating a zone.
- **`scripts/proxy_tester.html`** — single-file browser diagnostic. User configures their browser or OS proxy with the credentials, opens the file locally (or serves it from anywhere), and sees a live readout of their current exit IP/geo. Has a baseline-save feature so they can compare pre-proxy vs post-proxy exits visually. Credentials live in `sessionStorage` only — nothing is uploaded.

---

## Decision 1: which proxy network?

If the user hasn't said which network they're on, ask once, then proceed. Quick rubric:

| Network | When to recommend |
|---|---|
| **Datacenter** | Cheapest, fastest. Use for unprotected targets (news sites, public APIs, light scraping, account management at low scale, geo-bypass on permissive sites). |
| **ISP** | Static IPs that look residential to the destination. Best for long-lived sessions, account management on protected platforms, anything where IP reputation matters but you want speed and stability. |
| **Residential** | Real-user IPs from a 100M+ pool. Default choice when datacenter and ISP get blocked. Best success rate on hard targets. Pay-per-GB; slower. Requires SSL cert or KYC (see Residential/Mobile network access below). |
| **Mobile** | 3G/4G/5G mobile carrier IPs. Most expensive. Use only when the target is extreme (Instagram, TikTok, some banking). Same network-access requirements as Residential. |

Default reach order when the user is unsure: Datacenter → Residential. ISP and Mobile are deliberate choices for specific needs.

## Decision 2: which IP pool type? (Datacenter and ISP)

Bright Data sells Datacenter and ISP traffic in three IP-allocation modes. The user picks this when they create the zone in the control panel.

| Pool type | What it is | When to recommend |
|---|---|---|
| **Shared pool** (also called "pay-per-GB" or "unlimited") | Pull random IPs from a huge shared pool. No fixed IPs allocated to you. Pay per GB of traffic. | Default for high-volume rotating scraping. You don't care which IP you get, you just want a fresh one frequently. |
| **Shared IPs** | A fixed set of N IPs leased to you, but shared with other Bright Data customers. Cheaper than dedicated. | Mid-budget. You want some IP stability but not exclusivity. Useful when the target accepts moderately-warm IPs. |
| **Dedicated IPs** | A fixed set of N IPs leased exclusively to you. No other customer uses them. Highest cost per IP. | Account management on platforms that fingerprint IPs heavily, anything needing a clean reputation you control, anything where another customer's bad behavior on a shared IP would burn you. |

For Residential and Mobile the equivalent of "dedicated" is **dedicated gIPs** (groups of IPs) selected via the `-gip-` parameter — not the same as DC/ISP dedicated. Don't confuse the two.

---

## Proxy URL format & authentication

The username carries all per-request configuration. The general form:

```
brd-customer-CUSTOMER_ID-zone-ZONE_NAME[-param1-value1][-param2-value2]...
```

Composed into a proxy URL it looks like:

```
http://brd-customer-CUSTOMER_ID-zone-ZONE_NAME[-PARAMS]:[email protected]:33335
```

Notes:
- The scheme is `http://` even for HTTPS targets — that's the proxy's own scheme, not the destination's.
- Always URL-encode the password if it contains special characters.
- Parameters are appended to the username with hyphens — they are **not** query-string params on the URL.
- Zone name cannot be changed after creation; the user has to make a new zone if they want a different name.

## Username parameters (targeting, rotation, session)

| Parameter | Applies to | What it does | Example suffix on username |
|---|---|---|---|
| `-country-XX` | All networks | ISO country code (2-letter, lowercase). `eu` = random EU country. | `-country-us` |
| `-state-XX` | **Residential, Mobile only** | US state, 2-letter, requires `-country-us` | `-country-us-state-ny` |
| `-city-NAME` | **Residential, Mobile only** | City, no spaces (`sanfrancisco`), requires country | `-country-us-city-sanfrancisco` |
| `-zip-NNNNN` | **Residential, Mobile only** | US zip, 5 digits | `-country-us-zip-37501` |
| `-asn-NNNNN` | **Residential, Mobile only** | Target a specific ASN | `-asn-56386` |
| `-os-X` | **Residential only** | `windows`, `macos`, `android` | `-os-windows` |
| `-carrier-X` | **Mobile only** | Specific carrier (e.g. `-carrier-dt`) | `-carrier-dt` |
| `-session-STRING` | All | Sticky session — same session ID returns the same exit IP for the session's lifetime. Use a random string per logical "user session" to implement rotation. | `-session-abc12345` |
| `-ip-A.B.C.D` | Zones with **dedicated IPs** only | Pin to a specific allocated IP | `-ip-1.2.3.4` |
| `-gip-NAME` | **Dedicated Residential or Mobile** only | Pin to a specific gIP group | `-gip-us_7922_fl_hollywood_0` |
| `-dns-local` / `-dns-remote` | All | `remote` = resolve DNS at the proxy peer (default for residential); `local` = resolve on super proxy | `-dns-remote` |
| `-const` | Residential, Mobile | Bind to the same peer; if peer is unavailable, return 502 "no peer available" instead of switching | `-const` |
| `-direct` | All | Force the request from the super proxy itself (skip peer routing). Rarely needed. | `-direct` |
| `-c_tag-VALUE` | All | Custom tag echoed back in response headers, for correlating req/resp at scale | `-c_tag-job42-row7` |

**Critical constraint**: Datacenter and ISP zones only support **country** targeting. State, city, zip, ASN, OS, and carrier targeting are Residential/Mobile-only. Don't generate code that puts `-city-` on a DC or