NETWORK.md

Network behaviour

中文

Optional WorkBuddy and Claude benefit lookups

When explicitly enabled, WorkBuddy posts only to https://www.workbuddy.cn/billing/meter/get-user-resource-summary and the same host's get-user-resource-paid-packages / get-user-resource-free-packages endpoints. The manually supplied Cookie and matching User-Agent travel only to that host. The optional cycle lookups share a bounded deadline and cannot erase a successfully read Credits balance.

Claude OAuth usage requests may include ?cedar_ember=1 for reset vouchers and promotional cloud Credits. These remain separate from subscription quota and personal spending. Manual credentials may optionally use JSON { "accessToken": "…", "sessionCookie": "sessionKey=…" }. Only with that explicit Cookie do we contact https://claude.ai/api/account and https://claude.ai/api/organizations/<verified-org>/subscription_details; ownership is checked against https://api.anthropic.com/api/oauth/profile before and after the lookup. Cookie and OAuth headers are never sent to each other's host. A mismatch or optional failure leaves dates unavailable. There is no browser-cookie import, desktop decryption, credential rotation, or login-file write.

Codex measured turn performance is derived locally with no additional network access and is not included in community upload payloads.

There is no telemetry, software-version update check, advertising request, or hidden background connection. Local parsing modules do not import the network client. The public pricing catalog is downloaded only during the one best-effort init check, an explicit pricing update, or the Dashboard's Check for updates action; no local usage is uploaded. Background sync exists only after an explicit daemon install and can be inspected or removed with the CLI at any time.

Command	Network	Purpose
no arguments, help, sources, completion	No	Local help, configuration, completion scripts, and capability display
status	Only when connected	Local configuration plus a best-effort lookup of the bound community account (5-second timeout, no usage upload)
stats, top	No	Local offline multi-dimensional usage analytics and model rankings
export	No	Local export of token/session records as CSV/JSON/JSONL
quota / limits	Configured providers only	Query public quota endpoints and reset windows for enabled providers
inspect --dry-run	No	Show local roots and parser results
doctor [--json]	No	Redacted local compatibility report
reset --local	No	Remove local sync checkpoints
pricing status/reset	No	Inspect catalog status, or remove the downloaded cache and restore the bundled offline copy
pricing update	Yes	Explicitly download, validate, and cache the public community price catalog; uploads no usage
init	Yes	Connect a device and best-effort refresh public pricing; no usage upload unless --sync is explicit; --skip-pricing-update skips the download
sync [--full]	Yes	Read privacy settings and upload changed aggregates; --full explicitly replays only sources marked Local + sync
daemon install/restart	Yes, in the scheduled child	Manage a per-user OS scheduler and trigger its first incremental sync
daemon status/uninstall	No	Inspect or remove the per-user scheduler
scheduled daemon run	Yes	Run the same incremental sync while the device is awake and online
summary	No by default (--remote Yes)	Summarize usage (local offline by default; --remote reads cloud summary)
dashboard	No by default	Loopback dashboard; community connection/sync and provider quota checks require explicit browser actions
npm run setup	Yes	Explicitly install the dashboard's development dependencies from npm
npm run dev	No by default	Loopback Vite + local API; the same optional quota rules as dashboard apply
npm run check:pricing-drift	Yes	Maintainer-only comparison of a small provider/model allowlist against AI Pricing Guru; reads no local usage and writes no catalog

For the default origin https://kimi.builders, the current endpoints are:

• POST /api/usage/device/code
• POST /api/usage/device/token
• GET /api/usage/device/current (display identity of the authenticated device owner; no email)
• DELETE /api/usage/device/current (explicit device disconnection)
• GET /api/usage/settings
• POST /api/usage/ingest
• DELETE /api/usage/ingest
• GET /api/usage?days=N
• GET /api/public/usage-pricing/v1/catalog (public, no device key, ETag-aware)

The catalog is public versioned JSON containing only model match rules, standard API USD rates, effective windows, and provenance. It is cached at ~/.kimi-builders/usage/pricing-catalog-v1.json. Network or validation failures retain the last-known-good catalog; without one, the bundled npm snapshot remains available, so scanning and Dashboard startup never depend on the community API.

The separate maintainer CI drift check reads https://www.aipricing.guru/api/pricing.json only on its scheduled or manually dispatched workflow. It compares five explicitly mapped model/provider identities, stores no response artifact, and can only fail with a review prompt. It never runs in the published CLI, changes the catalog, or sends local usage. Maintainers must verify every flagged change against the first-party URL already recorded in the catalog.

init --api-url can point to another origin for development or self-hosting. The Collector sends the device API key only to the configured origin. Ingest bodies are gzip-compressed JSON; compression changes transport size, not fields.

The background service uses macOS launchd, Linux user systemd, or Windows Task Scheduler. It stores scheduler metadata, last-run status, a lock, a bounded local log, and a fixed-version Collector copy under ~/.kimi-builders/usage/runtime. It does not depend on the npx cache or automatically download upgrades. Explicit daemon restart refreshes the copy from the Collector version you are running; Node itself must remain installed. Uninstall retains runtime copies and user data. It has no additional network destinations and cannot be installed by merely opening the dashboard.

The local web dashboard binds to loopback only and uses a random per-launch browser token, strict Host/Origin checks, a restrictive CSP, and no-store responses. Its Token analysis stays offline. The Dashboard can request device authorization, run one sync, manage the OS scheduler, disconnect the current device, or delete that device's cloud history only after the user presses the corresponding control. Opening the community-sync dialog also verifies the bound account once; an old or unreachable community API shows an unconfirmed identity, never a guessed account. Local Token views perform no identity lookup. Subscription-limit checks are separate, disabled by default, and contact only the provider explicitly enabled in local settings:

Quota-history recording, Token-to-quota correlation, pace forecasts, and subscription-value observations are local computations and add no network destinations. Cached dashboard reads do not manufacture duplicate history points; only a fresh provider refresh can append a sanitized observation.

• Codex: https://chatgpt.com/backend-api/wham/usage and the optional wham/rate-limit-reset-credits companion endpoint;
• Claude Code: https://api.anthropic.com/api/oauth/usage;
• Kimi Code: the local login and each Coding API key independently query https://api.kimi.com/coding/v1/usages. API keys never call web/OAuth endpoints or fall back to another account. When a locally owned CLI access token is near expiry, https://auth.kimi.com/api/oauth/token rotates it under Kimi Code's cross-process lock and atomically updates the owner-only CLI credential file; or https://www.kimi.com/apiv2/kimi.gateway.billing.v1.BillingService/GetUsages and https://www.kimi.com/apiv2/kimi.gateway.membership.v2.MembershipService/GetSubscriptionStats when the user explicitly selects a Web token source, with optional https://www.kimi.com/apiv2/kimi.gateway.membership.v2.MembershipService/GetSubscription enrichment for the official plan name. Failure of either optional enrichment never hides quota facts already obtained;
• Cursor: https://cursor.com/api/usage-summary and the optional https://cursor.com/api/auth/me identity endpoint;
• GitHub Copilot: GitHub's device authorization endpoints https://github.com/login/device/code and https://github.com/login/oauth/access_token, account identity at https://api.github.com/user, then quota facts at https://api.github.com/copilot_internal/user; device authorization starts only after the user presses Connect and supports separately stored accounts;
• OpenCode Go: each account independently selects one connection method. API-key accounts request https://opencode.ai/zen/go/v1/usage; web-session accounts use their own Cookie with https://opencode.ai/workspace/{id}/go. A web-session Cookie and its wrk_… Workspace ID must belong to the same account and are never shared across accounts;
• Qoder: https://qoder.com/api/v2/me/usages/big_model_credits, or the equivalent qoder.com.cn endpoint when the user selects the China site;
• Warp: https://app.warp.dev/graphql/v2?op=GetRequestLimitInfo;
• Antigravity first reuses an already-running Antigravity or agy process. It discovers that process's listening loopback ports and sends fixed-path POSTs only to 127.0.0.1 for RetrieveUserQuotaSummary, GetUserStatus, or GetCommandModelConfigs. Self-signed TLS is accepted only on this fixed loopback boundary; the dashboard never starts or stops the process. If no usable local service exists, an explicitly configured OAuth source may use https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist, v1internal:fetchAvailableModels, and, when needed, v1internal:retrieveUserQuota; expired OAuth credentials may refresh through https://oauth2.googleapis.com/token;
• DeepSeek: https://api.deepseek.com/user/balance reads the API account's per-currency total, topped-up, and granted money balances with an explicitly configured API key. No browser session or private Platform endpoint is read;
• Kiro: the local Kiro CLI data.sqlite3 is opened read-only to obtain its access token and profile ARN, then https://codewhisperer.us-east-1.amazonaws.com/ receives AmazonCodeWhispererService.GetUsageLimits. usage-cli does not execute Kiro CLI or take ownership of token refresh; an expired login must be renewed with kiro-cli login. When bonus credits cannot be separated reliably, no plan balance is guessed;
• GLM / Z.ai: the selected region uses https://open.bigmodel.cn/api/monitor/usage/quota/limit or https://api.z.ai/api/monitor/usage/quota/limit with the personal Coding Plan key; no organization headers, team scopes, or optional analytics requests;
• MiniMax: the selected region uses https://api.minimaxi.com/v1/token_plan/remains or https://api.minimax.io/v1/token_plan/remains. Only 404/authentication failures may retry /v1/api/openplatform/coding_plan/remains on that same host. Keys never follow redirects;
• Alibaba Coding Plan: the explicitly supplied console Cookie goes to the selected https://bailian.console.aliyun.com or https://modelstudio.console.alibabacloud.com dashboard and, if needed, /tool/user/info.json to obtain its console SEC token. A read-only queryCodingPlanInstanceInfoV2 POST then goes to https://bailian-cs.console.aliyun.com/data/api.json (China) or https://bailian-singapore-cs.alibabacloud.com/data/api.json (international). No browser-cookie extraction, arbitrary endpoint overrides, purchases, or Token Plan requests;
• JetBrains AI: no network; the latest local IDE quota file is read.

The three regional Coding Plan integrations keep Keychain credentials and declared prices separate by region. Switching region does not retry credentials against another host. Quota history uses a one-way credential/region fingerprint; rotation starts a new series. No credentials, raw quota responses, or quota history are uploaded to the community. Trae is visible in the setup catalog but disabled because this version has no stable, independently verifiable subscription-quota interface for it. Merely showing a provider in settings never causes a connection.

These are account-product surfaces rather than standard public API usage meters. They are best-effort integrations and can change independently of the local log parsers. Failures are isolated and never block the Token dashboard.