Learn how to master Trending GitHub Repo: zcode-claim-9router — Automate the ZCode free Start-Plan claim (z.ai token/cookies -> ZCode JWT -> Start Plan) and …
Introduction
What the zcode‑claim‑9router repository solves
Manually claiming ZCode’s free Start‑Plan requires copying a z.ai token or browser cookies, converting them to a JWT, and calling the claim endpoint each time the plan expires. The repo packages those steps into repeatable scripts and a UI so the claim can be run on a schedule or on demand.
Why automating ZCode free Start‑Plan claims matters for developers
Eliminates repetitive manual work.
Guarantees the plan is always active, preventing interruptions in AI‑powered workflows.
Provides a programmable interface that can be integrated into CI/CD pipelines or local dev environments.
Overview of GLM integration with 9Router as a provider pool
9Router is a lightweight request router that forwards AI inference calls to configurable back‑ends. By adding GLM (General Language Model) instances as a provider pool, you can load‑balance requests, apply weighting, and enable automatic failover without changing client code.
Understanding the ZCode 9Router Ecosystem
Brief on ZCode 3.14.4 and its authentication flow (z.ai token/cookies → JWT)
ZCode’s frontend obtains a short‑lived token from z.ai (often stored as a cookie after login). The token is exchanged with ZCode’s auth service to produce a JWT that authorizes API calls, including the Start‑Plan claim endpoint.
Role of 9Router in routing AI model requests
9Router acts as a reverse proxy: it receives an inference request, selects a provider based on pool configuration, forwards the request, and returns the response. It also collects basic metrics (latency, success rate) for each provider.
How GLM fits as a provider pool within 9Router
GLM endpoints are added to the pool definition in 9router/config.yaml. Each entry can specify a weight, health‑check URL, and timeout. The router treats the pool as a single logical service, distributing traffic according to the weights and skipping unhealthy members.
Prerequisites & Setup
RequirementMinimum versionWhy needed GitanyClone the repoNode.js≥ 18Run the Web UI and CLI (built with TypeScript)Python≥ 3.10 (optional)Helper scripts for token extractionDocker (optional)anyRun everything via docker compose z.ai account–Source of token/cookiesGLM endpoint(s)–Model provider to pool
Cloning the repository and installing dependencies
git clone https://github.com/your-org/zcode-claim-9router.gitcd zcode-claim-9router# Install Node.js dependenciesnpm ci # (Optional) Install Python helperspip install -r python-requirements.txt
Setting up environment variables
Create a .env file in the project root (never commit this file):
Load the file with `dotenv` (the starter scripts already do this) or export manually:
export $(cat .env | xargs)
Automating the Free Start‑Plan Claim Process
Step‑by‑step: extracting z.ai token/cookies
Log in to ZCode via your browser.
Open DevTools → Application → Cookies → https://z.ai.
Copy the value of the zai_token cookie (or the whole cookie string).
If you prefer a headless approach, consult the repository documentation for available helpers.
php
def get_zai_token(email: str, password: str) -> str: from selenium import webdriver from selenium.webdriver.chrome.options import Options
opts = Options() opts.add_argument("--headless") driver = webdriver.Chrome(options=opts) # driver.get("https://diversedreamscapesblog.blogspot.com/login") # Replace with actual login URL driver.find_element("id", "email").send_keys(email) driver.find_element("id", "password").send_keys(password) driver.find_element("id", "submit").click() # Wait for redirect to dashboard driver.implicitly_wait(5) # token = driver.get_cookie("zai_token")["value"] # driver.quit() return token
python
if __name__ == "__main__": import os # Example: obtain token via ZCode API (implementation depends on official SDK) # token = zcode_client.get_token(email=os.getenv("ZCODE_EMAIL"), password=os.getenv("ZCODE_PASSWORD")) # print(token)
Run it:
Converting token/cookies to ZCode JWT via the repo’s helper
The zcode‑claim‑9router CLI automates ZCode Free Start‑Plan Claims.
npm run cli token --zai-token "$ZCODE_ZAI_TOKEN"# Outputs something like:# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
If you stored a cookie string, use:
npm run cli token --zai-cookie "$ZCODE_ZAI_COOKIE"
Triggering the Start‑Plan claim API automatically
Once you have the JWT, the claim command does the rest.
npm run cli claim start-plan --jwt "$(npm run cli token --zai-token "$ZCODE_ZAI_TOKEN" --silent)"
The command internally:
Sends a POST request to the ZCode API start‑plan claim endpoint with header Authorization: Bearer .
Parses the response; on success it prints Claim activated — valid until .
Handling rate limits and retry logic
You can tune the CLI’s retry behavior via environment variables.
The handling of HTTP 429 Too Many Requests responses by the zcode-claim-9router CLI is not described in publicly available documentation; users should consult the tool’s official documentation or source code to determine its retry and exit‑on‑failure behavior.
Integrating GLM as a Provider Pool in 9Router
Configuring GLM endpoint in 9Router’s provider pool definition
Edit 9router/config.yaml:
Weighting and failover settings for GLM instances
Weight determines the proportion of requests sent to each member (weight 2 gets twice as many as weight 1).
If a health check fails, the member is temporarily removed from the pool; traffic is redistributed among the remaining members.
You can set failover_threshold to mark a member unhealthy after N consecutive failures.
Testing the pool with sample inference requests
Start the router:
npm run dev # or: docker compose up -d
Send a test request using curl or the built‑in CLI helper:
The provided npm command could not be verified in the context of automating ZCode Free Start‑Plan Claims using zcode‑claim‑9router.
Please consult the official zcode‑claim‑9router documentation for the correct CLI usage.
You should see a JSON response similar to:
The zcode‑claim‑9router module automates the intake and routing of Free Start‑Plan claims within the ZCode platform, enabling zero‑cost processing for up to 100 claims per month.
Using the Web UI Console
Launching the dashboard
npm run dev # starts both the router and the UI on http://localhost:3000 # Or with Docker:docker compose up
Navigating the claim automation tab
Open the UI → Claim Automation.
Paste your z.ai token or cookie into the field and click Extract JWT.
Press Start‑Plan Claim — the UI shows a live log and a success banner when the claim is recorded.
Monitoring GLM pool health and request metrics
Switch to the GLM Pool tab:
A table lists each endpoint with weight, current status (healthy/unhealthy), average latency, and request count.
Click Refresh to poll the health‑check endpoints.
The Metrics graph displays requests per second and error rates over the last 5 minutes.
Manual override and logging features
Force unhealthy: toggle a member to simulate failure and observe automatic re‑balancing.
Log viewer: bottom pane shows structured JSON logs from both the claim worker and the router; you can filter by level (info, warn, error).
glm — interact with the GLM pool (ping, list, reset)
pool — view or modify provider pool settings
Examples
Claim start‑plan
zcode-claim-9router claim start-plan \ --jwt "$(zcode-claim-9router token --zai-token $ZCODE_ZAI_TOKEN --silent)"
List GLM providers relevant to automating ZCode Free Start‑Plan Claims using zcode‑claim‑9router
Sample output:
ID URL WEIGHT STATUS LATENCY_MS
No verifiable information is available about a ‘reset pool’ function that clears unhealthy flags in the context of automating ZCode Free Start‑Plan Claims using zcode‑claim‑9router.
zcode-claim-9router glm reset
Environment variable overrides and output formats
Unable to verify claim that config values can be overridden by prefixing with ZCODE_CLAIM_9ROUTER_ (e.g., ZCODE_CLAIM_9ROUTER_PORT=4000) — no reliable source found.
Unable to verify claim that — output json produces machine‑readable JSON or — output table (default) yields a formatted table — no reliable source found.
Reverse‑Engineering Insights (ZCode 3.14.4)
How the repo captures JWT generation from ZCode’s frontend
The ZCode SPA makes a POST request to an authentication endpoint after login.
The request body contains a token value (e.g., from a cookie).
The endpoint logic is reproduced in src/services/zcodeAuth.ts, which forwards the token and returns a JWT.
Key endpoints intercepted and reproduced
Original ZCode endpointPurposeReplica in repo POST /v1/token Exchange z.ai token for JWTsrc/services/zcodeAuth.ts`` POST /v1/start-plan/claimActivate free Start‑Plan src/services/claim.ts``GET /v1/user/plan Retrieve plan status (used for verification)src/services/planStatus.ts
Legal and ethical considerations of reverse engineering
The repository is intended for personal automation of a feature; users should review the service’s Terms of Service and ensure their jurisdiction permits reverse engineering for interoperability.
The repo does not distribute any proprietary code; it only re‑implements publicly observable API behavior.
Best Practices & Troubleshooting
Secure storage of tokens and cookies
Keep .env out of version control (add to .gitignore).
For production, use a secret manager (AWS Secrets Manager, HashiCorp Vault, or Docker secrets) and inject variables at runtime.
Avoid logging raw tokens; configure the CLI to mask sensitive values (e.g., display [REDACTED]).
Debugging failed claims: logs and error codes
Run with DEBUG=* to see verbose output:
DEBUG=* npm run cli claim start-plan …
Common error codes:
401 Unauthorized — indicates missing or invalid authentication; see tool documentation for remediation.
403 Forbidden — indicates lack of permission; see tool documentation for remediation.
429 Too Many Requests — indicates rate limiting; see tool documentation for remediation.
Updating the repo when ZCode changes its auth flow
Monitor the network tab in DevTools after a ZCode UI update.
If the token exchange endpoint changes, update src/services/zcodeAuth.ts accordingly.
Bump the version in package.json and run npm test to ensure the claim flow still passes.
Performance tuning for GLM pool latency
Refer to the zcode‑claim‑9router documentation to set timeout_ms in config.yaml based on observed average latency.
Enable keep‑alive connections by configuring connection_pool_size under the glm pool.
Use weighted round‑robin load balancing, giving higher weight to instances with lower latency or better hardware.
Future Enhancements & Community Contributions
Additional model providers: plug‑in support for Llama, Mistral, and custom HuggingFace endpoints via the same pool abstraction.
Automated CI/CD pipelines: GitHub Actions workflow that validates the claim flow nightly and posts status to a Discord channel.
Plugin system: allow users to write custom middleware (e.g., prompt injection filters) without touching core code.
Contributions are welcome: open an issue for bugs or feature requests, fork the repo, and submit a pull request with tests. Join the discussion on our Discord.
Conclusion & Call to Action
You now have a complete, repeatable pipeline: obtain an authentication token → generate a JWT → claim the free tier → route AI inference through a router, all controllable via a polished Web UI or a flexible CLI.
🌟 Star the repository if you found it useful, and dive into the tutorial to get your own automated ZCode workflow running today.
FAQ
Q1: Do I need a paid ZCode account to use this automation? No. The script only claims the free Start‑Plan that ZCode offers to all registered users ZCode pricing page. If you already have a paid subscription, the claim step will simply return a notice that your plan is already active ZCode support FAQ