Configuration Options

This guide covers all available configuration options for the GoLogin SDK. Whether you need to set up proxies, customize fingerprints, or fine-tune browser behavior, you’ll find the complete reference here.

Basic Configuration

The simplest configuration only requires a profile name:

import { GoLogin } from '@gologin/sdk';

const gologin = new GoLogin({
  profileName: 'my-profile',
});

Full Configuration Reference

Here’s the complete list of configuration options:

interface GoLoginConfig {
  // Profile settings
  profileName: string;           // Required: Unique identifier for the profile
  createProfile?: boolean;       // Create profile if it doesn't exist (default: true)
  profilesDir?: string;          // Custom profiles directory

  // Browser settings
  executablePath?: string;       // Path to Chrome/Chromium executable
  headless?: boolean;            // Run in headless mode (default: false)
  args?: string[];               // Additional browser arguments

  // Proxy settings
  proxy?: ProxyConfig;           // Proxy configuration

  // Fingerprint settings
  fingerprint?: FingerprintOptions;

  // Platform settings
  platform?: 'windows' | 'macos' | 'linux';

  // Locale and timezone
  locale?: string;               // Browser locale (e.g., 'en-US')
  timezone?: string;             // Timezone (e.g., 'America/New_York')

  // Advanced options
  debug?: boolean;               // Enable debug logging
  autoClose?: boolean;           // Auto-close browser on stop (default: true)
}

Profile Configuration

Profile Name

The profile name is the unique identifier for your browser profile:

const gologin = new GoLogin({
  profileName: 'amazon-scraper-01',
});

Tip

Use descriptive names that indicate the profile’s purpose. This makes management easier when you have many profiles.

Custom Profiles Directory

By default, profiles are stored in ~/.gologin/profiles. You can customize this:

const gologin = new GoLogin({
  profileName: 'my-profile',
  profilesDir: '/path/to/my/profiles',
});

Auto-Create Profiles

Control whether profiles are created automatically:

// Create profile if it doesn't exist (default behavior)
const gologin = new GoLogin({
  profileName: 'new-profile',
  createProfile: true,
});

// Throw error if profile doesn't exist
const gologin = new GoLogin({
  profileName: 'existing-profile',
  createProfile: false,
});

Proxy Configuration

Configure proxies to mask your IP address and location:

interface ProxyConfig {
  type: 'http' | 'https' | 'socks4' | 'socks5';
  host: string;
  port: number;
  username?: string;
  password?: string;
}

HTTP/HTTPS Proxy

const gologin = new GoLogin({
  profileName: 'with-proxy',
  proxy: {
    type: 'http',
    host: 'proxy.example.com',
    port: 8080,
    username: 'user',
    password: 'pass',
  },
});

SOCKS5 Proxy

const gologin = new GoLogin({
  profileName: 'socks-profile',
  proxy: {
    type: 'socks5',
    host: '192.168.1.100',
    port: 1080,
  },
});

Rotating Proxies

For rotating proxy services, update the proxy config before each session:

const proxyList = [
  { type: 'http', host: 'proxy1.example.com', port: 8080 },
  { type: 'http', host: 'proxy2.example.com', port: 8080 },
  { type: 'http', host: 'proxy3.example.com', port: 8080 },
];

const gologin = new GoLogin({
  profileName: 'rotating-profile',
  proxy: proxyList[Math.floor(Math.random() * proxyList.length)],
});

Caution

When using proxies, ensure your timezone and locale settings match the proxy’s geographic location to avoid detection.

Fingerprint Configuration

Customize the browser fingerprint for advanced use cases:

interface FingerprintOptions {
  // Screen settings
  screen?: {
    width?: number;
    height?: number;
  };

  // WebGL configuration
  webgl?: {
    vendor?: string;
    renderer?: string;
  };

  // Canvas noise
  canvas?: {
    noise?: number;  // 0-1, amount of noise to add
  };

  // Audio fingerprint
  audio?: {
    noise?: number;  // 0-1, amount of noise to add
  };

  // Navigator properties
  navigator?: {
    userAgent?: string;
    platform?: string;
    languages?: string[];
    maxTouchPoints?: number;
  };
}

Custom Screen Resolution

const gologin = new GoLogin({
  profileName: 'custom-screen',
  fingerprint: {
    screen: {
      width: 1920,
      height: 1080,
    },
  },
});

Custom User Agent

const gologin = new GoLogin({
  profileName: 'custom-ua',
  fingerprint: {
    navigator: {
      userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
    },
  },
});

Caution

Manual fingerprint customization should be done carefully. Inconsistent values can trigger detection. Let GoLogin auto-generate consistent fingerprints unless you have specific requirements.

Platform Configuration

Set the target operating system for the profile:

const gologin = new GoLogin({
  profileName: 'windows-profile',
  platform: 'windows',  // 'windows' | 'macos' | 'linux'
});

The platform affects multiple fingerprint components:

• User agent string
• Navigator.platform value
• Screen resolution defaults
• WebGL renderer strings
• Taskbar/dock height calculations

Locale and Timezone

Configure geographic settings:

const gologin = new GoLogin({
  profileName: 'japan-profile',
  locale: 'ja-JP',
  timezone: 'Asia/Tokyo',
});

Common Locale/Timezone Combinations

Region	Locale	Timezone
US East	en-US	America/New_York
US West	en-US	America/Los_Angeles
UK	en-GB	Europe/London
Germany	de-DE	Europe/Berlin
Japan	ja-JP	Asia/Tokyo
Brazil	pt-BR	America/Sao_Paulo

Browser Configuration

Custom Executable Path

Use a specific Chrome/Chromium installation:

const gologin = new GoLogin({
  profileName: 'my-profile',
  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
});

macOS

executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'

Windows

executablePath: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'

Linux

executablePath: '/usr/bin/google-chrome'

Headless Mode

Run the browser without a visible window:

const gologin = new GoLogin({
  profileName: 'headless-profile',
  headless: true,
});

Note

Headless mode may be more easily detected by some sites. Use with caution for sensitive targets.

Additional Browser Arguments

Pass custom arguments to the browser:

const gologin = new GoLogin({
  profileName: 'custom-args',
  args: [
    '--disable-gpu',
    '--no-sandbox',
    '--disable-setuid-sandbox',
  ],
});

Debug Mode

Enable detailed logging for troubleshooting:

const gologin = new GoLogin({
  profileName: 'debug-profile',
  debug: true,
});

Debug mode outputs:

• Profile loading/saving events
• Fingerprint injection details
• Proxy connection status
• Browser launch arguments
• WebSocket connection info

Environment Variables

Configuration can also be set via environment variables:

Variable	Description	Default
GOLOGIN_PROFILES_DIR	Profiles storage directory	~/.gologin/profiles
GOLOGIN_EXECUTABLE_PATH	Chrome executable path	Auto-detected
GOLOGIN_DEBUG	Enable debug mode	false

export GOLOGIN_PROFILES_DIR=/data/profiles
export GOLOGIN_DEBUG=true

Configuration Precedence

When the same option is set in multiple places, precedence is:

1. Constructor options (highest priority)
2. Environment variables
3. Default values (lowest priority)

// Constructor options override environment variables
const gologin = new GoLogin({
  profileName: 'my-profile',
  profilesDir: '/custom/path',  // Takes precedence over GOLOGIN_PROFILES_DIR
});

Best Practices

1. Match Location Settings

Always align proxy, timezone, and locale:

// Good: All settings match US East location
const gologin = new GoLogin({
  profileName: 'us-east-profile',
  proxy: { type: 'http', host: 'us-east.proxy.com', port: 8080 },
  timezone: 'America/New_York',
  locale: 'en-US',
});

2. Use Consistent Platform

Match the platform to your fingerprint expectations:

// Good: Windows platform with Windows-compatible settings
const gologin = new GoLogin({
  profileName: 'windows-profile',
  platform: 'windows',
  fingerprint: {
    screen: { width: 1920, height: 1080 },  // Common Windows resolution
  },
});

3. Avoid Over-Customization

Let GoLogin generate sensible defaults:

// Good: Minimal configuration, let SDK handle details
const gologin = new GoLogin({
  profileName: 'simple-profile',
  platform: 'windows',
  locale: 'en-US',
  timezone: 'America/New_York',
});

// Avoid: Over-specifying everything increases detection risk

Next Steps

• Quick Start Guide — Launch your first session
• Profile Management — Create and manage browser profiles
• Proxy Rotation Guide — Advanced proxy strategies