zhangkai208/grok-register-panel

Purpose and entry points

This is a Python-based Grok/xAI account registration automation system with a local authenticated control panel. The main operator entry point is webui/monitor.py, serving a localhost panel on port 8787. Registration can also run from CLI batch entry points: run_batch_headless.py, run_until_100.py, and batch_supervisor.py.

Control panel and orchestration

The panel manages registration jobs, worker processes, runtime status, provider configuration, proxy configuration, blacklists, and recovery operations. webui/monitor.py is the HTTP/UI boundary; it delegates process lifecycle work to webui/process_utils.py and registration control to batch_supervisor.py. Authentication and local-runtime security are handled by webui/security_utils.py.

Registration workflow

register_flow.py is the core registration state machine: it coordinates browser-driven signup, email verification, and credential output. Browser abstraction is split between browser_session.py and camoufox_adapter.py, allowing the flow to drive the Camoufox browser runtime rather than directly coupling all registration logic to browser APIs. cloudflare.py and connectivity.py support network/challenge and reachability concerns around this flow.

Batch execution boundary

batch_supervisor.py manages concurrent or repeated registration workers and isolates job execution from the web process. run_batch_headless.py is the primary headless worker launcher, while run_xvfb_smoke.py supports Linux/Xvfb browser execution validation. This separation enables the panel to supervise subprocesses rather than executing browser automation inside its HTTP request lifecycle.

Email-provider subsystem

Email acquisition and verification-code retrieval are provider-pluggable through email_providers/__init__.py and email_providers/common.py. Concrete backends include Cloudflare, DuckMail, Mailnest, MoEmail, and others under email_providers/. The Cloudflare provider (email_providers/cloudflare.py) connects to a separately deployed Cloudflare Worker API backed by Cloudflare Email Routing and D1, so that infrastructure is external to this repository.

Persistent operational state

The panel persists editable operational settings through store modules: webui/email_provider_store.py, webui/email_domain_store.py, webui/proxy_store.py, and webui/blacklist_store.py. These form the boundary between panel-managed configuration/state and worker consumption. Runtime outputs and sensitive artifacts are organized in accounts/, grok2api_auth/, cpa_auth/, and log/; secure_files.py protects sensitive file handling.

Authentication artifact conversion and recovery

After successful account/session acquisition, sso_to_auth_json.py converts SSO/session material into auth JSON artifacts. Recovery paths are exposed through webui/recovery_ops.py, with related registration/SSO logic in register_flow.py. These artifacts are intended for downstream API use rather than being only browser-session state.

Runtime and deployment

The project runs on Python with dependencies in requirements.txt and requires Camoufox browser assets. It supports native Windows and Linux; Linux-specific service deployment is represented by deploy/grok-register-panel.service.example. Production hardening and permission controls are documented/implemented through HARDENING_ROOTS.md, scripts/harden_runtime_permissions.py, and DEPLOYMENT.md. External dependencies include xAI/Grok web endpoints, proxy services, email-provider APIs, and optionally Cloudflare Workers, Email Routing, and D1.