License Management

This page describes how to manage your QUBO++ license using the qbpp-license command-line utility. The license system is shared between QUBO++ (C++) and PyQBPP (Python).

License Types

QUBO++ offers several license types with different variable count limits and validity periods.

License Type Key Required Validity CPU Variables GPU Variables
Trial Yes 30 days (renewable) 10,000 10,000
Other licenses Yes Set individually Set individually Set individually
Fallback N/A Always 100 100
  • Trial License: Free, self-service. Sign up at the QUBO++ User Portal using the sign-up code printed by qbpp-license -s. Once registration is complete, the Trial license key is displayed in the portal.
  • Other licenses: Licenses with individually agreed validity periods and variable-count limits may be issued. The applicable terms are communicated when the license is issued.
  • Fallback Mode: When no valid license is set, the license is suspended, or the cache has expired with no network, QUBO++ runs with a 100-variable limit.

How variables are counted

The variable counts in the table are limits on the total of binary and native integer variables, counted as follows:

  • Binary variable: 1 each
  • Native integer variable: $\lceil \log_2 (r+1) \rceil$ each, where $r$ is its range (upper bound minus lower bound)

An integer variable is counted exactly as the binary-encoded integer variable (var_int) would consume, so the two representations are license-neutral.

The current usage is available via qbpp::used_var_count() (qbpp.used_var_count() in Python). Use it to check whether your model fits within the 10,000 of Trial or the 100 of Fallback.

What Unlimited means

When a license shows Unlimited for its variable counts, there is no license-side limit on the number of variables — the counted limits of Trial (10,000) and Fallback (100) do not apply.

The implementation capacity of QUBO++ still remains, however: binary variables and native integer variables can each be used up to $2^{30}-1$ = 1,073,741,823. Reaching this capacity raises an explicit capacity error, not a license error.

Obtaining a Trial License

  1. Install QUBO++ on a Linux machine.
  2. Run qbpp-license -s — your terminal prints today’s 8-character sign-up code along with the portal URL.
  3. Open https://qubo-plus.github.io/portal/, fill the sign-up form, and enter the code from step 2.
  4. After confirming your email, the portal displays your Trial license key (T-PREFIX-XXXXXX-XXXXXX-XXXXXX, where PREFIX is derived from your email local part).
  5. Click the Start/Renew button in the portal to start the Trial.
  6. Activate the key on your machine: qbpp-license -k T-... -a.

The 30-day Trial clock starts when you click Start/Renew in the portal. A newly issued key has not started yet: activating or running with it before you click the button reports “Trial not started” and QUBO++ runs in the 100-variable Fallback mode. Within the final week before expiry (and after it has expired), the same button renews the Trial — the same license key is reused with the expiry pushed out by another 30 days, so your machine activations stay in place and no re-activation is needed.

Setting and Activating the License Key

Scope of this section: the activation flow described below — together with Checking License Status and Deactivating a License — applies to node-locked licenses (single-machine keys). Activation binds the key to a specific physical machine. For floating licenses, see Floating Licenses at the bottom of this page.

Virtual environments (Docker, VMs, ephemeral containers, etc.) are not supported with node-locked licenses. The machine fingerprint may not be stable, activation may fail, or the cached activation may be lost when the container is rebuilt — leaving the deactivation slot stranded on the server. If you need to run QUBO++ inside a virtual environment, use a floating license, which is designed for this case and works without any per-machine activation.

If you have a license key, set it using one of the following methods.

Run the following command once per machine:

qbpp-license -k XXXXXX-XXXXXX-XXXXXX-XXXXXX -a

The license key is encrypted and cached locally. After activation, no environment variable or -k option is needed for subsequent runs — QUBO++ programs automatically use the cached key.

To re-activate or change the key, simply run the command again with a new key.

Method 2: Environment Variable

Set the QBPP_LICENSE_KEY environment variable to supply the key without saving it as this machine’s default key — for example, to inject it from a deployment script or a CI secret (the license check result and similar information are still written to ~/.qbpp). A node-locked license must still be activated once on the machine with Method 1 (on a machine where it is not activated, QUBO++ runs in Fallback Mode):

export QBPP_LICENSE_KEY=XXXXXX-XXXXXX-XXXXXX-XXXXXX

Node-locked licenses are not recommended for Docker, VMs, or other ephemeral environments, even via this environment variable. Activation still binds to a machine fingerprint that is unstable in such environments, so a node-locked key cannot reliably run there. For Docker/VM/CI, use a floating license, which is not bound to a machine and reads the same QBPP_LICENSE_KEY variable.

Method 3: Embedding in Code

To bundle a license key inside an application, call license_key() in your code:

// C++
qbpp::license_key("XXXXXX-XXXXXX-XXXXXX-XXXXXX");

# Python
import pyqbpp as qbpp
qbpp.license_key("XXXXXX-XXXXXX-XXXXXX-XXXXXX")

A key set this way (the default form) is treated as an embedded default key with the lowest priority: it is used only on machines that have neither the environment variable nor an activated cached key. Users of your application can therefore switch to their own license simply by setting QBPP_LICENSE_KEY.

To force the key and override the environment variable and the cached key (the same treatment as qbpp-license -k), pass true as the second argument (force=True in Python):

qbpp::license_key("XXXXXX-XXXXXX-XXXXXX-XXXXXX", true);   // force

Priority

When multiple methods are used, the following priority applies:

  1. -k argument or qbpp::license_key(key, true) in code (highest)
  2. QBPP_LICENSE_KEY environment variable
  3. Cached key
  4. qbpp::license_key(key) in code (embedded default key, lowest)

Note: A Trial license key is required even for evaluation. Run qbpp-license -s to obtain a sign-up code, then register at the User Portal to receive your Trial key.

Checking License Status

To display the current license status without making any changes:

qbpp-license

This shows the license type, expiry date, variable limits, and activation usage. The command contacts the license server to refresh the status.

Deactivating a License

To move a license to another machine, first deactivate it on the current machine:

qbpp-license -d
  • Each license key has a limited number of allowed activations.
  • Deactivation frees up one activation slot.
  • The locally cached key is removed as well. To use the license on this machine again, run qbpp-license -k KEY -a (your key is always available in the User Portal).
  • There is a 24-hour cooldown between consecutive deactivations to prevent abuse.
  • If the same machine is no longer recognized as activated (for example, its network adapters changed, as can happen on WSL2) and qbpp-license -k KEY -a reports that the activation limit is reached, qbpp-license -k KEY -d on that machine still releases this machine’s existing activation; then run qbpp-license -k KEY -a again. This is also subject to the 24-hour cooldown.
  • qbpp-license -d only releases the activation of the machine it runs on. To release another machine’s activation, choose it in the User Portal.

Command Reference 

Usage: qbpp-license [options]

Options:
  -h, --help          Show help message and exit
  -v, --version       Show version and exit
  -k, --key KEY       Specify a license key (without -a/-d: show info only)
  -a, --activate      Install the license on this machine (node-locked:
                      activate + cache as default key; floating: cache only)
  -d, --deactivate    Remove the license from this machine (node-locked:
                      deactivate + remove cached key; floating: remove only)
  -s, --signup-code   Print today's portal sign-up code and exit
  -t, --time-out SEC  Set the server communication timeout (default: 20 seconds)

Examples

Command Description
qbpp-license Display current license status
qbpp-license -s Print today’s sign-up code for portal registration
qbpp-license -k KEY Show information about a key (no state change)
qbpp-license -k KEY -a Activate with a specific key
qbpp-license -d Deactivate the license on this machine and remove the cached key
qbpp-license -t 60 Check status with a 60-second timeout
qbpp-license -k KEY -t 60 -a Activate with a key and extended timeout

How License Verification Works

  • qbpp-license command: Always contacts the license server to get the latest status. This may take a few seconds depending on network conditions.
  • QUBO++ programs (node-locked licenses): Verify the license using the local cache and do not block on server communication. The server is contacted in the background only when the last check is old enough (more than 10 minutes).
  • QUBO++ programs (floating licenses): Acquire a seat from the server at startup. If a process with the same key is running on the same machine, its seat is taken over without contacting the server.
  • License key storage: When a license is activated with qbpp-license -a, the key is encrypted and cached locally. This allows subsequent runs without setting the key again. A key passed through QBPP_LICENSE_KEY or embedded in a program is not saved by running it.

Network and Timeout

If your network is slow or behind a firewall/proxy, the default 20-second timeout may not be enough.

To increase the timeout:

qbpp-license -t 60 -a

If the server is unreachable, a node-locked license falls back to the cached license status, and QUBO++ runs in Fallback Mode (100-variable limit) if no cache exists. A floating license cannot acquire a seat, so the cache is not used and QUBO++ runs in Fallback Mode.

Connecting Through a Proxy

Where the internet is reachable only through an HTTP proxy (compute nodes of supercomputers, corporate networks, etc.), set the proxy in the environment variable https_proxy. QUBO++ and qbpp-license then reach the license server through it.

export https_proxy=http://proxy.example.com:3128
  • HTTPS_PROXY and all_proxy are also accepted. Give a user name and password as http://user:password@proxy.example.com:3128.
  • Hosts listed in no_proxy are reached without the proxy.
  • Some supercomputers set this variable on their compute nodes automatically.

Programs work but with limited variables

  • QUBO++ may be running in Fallback Mode. Check the license status: 
    $ qbpp-license
  • Ensure the license key is set correctly via qbpp-license -k KEY -a or QBPP_LICENSE_KEY.
  • Re-activate if necessary: qbpp-license -a

“Deactivation cooldown”

  • There is a 24-hour waiting period between consecutive deactivations.
  • Wait and try again after the cooldown period has elapsed.

Floating Licenses

Floating licenses allow shared access across multiple machines within an organization. Instead of being permanently locked to a machine, a floating license uses a lease-based mechanism.

  • When a QUBO++ program starts, it acquires a lease from the license server.
  • The lease is automatically renewed while the program is running.
  • When the program exits, the lease is released, making the slot available for other machines.
  • If the program crashes or the network is lost, the lease expires automatically after a timeout period.
  • Virtual environments (Docker, VMs, ephemeral containers, etc.) are fully supported. Floating licenses do not bind to a machine fingerprint, so rebuilding a container or starting a fresh VM does not strand any activation slot.

A floating license key can be supplied in two ways.

Activate and cache (persistent machines):

qbpp-license -k F-XXXXXX-XXXXXX-XXXXXX-XXXXXX -a

The key is encrypted and cached locally, so subsequent runs pick it up automatically — convenient on a long-lived workstation or server.

Environment variable (recommended for Docker, CI, and other ephemeral environments):

export QBPP_LICENSE_KEY=F-XXXXXX-XXXXXX-XXXXXX-XXXXXX

The activation cache from qbpp-license -a is stored in the home directory, so it is lost whenever a container or VM is rebuilt — you would otherwise have to re-run qbpp-license -a on every fresh start. Setting QBPP_LICENSE_KEY avoids this entirely: each QUBO++ program reads the key directly from the environment and acquires its lease, with no local activation cache required. Because a floating license is not bound to a machine fingerprint, the same key can be shared across any number of containers without consuming or stranding per-machine activation slots — making the environment variable the preferred way to inject a floating key into a Docker image, docker run -e, Kubernetes secret, or CI job. However, one key holds a seat on only one machine at a time (multiple processes on the same machine share one seat); a process started at the same time on another machine or in another container cannot get a seat and runs in Fallback Mode.

The QBPP_LICENSE_KEY value is used only if it is a well-formed key (an offline format check, including the check digit). A malformed value is ignored (with a warning) and QUBO++ falls back to the cached key, so a mistyped environment variable never breaks an already-activated machine. A well-formed key, however, is used in preference to the cached key even if it has expired or been revoked, in which case QUBO++ runs in the 100-variable Fallback mode.

Back to top

Page last modified: 2026.10.30.

© 2026 Koji Nakano, Hiroshima University