Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• setup.js
• main.js
• renderer.js
• index.html
• README_zh.md
• CHANGELOG_v1.2.3.md

GeekEZ Browser is an anti-detect browser built on Electron and Puppeteer, designed for e-commerce operators and multi-account management. It focuses on isolating browser fingerprints, network environments, and local storage to prevent account association on platforms like Amazon, TikTok, and Facebook. The core of its networking is powered by an integrated Xray-core, providing support for a wide range of proxy protocols.

This guide provides instructions for setting up and running the GeekEZ Browser from its source code. It covers the installation process, application architecture, and build procedures. The project emphasizes a "Native Consistency" strategy, avoiding easily detectable JavaScript hooks to bypass advanced security measures like Cloudflare Turnstile.

Sources: README.md, README_zh.md

Installation

There are two primary methods for getting started with GeekEZ Browser.

Option 1: Download Release (Recommended)

The simplest way to use the application is to download the pre-built installer for your operating system from the project's Releases page.

• Windows: GeekEZ Browser Setup 1.2.3.exe

Sources: README.md:80-82

Option 2: Run from Source

For developers who wish to run the application directly from the source code, certain prerequisites and steps are required.

Prerequisites

• Node.js (version 16 or higher)
• Git

Sources: README.md:85

Step 1: Clone the Repository

First, clone the project repository to your local machine and navigate into the directory.

git clone https://github.com/CurtisLu1/GeekezBrowser.git
cd GeekezBrowser

Sources: README.md:88-91

Step 2: Install Dependencies

Run the npm install command to download and install the project's dependencies. This command also triggers a postinstall script defined in package.json.

npm install

The postinstall script, located at setup.js, automates the download of necessary binaries: Xray-core and a specific version of the Chrome browser for Puppeteer.

Sources: README.md:94, package.json:8

The setup script performs the following actions:

1. Network Check: It checks for global internet access to decide whether to use a download mirror.
2. Xray-core Download: It downloads the correct Xray-core binary (v24.11.30) for your operating system and architecture. It uses a proxy (https://gh-proxy.com/) if a direct connection to GitHub is not detected.
3. Chrome Download: It uses @puppeteer/browsers to download a specific Chrome build (129.0.6668.58) into the resources/puppeteer directory. It uses a mirror (https://npmmirror.com/mirrors/chrome-for-testing) if required.
4. Extraction and Cleanup: The script extracts the downloaded archives and sets the necessary permissions for the binaries.

The diagram below illustrates the postinstall workflow.

Step 3: Run the Application

Once all dependencies and binaries are installed, start the application using the npm start command.

npm start

This command executes electron ., which starts the Electron main process defined in main.js.

Sources: README.md:100, package.json:7

Application Architecture

GeekEZ Browser is an Electron application with a clear separation between the main process and the renderer process. It integrates external tools like Xray-core and Puppeteer to provide its core functionality.

This diagram shows the high-level components and their interactions within the GeekEZ Browser system.

Sources: main.js, renderer.js, index.html, setup.js

Key Components

Component	File / Path	Description
Main Process	main.js	The application's entry point. It manages the browser window, handles IPC events, and orchestrates the Xray and Puppeteer processes.
Renderer Process	index.html, renderer.js	The user interface of the application. It's responsible for displaying profiles, handling user input, and communicating with the main process.
Xray-core	resources/bin/	A networking tool that provides proxy capabilities. It is spawned by the main process for each browser profile.
Puppeteer	node_modules/puppeteer	A Node library used to control a headless or headed Chrome instance. It is used to launch and manage the isolated browser environments.
Chrome Binary	resources/puppeteer/	A specific version of Chrome downloaded by the setup.js script, which is controlled by Puppeteer.

Sources: main.js, renderer.js, index.html, setup.js, package.json

Profile Launch Sequence

When a user clicks the "Launch" button for a profile, a sequence of events is triggered across different components of the application.

The following diagram illustrates the profile launch process.

Building for Production

The project can be packaged into distributable installers for Windows, macOS, and Linux using electron-builder. The necessary scripts are defined in package.json.

Script	Command	Description
build:win	electron-builder --win --x64	Builds a 64-bit installer for Windows.
build:mac	electron-builder --mac --arm64 --x64	Builds a universal DMG for macOS (ARM64 & x64).
build:linux	electron-builder --linux	Builds an AppImage for Linux.

Sources: package.json:9-11, README.md:118-127

The build configuration in package.json specifies that the resources/bin (Xray-core) and resources/puppeteer (Chrome) directories are included as extraResources in the final packaged application.

Sources: package.json:23-35

Platform Compatibility

The browser has been tested and rated for safety on several major e-commerce and social media platforms. The effectiveness of the tool is highly dependent on using high-quality residential IP addresses.

Platform	Rating	Notes
TikTok	✅ Safe	Canvas noise prevents device association. Requires clean residential IP.
Facebook	✅ Safe	WebDriver automation flags are stripped. Avoid high-frequency automation.
Shopee	✅ Safe	Provides a stable fingerprint for seller center operations.
Amazon (Buyer)	✅ Safe	Sufficient isolation for buyer and reviewer accounts.
Amazon (Seller)	✅ Safe	Usable for main accounts with a high-quality residential IP and a fixed environment.
Cloudflare	✅ Pass	Bypasses Turnstile due to the native injection strategy.

Sources: README.md:105-115, CHANGELOG_v1.2.3.md:47-60