The duwqijlk/muse-protocol repository trended on GitHub in mid-November 2026 with roughly 1,700 stars by documenting Meta Muse.ai registration and invite-code redemption as pure HTTP Python, without a browser. The README is effectively a protocol map: CSRF restart, OTP send and confirm, register-completion, auth.meta.com hatch bootstrap, dynamic disclosure text for accept-tos, vm/wake, and invite-code/redeem endpoints.
explainx.ai covers it because Meta Muse sits in the frontier agent conversation next to Microsoft Muse naming collisions readers confuse — this repo is about Meta's muse.ai agent onboarding (see the site's terms), not Microsoft's image models.
What the protocol implements
The musepy/ package breaks into modules the README names:
| Module | Role |
|---|---|
client.py | End-to-end register plus redeem |
runner.py | Multi-account batch with sticky proxies and budgets |
otp.py | Polls OTP endpoints after send-otp |
falco.py / caa.py | Optional telemetry mirrors of front-end analytics |
Documented HTTP sequence (abbreviated):
GET /for cookiesPOST /api/auth/native/restartwith{"resume": false}— not an empty body- OTP send and confirm; confirm must include
supports_muse_link_transparency: true register-completionwith first_name as given name and last_name as family name (README warns names are swapped versus English intuition)POST auth.meta.com/hatch/session/bootstrap/following redirects until muse.ai returns HTML with disclosureVersionPOST /api/hatch/accept-tosusing server disclosure text, not hard-coded stringsGET /api/hatch/invite,POST /api/hatch/vm/wake, thenPOST /api/hatch/invite-code/redeem
hatch_sess cookie from register-completion (~886 characters per README) becomes the credential for hatch APIs.
Batch runner semantics and abuse surface
example_batch.py and runner.py document worker pools, sticky proxies, max_per_ip, and otp_file lines pairing emails with remote OTP JSON URLs — automation at scale.
The README's usage declaration (translated summary): personal, non-commercial research only; no MIT license; obey Muse.ai terms and local law. A Telegram community link appears in README; explainx.ai does not endorse using the tooling to farm invites.
ToS and data risks readers should weigh
- Automating OTP flows may violate Meta terms even when technically feasible.
- Proxy rotation to evade geo gates (
isGeoGated,waitlist) can constitute circumvention depending on jurisdiction and contracts. - Batch OTP URLs imply third-party access to email inboxes — a serious credential exposure if misconfigured.
- Invite code pools encourage gray-market trading Meta may ban.
If your security team models agent onboarding abuse, compare with explainx.ai's token fraud coverage — different product, same growth-hacking via API shape.
Technical footguns the README documents
Developers mirrored on Hacker News often share these pitfalls:
- Birth year 403: birthdays implying under-18 fail; README notes flipping year within same session can flip 403 to 200 — a signal that server-side age checks are brittle.
- Redeem without vm/wake: returns Japanese error text implying invalid code when the code exists.
- Telemetry optional: falco and caa-events posts do not affect registration success — useful when diffing minimal versus browser-faithful clients.
How this compares to legitimate Muse access
Ordinary users should use official Muse.ai apps and invites, not HTTP clones. Researchers studying invite economics can read muse-protocol as documentation of scarcity mechanics: dynamic disclosures, waitlist destinations, and 30-use invite caps listed in the README's redemption table.
For Meta agent strategy, pair this with Cursor House report on Chinese open-weight models — different topic, same platform gating theme.
Endpoint-by-endpoint notes for security reviewers
Security teams auditing mobile-first agent launches should map muse-protocol's sequence against your OWASP mobile checklist:
- CSRF tokens on
native/restartimply session fixation risks if clients mishandle cookies. - OTP endpoints are credential stuffing magnets when exposed to scripted send volumes.
- register-completion returns frl_access_token artifacts — treat logs as secret-bearing.
- hatch/bootstrap redirects across auth.meta.com and muse.ai enlarge phishing surface if users learn to click through unvetted links mimicking the chain.
None of this argues the repo is malware; it documents production behavior Meta ships to browsers. Defenders need the same map attackers use.
Invite economics and redemption table
The README's redemption reasons translate product rules into API JSON:
| reason | Meaning for growth teams |
|---|---|
| redeemed | Successful single use |
| already_redeemed | One invite per account enforced |
| used_up | Code hit ~30 redemption cap |
| invalid | Wrong code or missing vm/wake |
Scarcity engineering — caps, waitlists, geo gates — is why explainx.ai covers muse-protocol as infrastructure news, not a hacker how-to. Product managers studying ChatGPT Dots limits will recognize the pattern.
Why stars spiked on GitHub anyway
Stars climbed to ~1,700 in a week because:
- Invite bottlenecks create demand for visibility into gates.
- Reverse engineers publish maps faster than official docs during betas.
- Researchers want reproducible clients without browser automation fragility.
GitHub trending is not Meta endorsement. Stars do not imply license to automate against terms.
Responsible use for legitimate researchers
Acceptable uses might include comparing disclosure text versions, measuring latency, or verifying consent UX — always with test accounts you own and legal review. Unacceptable uses include mass account farming, reselling invites, or evading geo restrictions to bypass waitlists.
Document findings to Meta through official bug bounty channels when security issues appear — the README's telemetry section shows falco and caa-events endpoints attackers might spam; vendors need rate limit data.
Comparing Muse onboarding to other gated agent betas
| Product pattern | Muse (per README) | Builder takeaway |
|---|---|---|
| Invite codes | Redeem with caps | Gray markets emerge when stars spike on protocol repos |
| Geo gating | waitlist / isGeoGated | VPN instructions in README are a compliance red flag |
| Session bootstrap | Meta auth redirect chain | OAuth complexity aids attackers mimicking login |
| VM wake | Required before redeem | Hidden state ties "valid code" to client behavior |
ChatGPT Dots and Claude consumer tiers use different gating mechanics; muse-protocol is a case study in how much state hides behind a slick UI.
Engineering ethics for open documentation
Publishing HTTP maps educates defenders and abusers simultaneously. The muse-protocol README tries to narrow scope with non-commercial language. GitHub hosts the repo anyway, so Meta's response (rate limits, legal notices, API changes) will determine whether the map stays accurate.
If you maintain a similar repo, add RESPONSIBLE.md with bug reporting paths and explicit prohibitions on invite farming — the README partially does this; enterprises should still run legal review.
Walkthrough: single-account register smoke test
The README's example_register.py path expects config.json from config.example.json with email and optional proxy settings. A responsible tester using only their own email:
- Copies config template and fills personal email.
- Runs pip install from
requirements.txt. - Executes single-account script, not batch runner.
- Stops at region_waitlist without attempting VPN circumvention.
- Deletes local cookies and tokens afterward.
The included test_onboarding_smoke.py and test_runner_smoke.py run offline mocks — good CI templates if you fork for security research, not production signup farms.
Cookie and session hygiene
hatch_sess length (~886 characters per README) makes it a high-value bearer token. Do not commit configs with live cookies to public repos. Rotate emails used in tests; Muse may rate-limit or ban accounts that trigger batch runner stop conditions the README documents (region_waitlist, server_rejected, transport_error counters in batch_summary JSON).
JP node note in README
The README mentions JP nodes for registration without card binding — explainx.ai does not verify that claim against Meta policy and does not recommend jurisdictional shopping to bypass billing checks. Treat it as author commentary inside a grey-area repo.
FAQ for security researchers
Is muse-protocol malware? It is source code plus docs; run it only in isolated environments. Does Meta endorse it? No public endorsement appears. Will APIs change? Almost certainly; reverse-engineered clients break when servers rotate fields like disclosureVersion. Should enterprises block the repo domain? Blocking GitHub is impractical; instead block automated Muse registration at egress if policy forbids consumer agent betas.
FAQ for compliance officers
If employees clone the repo on corporate laptops, treat it as potential ToS violation risk, not automatic malware. Audit proxy pools and OTP file formats mentioned in the README — they resemble credential stuffing tooling in DLP rulebooks.
Document whether Muse.ai appears on your approved SaaS list before anyone tests signup automation.
Independent journalists covering Meta agents should interview Meta spokespeople, not treat GitHub star counts as adoption proof. Star velocity here reflects invite scarcity curiosity, not necessarily production Muse users.
Researchers publishing on reverse-engineered onboarding should disclose IRB status and terms acceptance in papers, the same way clinical studies cite consent forms.
If Meta ships an official Muse SDK, expect this repository to age quickly; archive commit hashes when citing results so peers can reproduce API versions tied to papers. Until then, cite star count and commit date as attention metrics, not user counts.
musepy/runner.py batch semantics — sticky proxies, max_per_ip, and hard stop on region_waitlist — are documented for transparency. Forks should not strip the README usage declaration when reblogging the map anywhere. explainx.ai does not reproduce full code excerpts here; read the repository if you study automation abuse patterns academically.
