License configuration¶

ubCode and the CLI application ubc are provided in 2 different licensing modes: commercial and open source.

For open source projects, that is projects that are publicly available, we grant you a free open source license. We do that because we value open source software and want to support the community.

For usage in non-public projects, a commercial license is required.

Commercial¶

If not already done, please request a license key from useblocks. The process for this is not yet automated, so please contact our support directly via e-mail.

We also offer free trials, so that you can evaluate ubCode in your own environment. Please get in touch with us for that.

To configure the license for ubCode, place a file named ubcode.toml in the following location:

For Linux:

~/.config/ubcode/ubcode.toml

For Windows:

C:\Users\<username>\AppData\Local\useblocks\ubcode\ubcode.toml

For MacOS:

~/Library/Application Support/ubcode/ubcode.toml

The file should have the following content:

[license]
key = "AAAAA-BBBBB-CCCCC-DDDDD"
user = "mail@example.com"

If you add or change the key, to let it take effect in the VS Code extension, you need to restart the server, with the command Ctrl+Shift+P and then ubCode: Restart language server.

Systems licenses¶

A systems license is a license key issued for automation, such as a CI/CD runner, rather than for a person: it is not tied to a user e-mail, so it needs no user setting. Only the ubc CLI accepts a systems license, for the commands you run in a pipeline and for ubc serve mcp. The VS Code extension’s language server does not: with only a systems license configured, the editor treats the project as unlicensed unless it is open source (see What works without a license).

Proxies¶

License activation requires an active Internet connection. System proxies are automatically detected and used by ubCode (the standard ALL_PROXY, HTTPS_PROXY, HTTP_PROXY and NO_PROXY environment variables).

If that fails or cannot be done on system level, the proxy server can also be configured in a dedicated section of ubcode.toml:

[proxy]
https = "<proxy-domain-or-ip>"

Note

ubCode only supports HTTP CONNECT proxies, given as host:port or http://host:port. For license checks, a proxy given as https://... is refused, and so is a configured SOCKS proxy.

Machines without Internet access¶

A license key is checked online, against the license server https://api.cryptolens.io. A successful check is cached for 3 days (see Caching), so a machine that was licensed recently keeps working offline for that long.

When the license server cannot be reached, a license check gives up after at most 20 seconds per request (10 seconds to open the connection; on Windows, a blocked certificate revocation check can add up to 10 seconds), and reports the endpoint it could not reach. This matters for build machines, such as CI runners, without a route to the Internet. They have two options:

use an offline license instead of the license key, which needs no network access at all, or
reach the license server through an HTTP CONNECT proxy, see Proxies.

Environmental variables¶

In the CLI, environmental variables can also set, to override the configuration in the ubcode.toml file:

UBCODE_LICENSE_KEY: The license key.
UBCODE_LICENSE_FILE: The path to an offline license file.
UBCODE_LICENSE_USER: The user e-mail.
UBCODE_LICENSE_HTTPS_PROXY: The proxy server.

License handling¶

License keys supplied by useblocks are commonly user based, which means a valid user e-mail must be provided with the license key.

For data protection, the e-mail is irreversibly obfuscated on the local user’s machine, before being sent to the license server for activation.

Caching¶

Online license requests are cached locally for 3 days to avoid unnecessary network traffic, faster startup times and to be able to work offline for a limited time.

The cache is stored in platform specific cache directories, e.g. for Linux under ~/.cache/ublicense/.

The directory can be safely deleted to clear the cache. Online license requests will then be repeated the next time ubCode is started. Also open source checks will be repeated.

Offline licenses¶

If agreed upon, useblocks can also provide offline licenses. The provided license file is configured as follows:

[license]
file = "ActivationFile.skm"
user = "mail@example.com"

If the license file is placed in the same directory as the ubcode.toml file and named “ActivationFile.skm”, it will be picked up automatically.

A user is still required for offline licenses, but the property key is not needed. Remove the key when switching to an offline license, so that it cannot take precedence over the license file.

Open Source¶

ubCode detects whether your VS Code workspace folders are located within publicly reachable Git projects. Every remote of the repository must be reachable without authentication on one of the supported hosts: github.com, gitlab.com, bitbucket.org, codeberg.org and gitea.com (a self-hosted Git server is not detected). Submodules and nested repositories must fulfill the same conditions.

The ubc CLI application does the same, but based on paths of the analyzed projects.

Note

The test requests to the Git remotes are cached for a couple of days, so that they are not repeated unnecessarily.

Note

The requests to test this are unauthenticated. They use the proxy named in the standard ALL_PROXY, HTTPS_PROXY or HTTP_PROXY environment variables, honouring NO_PROXY, but not the [proxy] table of ubcode.toml or UBCODE_LICENSE_HTTPS_PROXY, which apply to the license server only.

Please get in touch with us if you have any issues with this.

What works without a license¶

ubCode has no feature tiers. An active license, commercial or open source, unlocks everything; without one, the same features are available within the limits below.

How the license is decided¶

Each check first tries the commercial license (a license key, or an offline license file). If there is none, or it cannot be activated, ubCode tries the open-source check. If that fails too, the project is unlicensed.

The open-source check is technical: it only tests that the Git repositories holding the project are publicly reachable. It does not look at your project’s license. The license terms ask for more: an OSI-approved open source license, and the complete source code in a public repository. Passing the check does not by itself mean a project meets those terms.

Which paths are checked:

in VS Code, every workspace folder, once when the language server starts;
in the CLI, the project path the command runs on (the current directory by default), or every path you name for ubc check <paths>, ubc check --per-file, ubc format and ubc diff;
in the MCP server, the project of the file each tool call names (the directory of its nearest ubproject.toml), or the server’s default project when the call names no file.

The command line¶

The file limit counts the project’s source documents, the same files ubc build list-documents lists. A command over a limit stops with an error that names the limit, followed by the reason no license was found.

Command	Without a license
`ubc check` (the whole project, or scoped to paths), `ubc build index`, `ubc build list-documents`, `ubc build html`, `ubc build pdf`	Works on projects of up to 5 source files.
`ubc build needs`	Works on projects of up to 5 source files and up to 100 needs.
`ubc build targets`	Works on projects of up to 5 source files and up to 100 targets.
`ubc report`	Works on projects of up to 5 source files and up to 100 needs.
`ubc agent` commands that read the needs index	Work on projects of at most 100 needs, with no limit on source files.
`ubc check --per-file`, `ubc format`, `ubc schema validate`, `ubc query filter`, `ubc query cypher`, `ubc query search`, `ubc diff`, `ubc diff git`, `ubc build linkcheck`	Refused, however small the project.
`ubc serve lsp`	Starts, with the limits in The editor.
`ubc serve mcp`	Starts, but refuses the project tools; see The MCP server.
`ubc quickstart`, `ubc config`, `ubc clean`, `ubc script`, `ubc completions`, `ubc agent-skill`, `ubc license`, `ubc intersphinx`, `ubc build validate-json`, `ubc build linkcheck cache`, `ubc agent config-validate`, `ubc agent doctor`, `ubc agent update`, `ubc agent install` (without `--detect`), `ubc agent reverse record`, `ubc agent reverse forget`, `ubc agent reverse rebaseline`	No license needed.

The editor¶

The VS Code extension, like ubc serve lsp in any other editor, indexes and checks a project of any size without a license. Diagnostics, hover, completion, navigation and formatting work in full, apart from the list-based features below. Without a license:

the preview shows the first 5 top-level blocks of a document, followed by a notice;
the Needs Index and Needs Json views, the search in the needs graph view, and the workflow gap warnings in the Problems panel cover at most 10 needs;
the report preview refuses to render a project of more than 100 needs;
the panels that run ubc agent commands for you are subject to those commands’ limit (see above).

The other workflow views the language server computes itself have no such limit.

The MCP server¶

The MCP server (ubc serve mcp, which the VS Code extension also registers) serves a project’s data only when that project has an active license, whatever its size: get_graph_schema, query_cypher, search_references and resolve_reference answer “Requires active license” otherwise. The documentation tools, search_docs and fetch_doc_page, need no license: they read the public sphinx-needs and ubCode documentation, not your project. See Model Context Protocol (MCP) server for what each tool does.

To evaluate ubCode on a larger private project, ask us for a free trial (see Commercial).

License terms¶

ubCode is proprietary software developed and owned by useblocks GmbH.

While the source code of ubCode itself is not publicly available (closed source), ubCode is offered free of charge for use in Open Source Software (OSS) projects that fulfill the following conditions:

the OSS project must be licensed under an OSI-approved open source license, and
the complete source code of the OSS project must be publicly available in a generally accessible Git repository (e.g. GitHub, GitLab).

Any use of ubCode in commercial environments - including but not limited to closed-source projects, commercial products, services, platforms, or internal tools - requires a separate commercial license agreement with useblocks GmbH.

Please contact us for licensing inquiries regarding commercial use.