duwqijlk/muse-protocol

What it does

This repository documents the HTTP protocol behind muse.ai account registration and invite-code redemption, captured by comparing field-by-field packet dumps rather than driving a browser. The musepy package contains a full-flow client (client.py) plus optional telemetry reporters for falco performance events (fixed machineId of not_set) and CAA registration-funnel events. An end-to-end example (example_register.py) walks from the landing page through OTP confirmation, registration completion, session activation, VM wake, and invite-code redemption.

The README is a protocol walkthrough: it lists the exact endpoints and expected status codes, then flags details that are easy to get wrong. It is aimed at developers studying the signup flow, not at end users who just want an account.

Quick start

Requires Python and a JSON config file. Install dependencies, copy the config template, fill in an email and optional proxy, then run the example:

pip install -r requirements.txt
cp config.example.json config.json
python example_register.py

The flow expects a Japan node per the README, which it says does not require a payment card binding. The script drives the sequence: GET / for the initial cookie, POST /api/auth/native/restart (body {"resume": false}) to obtain a CSRF token, then send-otp, confirm-otp, and register-completion to get frl_access_token and frl_account_id. After that, accept-tos, vm/wake, and stateful-sharing must run before invite-code/redeem. Success returns {"redemptionStatus": "redeemed"}.

Key protocol details documented in the README include: confirm-otp requires supports_muse_link_transparency: true; first_name is the given name and last_name is the family name, and a birth date under about 18 years returns 403; accept-tos must carry the full Japanese disclosure text to activate the session; and skipping vm/wake makes a valid code report invalid. A vmId UUID is extracted from the logged-in page for that call.

Constraints

The project is stated as personal, non-commercial study and research only, with no MIT-style open license and no redistribution; the repository metadata shows NOASSERTION. Users are told to follow the target site's terms and local laws. Redemption failures map to already_redeemed, used_up (30-use cap), and invalid. The hatch_sess cookie (about 886 characters) issued by register-completion is the credential for all hatch endpoints; hatch_vml is cleared during registration and is not required. Telemetry modules can be disabled in config without affecting the flow.

HotRepo's take

On the HotRepo new-project list, the repository recorded 124 stars and 78 forks on 2026-11-14, with growth observed over roughly three hours from 01:24 to 04:15 UTC. No GitHub daily rank is recorded. The fork-to-star ratio is unusually high for a small protocol client, which suggests the code itself is the draw rather than a built-up user base. The README's note on Japan nodes and card-free signup, plus the linked Telegram group, sit outside what the protocol docs can substantiate; readers should treat those operational claims as unverified.

Project source and documentation