grok-register: a Python toolkit for batch Grok account registration

What grok-register automates, and for whom

The repository automates one narrow job: walking a real Chromium or Chrome instance through the Grok registration page, from opening the signup URL to obtaining an SSO cookie. Everything else in the project exists to make that loop repeatable at batch scale.

The README frames the audience explicitly. It describes the project as a Python tool for automation research, test environment validation and personal study, and carries an important notice asking users to respect the target site's terms of service and local law. That framing matters when you decide whether this belongs in your environment. It is not a hosted signup service and it does not create mailboxes for you; it consumes mailboxes you already have.

The concrete problem it addresses is the gap between a browser session that a human drives and a script that can run a hundred of those sessions with different email addresses, different proxies and a record of what succeeded. The project's answer is a single registration core (registration_flow.py, registration_browser.py) with three front ends on top: a Tkinter GUI, a CLI, and a local web server.

The registration pipeline and its post-processing stages

The README prints the per-account sequence as a text diagram: open the registration page, create a mailbox and submit it, fetch and fill the verification code, fill in the profile, obtain the SSO cookie, optionally enable NSFW, run the SSO risk screening on botFlagSource and policy, save the account, optionally write into grok2api, and optionally export CPA/OIDC credentials.

Two design decisions in that chain are worth calling out. First, grok2api token insertion and CPA/OIDC export are post-processing. The README states that a post-processing failure logs a warning but does not reclassify an already-saved account as a failed registration. Second, the SSO risk gate sits before the write. When it matches botFlagSource or policy=deny, the record is not written to the main account file and does not reach grok2api or CPA. The README also notes the gate is fail-open: network errors, HTTP exceptions or an unparsed risk field are logged as diagnostics and the account continues into the pool. That is a deliberate availability-over-strictness trade-off, and it means the gate is a filter, not a guarantee.

Persistence is incremental. Successful accounts are written to disk as they complete, and a failure to write the primary account result lands in a matching accounts_*.txt.pending.jsonl file that can be recovered later. Risk quarantines use a separate risk pending file so they never mix with ordinary account pending records.

Installing grok-register and running a first batch

The README requires Python 3.9 or newer, Chrome or Chromium, network access to the registration page and your chosen mailbox API, and Tkinter if you want the GUI. The sing-box dependency appears only if you use VLESS, VMess, Trojan, Hysteria2, TUIC or Shadowsocks nodes; HTTP, HTTPS and SOCKS keep using the project's native proxy implementation.

Clone the repository and create a virtual environment:

git clone https://github.com/AaronL725/grok-register.git
cd grok-register
python -m venv .venv

Activate it. The README gives both forms:

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

Then install the core dependencies and copy the config template:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cp config.example.json config.json

On Windows CMD the copy step is `copy config.example.json config.json`.

The README suggests starting from a minimal DuckMail configuration, which you can paste into config.json and extend afterwards:

{
  "email_provider": "duckmail",
  "duckmail_api_key": "",
  "register_count": 1,
  "proxy_mode": "auto",
  "proxy": "",
  "multi_thread_enabled": false,
  "cpa_export_enabled": false
}

Launch the GUI with `python grok_register_ttk.py`, or the WebUI after installing its extra requirements:

python -m pip install -r requirements-web.txt
python -m web.server

The WebUI listens on 127.0.0.1:8092 by default and offers bilingual configuration, start and stop controls, batch statistics, live logs, proxy pool node status, subscription parsing statistics, reload and manual test. The CLI accepts three equivalent forms: `python grok_register_ttk.py cli`, `python grok_register_ttk.py start`, or `python grok_register_ttk.py --cli`. It validates config.json, then waits for you to type `start` before anything runs; Ctrl+C requests a stop. The README advises using only one entry point at a time because all three share the same config.json and registration core.

Mailbox sources, proxy modes and the concurrency ceiling

Five mailbox sources are supported: DuckMail, YYDS, Cloudflare temporary mail, Cloud Mail, and an Outlook mailbox pool. The first four are temporary-mail style providers configured with API keys; YYDS needs at least one of yyds_api_key or yyds_jwt. Outlook is different in kind. The README is explicit that Outlook mode uses existing Outlook or Microsoft mailboxes readable over OAuth2 and does not create Microsoft accounts. You point it at a pool file whose lines follow an `email----password----clientId----refresh` layout, and that file path is the only thing stored in config.json.

Proxy handling has three operating modes: direct, single and pool, plus an auto mode where an empty proxy field means a direct connection. The pool can mix HTTP, HTTPS, SOCKS, VLESS, VMess, Trojan, Hysteria2, TUIC and Shadowsocks nodes, and the README lists health checks, cooldown, subscription refresh, fixed or rotating nodes, and a per-account stable proxy lease. That lease concept is the interesting part: rather than rotating a node mid-registration, an account keeps one proxy for its whole flow, which is the behaviour you want when the target site correlates sessions by IP.

Concurrency is capped at eight workers and is off by default. The README does not publish throughput numbers, so treat the worker count as a configuration knob rather than a promise. Raising it multiplies browser instances, mailbox API calls and proxy usage at the same time, and the README does not document how the tool behaves when a provider rate-limits you mid-batch.

Where grok-register is the wrong tool

The fail-open risk gate is the first limitation to internalize. If grok.com's risk fields cannot be fetched or parsed, the account proceeds into the pool anyway. A batch that looks clean may contain accounts the gate never actually evaluated, and the only trace is a diagnostic log line. If your workflow depends on the quarantine being complete, this design will not give you that.

Second, the project depends on browser automation against a live third-party signup page. DrissionPage drives a real Chromium instance, so any change to the page markup, the verification-code step or the SSO cookie issuance can break the flow without notice. Nothing in the README describes a versioned compatibility contract with the target site.

Third, the pending-recovery mechanism covers a specific failure: the primary account result could not be written. It is not a general job queue. The README does not document rollback, and it does not describe what happens to a mailbox that was consumed before the registration flow failed partway through.

Finally, if you only need a handful of accounts, or you want a managed service that handles mailboxes and proxies for you, this project is more moving parts than the task requires. It assumes you can supply and operate the email and network infrastructure yourself.

How it differs from general browser-automation frameworks

The obvious alternative is a general-purpose automation framework such as Playwright or Selenium: you write the signup script yourself against the same Chromium engine. The difference is scope, not capability. A general framework gives you a driver and a test runner and leaves mailbox creation, verification-code polling, proxy leasing, account persistence, pending recovery and downstream token export entirely to you. grok-register ships those as modules in the repository: mail_service.py, outlook_mail.py, outlook_mailbox_pool.py, proxy_pool.py, proxy_pool_v3.py, account_outputs.py, sso_risk.py and cpa_export.py.

That is a real trade. You get a working end-to-end pipeline on day one, and you inherit a pipeline whose assumptions were made for one target site. A Playwright script is more work to write and far easier to point at a different signup flow. If your actual goal is learning browser automation rather than producing accounts, the framework is the better teacher. If your goal is running the Grok flow repeatedly with different mailboxes and proxies, grok-register already contains the glue.

Licence, maintenance and what upgrading costs you

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the licence text's effect, not legal advice; if you plan to redistribute a modified version, read LICENSE in the repository rather than this summary. The README's own usage notice is separate from the licence and asks users to respect the target site's terms of service, local law and third-party service limits.

On maintenance, the last push to the default branch was on 2026-09-14, three days before this writing, and the repository is not archived. That is a recent commit history, but the repository has no published releases, so there is no tagged version to pin. Upgrading means pulling main and re-reading config.example.json for new keys, because the README states that structural validation runs at startup while feature-specific fields are only checked when a task begins. A config that opens fine in the GUI can still fail the moment you press start.

Dependency drift is the other cost. requirements.txt pins exact versions for most packages, including DrissionPage within a `>=4.1.1.2,<4.2` range, so the automation layer is bounded by design. When DrissionPage moves past 4.2, that pin becomes a decision rather than an automatic update.

Editorial conclusion

Adopt grok-register if you need a scriptable, self-hosted way to exercise the Grok signup flow against your own mailboxes and proxies, and you are comfortable reading config.example.json before running anything. Do not adopt it if you want a hosted service, if you cannot supply your own email infrastructure, or if you are not prepared to handle the account credentials it writes to disk. Before your first batch, verify three things: that Tkinter is present if you intend to use the GUI, that your chosen email provider's fields are filled in (the example config ships placeholder hostnames that will not work), and that sso_risk_gate_enabled is set the way you want, since it defaults to true and quarantines SSO records that hit botFlagSource or policy=deny into sso_risk_rejected.txt rather than the main account file.

Frequently asked questions

Official sources

1. AaronL725/grok-register on GitHub
2. Issues
3. License: MIT
4. README