k12-reg: a local console for email pools, K12 workspace joins and Sub2API import

What k12-reg automates, and the operator it assumes

k12-reg, published as the package ai-gpt-k12, is a locally run task console. The README describes it as managing an email pool, a K12 workspace join flow, Sub2API import, AT liveness checks and repair, and account JSON export. Those are the five moving parts. Nothing in the README suggests a hosted service, a hosted control plane, or any account system of its own.

The audience is narrow and technical. You need Node.js 20 or newer (22+ suggested), npm 10+, network access to the services involved, and an HTTP or SOCKS proxy if your environment needs one. You also need a Sub2API service address and its admin credentials, because the console imports accounts there. If you do not already run Sub2API, the sub2apiUrl, sub2apiEmail and sub2apiPassword settings have nothing to point at.

The README opens with a warning that reads more like a terms-of-use boundary than a disclaimer: the project is published as an open source technical example and local automation tool, and users confirm their own scenario is legal and compliant and carry the risk. That framing is honest about what the software is. It is a driver for a pipeline you assemble, not a finished product with a support contract.

How the console is put together: one process, two ports, per-tenant data

The repository layout shows a server/ directory, a src/ directory, index.html and vite.config.ts. The package.json scripts confirm the split: npm run dev uses concurrently to start an API process (tsx server/index.ts) and a Vite frontend at the same time. The web console listens on http://127.0.0.1:5174/ and the API on http://127.0.0.1:8796/.

The isolation model is the most interesting design decision in the README. The browser generates a tenant ID in localStorage and sends it on every API request as the X-K12-Tenant-Id header. The backend then partitions configuration, email pool, tasks, top-up history and JSON output by that ID. Local use writes to data/, while browser tenants write to data/tenants/<tenantId>/. The stated consequence is that each online user keeps their own Sub2API, proxy and email pool settings instead of sharing one data/config.json. The stated cost is equally clear: clearing browser data or switching browsers produces a new tenant space, and whatever was under the old one is not reachable from the new ID.

That is a lightweight tenancy scheme, not authentication. The header is client-supplied, so anyone who can reach the API and guess or observe a tenant ID is inside that tenant's data. For a localhost console that is a reasonable trade. For anything exposed on a network it is the thing to think about first.

Installing k12-reg and running a first batch

The README gives two commands for setup. Run them from the repository root, with Node 20 or newer active.

npm install
npm run dev

After that, the console should be reachable at http://127.0.0.1:5174/ and the API at http://127.0.0.1:8796/. The README does not promise a specific startup banner, so treat a responding page on 5174 as the signal that both processes came up.

For a production-style run, the README documents a build step, and package.json adds a start script that runs the server directly.

npm run build
npm start

The first real use is configuration, not task creation. Open the console, click Settings, and fill in what the run needs. The README lists the keys; the ones that matter for a first pass are the proxy, the workspace IDs, the concurrency, and the Sub2API block. The README states configuration is saved from the Settings page and written at runtime to data/config.json, with config.json kept for compatibility with older flows. The configuration table names defaultProxyUrl, workspaceIds, taskConcurrency, runWorkspaceJoin, runSub2Api, sub2apiNoRtMode, sub2apiUrl, sub2apiEmail, sub2apiPassword, smsBowerMailEnabled, gmailMailProvider, jsonOutDir and jsonOutFormat, with gmailMailProvider accepting smsbower or emailnator and jsonOutFormat accepting sub2api or cpa.

Then import an email pool, or enable dynamic Gmail intake through smsBowerMailEnabled with gmailMailProvider set to smsbower or emailnator. Set the task count and concurrency, start the batch, and watch the task list for status and logs. The README notes tasks can be cancelled, retried, and that failed tasks can be cleaned up, with paginated logs.

The failure modes the README admits to

Four known errors are documented, and they are worth reading before you write any retry logic.

EmailOtpValidate wrong_email_otp_code means OpenAI judged the submitted email code wrong. The README attributes this to the code source returning an old message, a six-digit number from an advertisement, or an expired code. The practical implication is that a generic inbox is a bad code source, and that the pool's quality determines the error rate more than the tool does.

Stalling at accounts.google.com is the more structural one. The README says that when OpenAI routes an email to Google OAuth login, the current tool does not log into Google accounts automatically. There is no workaround documented. The instruction is to switch to an email that can go through the email-code flow. This is a hard boundary, not a bug to be patched around by configuration.

CreateAccount HTTP 500 Request timeout is described as an OpenAI-side timeout, usually remote instability, a slow proxy or excessive concurrency. Retry or lower taskConcurrency. Finally, cancellation is not instantaneous: the README explains that if a task is mid-request it waits for the request to return or time out before finishing the cancel. If you build a supervisor around this, do not assume a cancelled task has stopped the moment you ask.

The risk section adds the operational ones: third-party rule changes can break the flow, the registration, login, code intake, proxy and import behaviours may trigger risk controls, and third-party APIs, mailboxes, proxies and Sub2API can leak, fail or cost money. Locally stored tokens, cookies, refresh tokens and account JSON are called out as a disclosure risk.

Where k12-reg is the wrong tool

If you need Google account automation, stop here. The README states plainly that the tool does not log into Google accounts automatically and that affected emails should be swapped out. A project that solves that problem is a different project.

If you need a shared, multi-operator deployment with real access control, the X-K12-Tenant-Id scheme will not carry you. The tenant ID is generated in the browser and travels as a header; the README describes isolation, not authentication. There is no documented user model, no roles, no session expiry. The README does not document rollback of a tenant, either, so a misconfigured batch has no described undo beyond deleting files yourself.

If you need a managed service that registers accounts for you, this is the opposite shape. It is a local console with no homepage in the repository metadata and no hosted endpoint. You supply the proxy, the mailboxes, the workspace IDs and the Sub2API instance.

And if you want something you can point at production traffic without review, the licence and disclaimer push the other way. The README asks users to confirm their own legal and compliance position and states the authors accept no responsibility for account loss, service bans, data leaks, cost or legal disputes.

Alternatives and the difference in approach

For the email side, the README itself points at two providers it integrates with rather than treating as competitors: SMSBower and Emailnator. The distinction is architectural. k12-reg does not implement code retrieval; it delegates to a provider, selected by gmailMailProvider, or to a plain code URL, or to manual entry. If you already have a mailbox provider that works, you can point the tool at it instead of adopting the built-in channels. If you want a self-contained system with its own mailbox infrastructure, this is not that.

For the browser-automation layer, the alternative is a general automation framework. The dependency list shows playwright-core and chromium-bidi, so the project drives a browser through the Chrome DevTools protocol and also uses undici and fetch-cookie for HTTP-level work. A general-purpose browser automation stack gives you the same primitives with no opinion about K12 workspaces, email pools or Sub2API. You would write the join flow, the code polling and the export yourself. k12-reg is the opinionated version of that work, and the price of the opinion is that you inherit its flow assumptions, including the Google OAuth dead end.

For the storage and import side, the alternative is your own script against the Sub2API API. The README says the console performs OAuth import, a noRT direct mode, liveness checks and AT repair, and writes account JSON in sub2api or cpa format to jsonOutDir. If your Sub2API instance already has a working import path in your own tooling, the console's value is the queue, the retry and the log view around it, not the API call.

Maintenance, licence and what upgrading costs

The repository is not archived, and the last push was on 2026-07-04. That is roughly two and a half months before the date this review was written, so the codebase has moved recently, but the README does not describe a release process and no releases were retrieved. Version 0.1.0 in package.json is consistent with an early project. Treat the version as a signal: APIs and config keys in a 0.x project can change without a migration note, and the README documents config.json only as a compatibility file for older flows, which implies the config surface has already shifted at least once.

Upgrade cost is mostly environmental. The project pins ranges for playwright-core, undici, vite, vue and tsx, and the build runs vue-tsc --noEmit before vite build, so a type error blocks the build. The contribution notes ask for npm run build before submitting. There is no documented migration path between versions, so the practical upgrade procedure is to diff your data/config.json against the configuration table after pulling.

Licensing is MIT, stated in the README and present as LICENSE in the repository root. MIT permits use, copying, modification, merging, publication, distribution, sublicensing and sale, provided the copyright and permission notice are retained, and the software is provided as is with no warranty. That is permissive and standard. It says nothing about whether your use of the third-party services the tool talks to is permitted, and the README separates those concerns deliberately. This is not legal advice; the compliance question lives with the services, not the licence.

Editorial conclusion

Adopt k12-reg only if you already operate the surrounding pieces it assumes: a Sub2API instance, a proxy, and email accounts you are authorised to automate. Skip it if you need a hosted multi-tenant registration service or a tool that logs into Google accounts, because the README states the tool does not do the latter and routes around it instead. Before running anything, verify that data/config.json and config.json are covered by .gitignore, run git status --short --ignored, and confirm your workspaceIds values are the ones you actually own.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. lxh77721/k12-reg on GitHub
4. README