# How to Configure Residential Proxy Geolocation for Auth Cookie Sync

> Configure residential proxy geolocation for auth cookie sync using the cookie-sync script. Pass the --proxy flag to route syncs through specific locations and prevent IP rejection.

- Repository: [browserbase/skills](https://github.com/browserbase/skills)
- Tags: how-to-guide
- Published: 2026-05-01

---

**Pass the `--proxy "City,State,Country"` flag to the `cookie-sync` script to route authentication cookie synchronization through a residential proxy matching your local geolocation, preventing IP-based rejection of session tokens.**

When synchronizing authentication cookies from your local Chrome instance to a Browserbase persistent context, the `cookie-sync` skill in the **browserbase/skills** repository ensures sites accept your session by matching the proxy location to your original login IP. Without this geolocation alignment, websites may invalidate auth tokens when detecting requests from disparate geographic regions during the sync operation.

## Why Geolocation Matching Prevents Auth Failures

Sites often validate sessions by comparing the IP location at login versus subsequent requests. When you export cookies locally and import them into a cloud browser, a mismatch between your residential IP and the cloud datacenter IP triggers security flags. The **residential proxy** feature solves this by routing the initial cookie injection through an IP address physically located near your specified city and state, making the sync operation appear to originate from your local network.

## How the `--proxy` Flag Configures Session Geolocation

The residential proxy configuration flows through three distinct phases in `skills/cookie-sync/scripts/cookie-sync.mjs`:

### Argument Parsing and Validation

The `parseArgs()` function extracts the `--proxy` flag and validates the location string format. It expects `"City,State,Country"` where state is a 2-letter code and country defaults to `US` if omitted.

```javascript
// in skills/cookie-sync/scripts/cookie-sync.mjs
else if (args[i] === '--proxy' && args[i + 1]) {
  const parts = args[++i].split(',').map(s => s.trim());
  if (!parts[0] || !parts[1]) {
    console.error('Error: --proxy requires "City,State,Country" (e.g. "San Francisco,CA,US")');
    process.exit(1);
  }
  result.proxy = { city: parts[0], state: parts[1], country: parts[2] || 'US' };
}

```

### Session Creation with Proxy Parameters

When instantiating the Cloud Stagehand client, the parsed proxy object is injected into `browserbaseSessionCreateParams` under the `proxies` field. Browserbase then launches the session through its residential proxy network, applying the requested `geolocation` constraints.

```javascript
const cloud = new Stagehand({
  env: 'BROWSERBASE',
  apiKey: API_KEY,
  disableAPI: true,
  browserbaseSessionCreateParams: {
    browserSettings,
    ...(CLI.proxy && {
      proxies: [{ type: 'browserbase', geolocation: CLI.proxy }],
    }),
  },
  ...
});

```

### Cookie Injection Through Proxied Context

The temporary session receives the exported cookies while running through the specified residential proxy. Because the request originates from the matching geolocation, authentication tokens remain valid. Once injected, the persistent context stores these cookies independently of the proxy session, allowing subsequent `browse` commands to reuse the authenticated state without maintaining the proxy connection.

## Practical Configuration Examples

### Sync All Cookies with Basic Geolocation

Run the sync operation through a San Francisco residential proxy to match West Coast auth sessions:

```bash
node skills/cookie-sync/scripts/cookie-sync.mjs \
  --proxy "San Francisco,CA,US"

```

### Filter Domains and Enable Stealth Mode

Sync only specific domains while enabling advanced stealth protections and routing through a New York proxy:

```bash
node skills/cookie-sync/scripts/cookie-sync.mjs \
  --domains github.com,google.com \
  --stealth \
  --proxy "New York,NY,US"

```

### Refresh Existing Context with Consistent Location

Maintain geolocation consistency when refreshing cookies in an existing context by reapplying the same proxy settings:

```bash

# Initial sync creates context

CTX=$(node skills/cookie-sync/scripts/cookie-sync.mjs \
  --proxy "Austin,TX,US" | grep -o 'ctx_[a-z0-9]\+')

# Refresh same context with identical geolocation

node skills/cookie-sync/scripts/cookie-sync.mjs \
  --context $CTX \
  --proxy "Austin,TX,US"

```

## Summary

- The ** `--proxy` flag** accepts location strings in `"City,State,Country"` format to configure residential proxy geolocation.
- In `skills/cookie-sync/scripts/cookie-sync.mjs`, the proxy parameter is parsed into a `geolocation` object and passed to `browserbaseSessionCreateParams`.
- Residential proxies prevent auth cookie rejection by aligning the sync operation's IP address with your local login location.
- Context persistence means you only need the proxy during the initial sync; subsequent browsing reuses the authenticated session without proxy overhead.

## Frequently Asked Questions

### What format does the `--proxy` flag require?

The flag requires a comma-separated string in the format `"City,State,Country"`, where **State** is a 2-letter code and **Country** defaults to `US` if omitted. For example: `"Boston,MA,US"` or `"London,,GB"`.

### Do I need to configure the proxy for every cookie sync operation?

You must specify the proxy during the initial sync to prevent geolocation mismatches. When refreshing cookies in an existing context using the `--context` flag, you should reuse the same proxy location to maintain consistency, though the persistent context itself stores the authentication state independently.

### Why does cookie synchronization fail without residential proxy geolocation?

Websites validate session integrity by comparing the IP address used during login with subsequent requests. When your local Chrome exports cookies from your residential IP but the sync injects them from a cloud datacenter IP in a different region, security systems flag this as potential session hijacking and invalidate the tokens.

### Which source file handles the proxy configuration logic?

The proxy parsing and session injection logic resides in `skills/cookie-sync/scripts/cookie-sync.mjs`, specifically within the `parseArgs()` function (around lines 47-53) and the Cloud Stagehand instantiation block (around lines 74-78).