Introduction

GeekEZ Browser is a specialized anti-detect browser built on Electron and Puppeteer, with Xray-core integrated at the core. It is designed to solve multi-account association problems for cross-border e-commerce (TikTok, Amazon, Facebook, Shopee, etc.) by implementing deep system-level fingerprint spoofing.

Advanced Features

Hardware Randomization

  • Random CPU Cores (4/8/12/16)
  • Random Memory (4/8/16 GB)
  • This ensures every profile looks like a unique physical device.

WebRTC & IP Leak Protection

Forces disable_non_proxied_udp policy to physically block local IP leaks via WebRTC, ensuring only your proxy IP is visible.

Xray Network Engine

Fully supports VLESS, VMess, Trojan, Shadowsocks (including SS-2022).

Chain Proxy Architecture

[Local] -> [Pre-Proxy] -> [Profile Proxy] -> [Target]

This architecture hides your real IP from the final proxy provider, adding an extra layer of anonymity.

Important Warning

If your local machine is already using a TUN proxy, do not enable pre-proxy, or the proxy chain may fail.

Installation

Please verify your system requirements before installation.

macOS Notice

If you see "App is damaged", run this command in Terminal:

sudo xattr -rd com.apple.quarantine /Applications/GeekEZ\ Browser.app

Usage Guide

1) Quick Start

  1. Open GeekEZ Browser and click New Profile.
  2. Paste a subscription URL or a single proxy link.
  3. Click Generate & Save to create the profile.

2) Advanced Features

  • Pre-Proxy: supports Xray nodes or subscription links. If the profile proxy can reach the target site directly, you can leave this disabled. Warning: If your local machine is already using a TUN proxy, do not enable pre-proxy, or the proxy chain may fail.
  • Extensions: add unpacked extension folders in Settings → Extension Management.
  • Remote Debugging: opens a debugging port for the profile so Puppeteer or DevTools can connect.
  • UA & WebGL Modify: useful for fingerprint testing and compatibility debugging, but not guaranteed to bypass risk-control detection.
  • Custom Launch Arguments: append Chrome launch flags to a single profile, such as window, performance, or experimental options.
  • API Server: after enabling it in Advanced Settings, you can automate profile management through the local REST API.

Proxy Link Formats

All protocols support standard Xray-core formats such as VMess, VLESS, Trojan, and Shadowsocks.

Below are common HTTP and SOCKS examples:

HTTP / HTTPS Proxies

# With username and password
http://user:pass@1.2.3.4:8080

# Without username and password
http://1.2.3.4:8080

# HTTPS form (handled as an HTTP proxy)
https://1.2.3.4:8080

SOCKS Proxies

# Standard format (with username and password)
socks://user:pass@1.2.3.4:1080

# Username only (no password)
socks5://user@1.2.3.4:1080

# No authentication
socks5://1.2.3.4:1080

# v2rayN style (base64(user:pass))
socks://dXNlcjpwYXNz@1.2.3.4:1080#remark

# Plain-text shorthand (treated as SOCKS by GeekEZ Browser)
1.2.3.4:1080
1.2.3.4:1080:user:pass

Direct Mode (No Proxy)

Direct

When the proxy link is set to Direct, GeekEZ Browser does not start Xray for the profile and uses the local network directly.

FAQ

Q: Why is TikTok/Facebook still flagging my account?

A: Fingerprint isolation only protects device identity. You MUST use a high-quality Clean/Dedicated IP. Shared IPs are easily detected.

Q: White screen on startup?

A: Try setting Timezone to "Auto" in settings. Some sites (like Oracle) require precise time synchronization.

API 文档

GeekEZ Browser REST API 仅监听本地地址 127.0.0.1。请在 设置 → 高级设置 → API 服务 中启用。

通用说明

  • 所有 :idOrName 参数均支持环境 ID（UUID）或环境名称。
  • 列表接口支持按标签精确筛选：GET /api/profiles?tag=标签名。
  • 若开启“远程调试”，创建/更新返回中会包含 remoteDebugPort。
  • POST /api/profiles 与 PUT /api/profiles/:idOrName 支持 args 字段，写入后会永久保存到环境启动参数中。
  • GET /api/open/:idOrName 支持查询参数 args，仅对本次启动生效，不会修改环境内已保存的启动参数。
  • 如需在 URL 中传递带空格的启动参数，推荐使用 curl -G --data-urlencode，避免 URL 因空格报错。

创建环境（Create Profile）说明

POST /api/profiles 支持完整参数输入。

必须参数：name、proxyStr。

其余参数：不填时将自动按默认策略/随机策略生成。若不传 args，环境启动参数默认留空。

curl -X POST http://localhost:12138/api/profiles \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US-TikTok-01",
    "proxyStr": "socks5://1.2.3.4:1080",
    "args": "--start-maximized --disable-popup-blocking"
  }'

接口与示例

1) 查询运行状态 GET /api/status

curl http://localhost:12138/api/status

2) 查询环境列表 GET /api/profiles

curl http://localhost:12138/api/profiles

3) 按标签筛选环境 GET /api/profiles?tag=tiktok

curl "http://localhost:12138/api/profiles?tag=tiktok"

4) 查询单个环境详情 GET /api/profiles/:idOrName

curl http://localhost:12138/api/profiles/US-TikTok-01

5) 创建环境（完整参数示例） POST /api/profiles

curl -X POST http://localhost:12138/api/profiles \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US-TikTok-02",
    "proxyStr": "http://user:pass@1.2.3.4:8080",
    "tags": ["tiktok", "us"],
    "preProxyOverride": "default",
    "timezone": "America/New_York",
    "language": "en-US",
    "screen": { "width": 1920, "height": 1080 },
    "uaMode": "spoof",
    "browserType": "chrome",
    "browserMajorVersion": 136,
    "webglProfile": "win_nvidia_1650",
    "args": "--start-maximized --disable-popup-blocking"
  }'

6) 更新环境 PUT /api/profiles/:idOrName

curl -X PUT http://localhost:12138/api/profiles/US-TikTok-01 \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["tiktok", "us", "shop"],
    "language": "en-US",
    "args": "--start-maximized --disable-popup-blocking --disable-notifications"
  }'

说明：更新时如果不下发 args，则保持原有启动参数不变；若下发 "args": ""，则会清空该环境已保存的启动参数。

7) 删除环境 DELETE /api/profiles/:idOrName

curl -X DELETE http://localhost:12138/api/profiles/US-TikTok-01

8) 启动环境 GET /api/open/:idOrName

curl http://localhost:12138/api/open/US-TikTok-01

8.1) 启动环境并为本次追加临时启动参数 GET /api/open/:idOrName?args=...

curl -G \
  --data-urlencode "args=--start-maximized --disable-popup-blocking" \
  "http://localhost:12138/api/open/US-TikTok-01"

说明：这里的 args 只在本次启动生效，不会覆盖或修改环境里已经保存的 args/customArgs。

9) 停止环境 POST /api/profiles/:idOrName/stop

curl -X POST http://localhost:12138/api/profiles/US-TikTok-01/stop

10) 导出加密完整备份 GET /api/export/all?password=你的密码

curl "http://localhost:12138/api/export/all?password=123456"

11) 导出指纹 YAML GET /api/export/fingerprint

curl http://localhost:12138/api/export/fingerprint

12) 导入（YAML 或加密备份） POST /api/import

curl -X POST http://localhost:12138/api/import \
  -H "Content-Type: application/json" \
  -d '{
    "content": "这里填 YAML 文本或加密备份的 Base64 内容",
    "password": "加密备份时需要，YAML 可不填"
  }'