3. Account, usage and billing
[!ref] New-user tutorial: a step-by-step first sign-in walk-through is in the Quick Start Guide, "Install and sign in"; this chapter details each sign-in method, quotas and usage billing.
AVL Code uses a unified administration backend for sign-in; signing in automatically provisions a plan quota for this machine. No manual API key configuration is needed.
3.1 Sign-in methods
The unauthenticated section of the account page is a two-segment switcher: Phone (default) | Password.
| Method | Flow |
|---|---|
| SMS verification code (default, fastest) | Enter phone number → receive SMS code → submit. If the account doesn't exist it auto-registers. 60-second resend countdown; risk control swaps in a CAPTCHA when needed |
| Username + password | Settings → Account → Password tab → enter credentials → submit |
| SSO single sign-on | Settings → Account → SSO sign in → browser → callback → app receives credential |
The three methods give identical quotas (key issuance and state stay in sync) and only differ in the sign-in step itself.
3.2 Plan quota vs personal quota
After signing in your account carries a plan quota. The quota is metered per period (5-hour and 7-day windows); when a window is used up you'll see a "plan quota exhausted" notice — wait for the period to recover to continue. Purchased usage vouchers are exempt from plan quotas. Your current plan and available points show in the Settings → Account panel.
If you want to use your own model API key (e.g. a personal OpenAI / Anthropic / Aliyun subscription), add it under Settings → Models → Providers. AVL Code uses your key first and falls back to the plan quota.
3.3 Usage monitoring
The Settings → Account panel shows three usage windows:
- 24 hours
- 7 days
- 30 days
Refreshed every minute. If something anomalous happens — e.g. a burst of calls — the points-balance panel highlights it in a warning colour to make the anomaly easy to spot.
3.3.1 Quota prompts now tiered by usage and reset time
Pre-exhaustion prompts are no longer one-size-fits-all — they tier by current usage percentage + time until reset:
- Light hint: usage not high yet, reset still far away → only the status dot changes colour, no interruption.
- Medium hint: usage near the cap or reset coming up soon → an info bar above the input box shows "N points left · resets in M minutes".
- Strong hint: usage almost exhausted and reset still distant → banner / card prompt with suggestions (switch to backup provider, redeem a coupon).
The prompt text shows the reset time in your local timezone (e.g. "resets today at 18:00") instead of a vague "running out".
3.4 Credential expiry
The sign-in credential is valid for about 24 hours.
- Within an hour of expiry the sidebar status dot turns amber.
- Once expired, the next action triggers a "session expired" message and the sign-in page.
- Re-signing in does not lose sessions or config.
3.4.1 Redemption codes and usage coupons
Settings → Account has a new Redemption Code section:
- Enter a redemption code → click "Redeem".
- Result feedback in place (12 localised outcomes covering success / invalid / used etc.).
- Below it is My Usage Coupons — face value, expiry, with permanent coupons explicitly tagged "Permanent".
[!note] The Available credits figure on the account panel comes straight from the server's display value, so it always matches what the web account page shows; the client no longer sums the coupon list itself, which is what used to make the two disagree.
3.4.2 One click to buy when you run short
When credits run out or the plan's period quota is exhausted, you don't have to go hunting for the right web page — the UI offers the way out where you are:
| Where | What you get |
|---|---|
| The error block in the conversation | When the turn failed because of "insufficient balance" or "period quota exhausted", the error block gains a "Buy vouchers" and an "Upgrade plan" button. Throttling, auth failures and upstream outages don't get those buttons — spending money wouldn't fix them |
| Low-balance notice in the message stream | When you use the built-in AVL-Zero and available points drop below 50, a one-line notice appears under the latest reply in this session — "AVL Zero balance is down to §xx.xx and running low" — with "Buy vouchers" and "Upgrade plan" buttons; it isn't repeated on a reply that already shows the out-of-credits error, while output is streaming, or when the balance is unknown |
| Settings → Account · account card | A permanent "Buy vouchers" entry next to the balance, so you can top up the moment you see it; the balance row is always rendered on a single line, even when the balance is unknown |
| Settings → Account · usage area | The same "Buy vouchers" and "Upgrade plan" buttons |
| Version-expired lock screen | Offers both entry points as well |
Clicking first opens a tier dialog in the app ("Pick a tier, then confirm and pay in your browser"); once you pick a tier, that tier's "confirm purchase" page opens directly in your system browser to complete payment, saving a hop. Plans that require contacting sales go to the plan subscription page instead, and "Open service page" at the bottom of the dialog opens the full vouchers / subscription page. The reason the payment QR code isn't embedded in the app: the payment URL itself is long, the resulting code is too dense, and real phones struggle to scan it — handing off to the browser is simply more reliable.
The destination follows whatever account-service address you have configured, so self-hosted deployments work too.
3.5 Sign out
Settings → Account → Sign Out. This clears the local credential and the ability to use the plan quota, but preserves all local workspaces, sessions, skills and settings — signing back in resumes seamlessly.