Licensing and activation in Onyx Code

Licensing at a glance

Onyx Code Pro is a one-time purchase. Activation runs locally: the desktop verifies a signed JWT against an embedded Ed25519 public key, then caches the license under your OS secret store. No background subscription, no recurring charges, no telemetry tied to the license.

Free vs Pro

The Free tier covers local chat, inline autocomplete, local GGUF models, and the codebase index for as long as you use the editor. Onyx Code Pro unlocks Plan and Auto agent modes, unlimited chat models, every MCP server running at once, project memory across sessions, model A/B comparison, and other Pro-only surfaces. A status-bar pill on the left shows the current tier (Onyx Free or PRO); click it to open the License Panel.

Activating Pro (online, code + email verification)

After purchase, you receive a 16-character activation code by email (Crockford alphabet, no ambiguous characters). Online activation also confirms you control the purchase inbox via a one-time email code, so a code shared without inbox access cannot unlock Pro online. To activate:

1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run Onyx: Activate Pro, or type /activate in chat, click Activate Pro in the License Panel, or use the Already Have Pro? step in the Welcome wizard on first run.
2. Enter your 16-character code and the email you bought with, then click Send Verification Code. If they match your license, a 6-digit code is emailed to that address.
3. Enter the 6-digit verification code and click Activate.
4. The desktop POSTs the code, email, verification code, your hashed Machine ID, and the app version to the licensing server. On success, the server returns a signed JWT that this device caches in secret storage. The status bar flips to PRO.

Activation requires an internet connection. If you are permanently air-gapped, use Activate from Offline File instead (see below).

Activating offline (license file)

For machines that cannot reach the internet, mint a .onyxlicense file from any internet-connected device at onyxcode.app (direct buyers) or at codesnatch.io/onyx/offline-activation (codesnatch members), copy it to the air-gapped machine, then run Onyx: Activate from Offline File (also reachable as /activate-file in chat, or from the License Panel). The file is verified against the embedded public key with no network call. Offline files are valid for 365 days; mint a new one before expiry to renew.

Already activated on this device

Running Onyx: Activate Pro (or /activate) on a device that already holds an active Pro license does not present the input form. The desktop short-circuits to an Onyx Code Pro is already active on this device dialog showing your purchase email and three buttons:

• View License opens the License Panel with full license details.
• Manage Devices jumps to the device list for the current license.
• Close dismisses the dialog.

The licensing service refuses to send a fresh activation request in this state as a second-layer guard, so a DevTools bypass of the dialog still cannot burn a duplicate activation or knock the device off its current binding. To activate with a different code, run Onyx: Deactivate This Device first.

Lost your activation code (recovery)

Run Onyx: Resend Activation Code by Email (or click Lost your code? in the License Panel). Enter the email address you used at purchase. The server checks for an active license under that email and, if one exists, re-mails the 16-character code.

The recovery endpoint is designed not to leak which addresses have purchased Onyx Code Pro. Several defenses run in layers:

• Identical response shape. Whether or not the email matches, the server returns the same status code, body, and headers. The desktop toast is the same in both cases (Request received. If this email has an active Onyx Code Pro license, the activation code will arrive in your inbox shortly.).
• Constant-time floor. Every response is padded to at least 350 ms so a missing license cannot complete faster than a successful send and reveal itself by timing.
• Three rate-limit keys. 3 requests per 24 hours per email address, 10 per hour per IP, and 5 per 24 hours per machine. The tightest one binds; the 429 response never says which key tripped.
• Origin check. The endpoint requires an X-Onyx-Client: desktop/<version> header that every production build sends. Casual scrapers without this header fail closed with the same generic response.
• Client-side cooldown. The desktop adds a 60-second cooldown after each request, persisted across app restarts. Accidental double-clicks (or a slow-network retry) cannot fire repeat requests within that window.

Managing devices

One Onyx Code Pro license runs on up to 3 devices at a time. Run Onyx: Manage Devices (or /manage-devices in chat) to see the devices bound to your license. Each row shows the device label (OS hostname when available), platform, app version, and last-seen date.

To free a slot on a device other than the one you are currently using, click the Remove button next to it. The server sends a confirmation link to your purchase email; opening that link on the current device within 15 minutes removes the target device. The link is single-use and bound to the requesting machine, so it cannot be replayed from somewhere else.

To remove the device you are currently on, run Onyx: Deactivate This Device instead. The server rejects requests to remove the calling device via Manage Devices with a dedicated error, so the local-deactivate path is the only way to free your own slot.

Refreshing the license

Online licenses are cached as 30-day JWTs. A background scheduler ticks every 6 hours and refreshes the token once it enters its last week of validity, so the cache renews on its own as long as you are online. To force a refresh (after a network switch, after toggling Air-Gap off, or just to verify your license is still good), run Onyx: Refresh License Now or click Refresh Now in the License Panel.

Offline-file licenses (365 days) are self-contained and do not refresh. The Refresh Now button is hidden when the current license is an offline file. When the 365-day window is within 30 days of expiry the desktop shows a soft notification with a one-click link to onyxcode.app/offline-activation where you can mint a fresh file; if the window closes before you renew, the desktop drops to Free and shows a recovery notification with the same link.

Deactivating this device

Run Onyx: Deactivate This Device (or /deactivate) to clear the cached license locally and release the device slot on the server. The license itself is preserved; you can re-activate on this machine any time, or use the slot on a different machine. Deactivation requires an internet connection so the server-side release succeeds. If Air-Gap Mode is on, the command refuses and points you at Manage Devices from another machine.

The License Panel

Run Onyx: Open License Panel (or /license in chat, or click the status-bar tier badge) to open a unified license overview. Pro users see their purchase email, license source, and cache-expiry date plus buttons for Refresh Now, Manage Devices, Show Machine ID, and Deactivate. Free users see a short tier explainer plus Activate Pro, Activate from File, Lost your code?, and Show Machine ID.

Machine ID

The Machine ID is a SHA-256 one-way hash of a stable per-install identifier. The server sees only this hash, never the underlying identifier or any device-fingerprinting data. Run Onyx: Show This Device's ID to display it; you only need it for offline activation (paste it into the offline-activation form to mint a file bound to this machine) or for support tickets.