How to Configure Residential Proxy Geolocation for Auth Cookie Sync

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.

// 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.

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:

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:

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:

# 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).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}