Camofox can route all browser traffic through a proxy server and automatically configure the browser fingerprint to match the proxy’s geographic location. This ensures consistent geolocation signals across all browser APIs.
Environment variables
Set these environment variables before starting the Camofox server:
| Variable | Description | Required |
|---|
PROXY_HOST | Proxy hostname or IP address | Yes |
PROXY_PORT | Proxy port number | Yes |
PROXY_USERNAME | Proxy authentication username | No |
PROXY_PASSWORD | Proxy authentication password | No |
Configuration
Local development
export PROXY_HOST=166.88.179.132
export PROXY_PORT=46040
export PROXY_USERNAME=myuser
export PROXY_PASSWORD=mypass
npm start
Docker deployment
docker run -p 9377:9377 \
-e PROXY_HOST=166.88.179.132 \
-e PROXY_PORT=46040 \
-e PROXY_USERNAME=myuser \
-e PROXY_PASSWORD=mypass \
camofox-browser
Fly.io deployment
fly secrets set PROXY_HOST=166.88.179.132
fly secrets set PROXY_PORT=46040
fly secrets set PROXY_USERNAME=myuser
fly secrets set PROXY_PASSWORD=mypass
fly deploy
Railway deployment
In the Railway dashboard:
- Go to your service → Variables
- Add:
PROXY_HOST = 166.88.179.132PROXY_PORT = 46040PROXY_USERNAME = myuserPROXY_PASSWORD = mypass
- Redeploy
How GeoIP works
When proxy configuration is detected, Camofox’s GeoIP feature automatically:
- Resolves the proxy’s exit IP address via geo-lookup
- Sets browser locale to match the IP’s country (e.g.,
en-GB for UK, de-DE for Germany)
- Sets timezone to match the IP’s region (e.g.,
Europe/London, America/New_York)
- Sets geolocation coordinates to match the IP’s city (latitude/longitude)
- Configures Camoufox fingerprint to align with the derived locale
This happens at browser launch time. All tabs created in the browser session inherit these settings.
Without proxy
If no proxy is configured, Camofox uses default US-based fingerprinting:
- Locale:
en-US
- Timezone:
America/Los_Angeles
- Geolocation: San Francisco, CA coordinates (37.7749, -122.4194)
Fingerprint consistency
GeoIP ensures that all geolocation signals exposed to websites are consistent:
| Browser API | Value Source |
|---|
navigator.language | Derived from proxy IP |
navigator.languages | Derived from proxy IP |
Intl.DateTimeFormat().resolvedOptions().timeZone | Derived from proxy IP |
navigator.geolocation.getCurrentPosition() | Derived from proxy IP |
HTTP Accept-Language header | Derived from proxy IP |
Do not override locale/timezone in the Playwright context when using GeoIP. Let Camoufox manage these settings automatically.
Proxy protocol
Camofox uses HTTP CONNECT tunneling (server.js:286-298):
const proxy = {
server: `http://${PROXY_HOST}:${PROXY_PORT}`,
username: PROXY_USERNAME,
password: PROXY_PASSWORD,
};
- HTTP proxies with CONNECT tunneling
- SOCKS5 proxies (if your proxy supports it)
- Basic authentication via username/password
Implementation details
Proxy config resolution
The buildProxyConfig() function (server.js:285-299) checks for proxy environment variables at startup:
function buildProxyConfig() {
const { host, port, username, password } = CONFIG.proxy;
if (!host || !port) {
log('info', 'no proxy configured');
return null;
}
log('info', 'proxy configured', { host, port });
return {
server: `http://${host}:${port}`,
username,
password,
};
}
PROXY_HOST or PROXY_PORT is missing, proxy is disabled.
Browser launch with GeoIP
When launching the browser (server.js:379-396), the proxy config is passed to Camoufox’s launchOptions():
const options = await launchOptions({
headless: true,
os: hostOS,
humanize: true,
enable_cache: true,
proxy: proxy,
geoip: !!proxy, // Enable GeoIP if proxy is set
});
browser = await firefox.launch(options);
geoip: !!proxy flag tells Camoufox to perform geo-lookup and configure fingerprinting.
Context creation without overrides
When creating browser contexts for sessions (server.js:432-443), the code checks if a proxy is configured:
const contextOptions = {
viewport: { width: 1280, height: 720 },
permissions: ['geolocation'],
};
// When geoip is active (proxy configured), camoufox auto-configures
// locale/timezone/geolocation from the proxy IP. Without proxy, use defaults.
if (!CONFIG.proxy.host) {
contextOptions.locale = 'en-US';
contextOptions.timezoneId = 'America/Los_Angeles';
contextOptions.geolocation = { latitude: 37.7749, longitude: -122.4194 };
}
const context = await browser.newContext(contextOptions);
Residential proxies
For best results, use residential proxies instead of datacenter proxies. Residential IPs are less likely to be flagged by anti-bot systems.
Recommended providers:
Rotating residential proxies are ideal for scraping multiple pages without getting rate-limited. Sticky session proxies are better for maintaining login state across requests.
Proxy rotation
Camofox does not rotate proxies automatically. Each browser instance uses a single proxy configuration for its entire lifetime.
For proxy rotation:
- Restart the browser with a new proxy config (not recommended - slow)
- Deploy multiple Camofox instances with different proxy configs behind a load balancer
- Use rotating proxies from your provider (proxy endpoint rotates IPs per request)
Option 3 is recommended. Most residential proxy providers support session-based rotation where each new TCP connection gets a new IP.
Debugging proxy issues
Connection failures
Symptoms: Browser fails to launch, all page loads timeout
Causes:
- Proxy host/port unreachable
- Firewall blocking outbound connections
- Proxy authentication failed
Fix: Test the proxy with curl:
This should return the proxy’s exit IP. If it fails, the proxy config is incorrect.
GeoIP mismatch
Symptoms: Browser locale/timezone don’t match proxy location
Causes:
- GeoIP database out of date
- Proxy IP is newly allocated and not in geo databases
- Context options override GeoIP settings
Fix: Ensure you’re not setting locale, timezoneId, or geolocation in the context options when using GeoIP.
Slow page loads
Causes:
- High latency proxy
- Proxy bandwidth throttling
Fix: Use a faster proxy or increase NAVIGATE_TIMEOUT_MS (default 30s).
Logging
Camofox logs proxy status at startup:
{"ts":"2026-02-28T10:00:00.000Z","level":"info","msg":"proxy configured","host":"166.88.179.132","port":46040}
{"ts":"2026-02-28T10:00:01.234Z","level":"info","msg":"launching camoufox","hostOS":"linux","geoip":true}
geoip: true, GeoIP is active.