License Usage

License Deprecation

With MetriCal v14 (released in May 2025), version 1 license keys (prefixed with key/) have been deprecated and will no longer work after November 1st, 2025. If you use license keys prefixed with key/, please create new license keys (which will be version 2 keys, prefixed with key2/) and use them instead.

MetriCal licenses are user-specific rather than machine-specific. A license key can be utilized on any system with internet connectivity that can establish a connection to Tangram Vision's authentication servers. For environments with limited connectivity, offline licensing options are available (detailed below).

Using a License Key

R&DGrowthEnterprise

MetriCal looks for license keys in 3 places, in this order:

1. Command Line Argument

Provide the key as an argument to the metrical command.

metrical_runner.sh

metrical --license="key2/<your_key>" calibrate ...

For Docker

This command line argument can be included directly in the metrical shell function by adding it before the "$@" line of your alias.

~/.bashrc

metrical() {
    docker run --rm --tty --init --user="$(id -u):$(id -g)" \
    --volume="$MOUNT":"/datasets" \
    --volume=metrical-license-cache:/.cache/tangram-vision \
    --workdir="/datasets" \
    --add-host=host.docker.internal:host-gateway \
    tangramvision/cli:latest \
    # Note the following line!
    --license="key2/<your_key>" \
    "$@";
    }

2. Environment Variable

Provide the key as a string in the environment variable TANGRAM_VISION_LICENSE.

metrical_runner.sh

TANGRAM_VISION_LICENSE="key2/<your_key>"
metrical calibrate ...

For Docker

Using Environment Variables in Docker

If running MetriCal via Docker, the environment variable must be set inside the container. The docker run documentation shows various methods for setting environment variables inside a container.

One example of how you can do this is to add an --env flag to the docker run invocation inside the metrical shell function that was shown above, which would then look like this:

~/.bashrc

metrical() {
    docker run --rm --tty --init --user="$(id -u):$(id -g)" \
    --volume="$MOUNT":"/datasets" \
    --volume=metrical-license-cache:/.cache/tangram-vision \
    --workdir="/datasets" \
    --add-host=host.docker.internal:host-gateway \
    # Note the following line!
    --env=TANGRAM_VISION_LICENSE="key2/<your_key>" \
    tangramvision/cli:latest \
    "$@";
    }

3. Config File

Provide the key as a string in a config TOML file, assigned to a top-level license key. This key should be placed in your config directory at ~/.config/tangram-vision/config.toml.

~/.config/tangram-vision/config.toml

license = "key2/{your_key}"

For Docker

Using a Config File in Docker

To use a config file in Docker, you’ll need to modify the metrical shell function by mounting the config file to the expected location. Use the following snippet, making sure to update path/to/config.toml to point to your config file.

~/.bashrc

metrical() {
    docker run --rm --tty --init --user="$(id -u):$(id -g)" \
    --volume="$MOUNT":"/datasets" \
    --volume=metrical-license-cache:/.cache/tangram-vision \
    # Note the following line!
    --volume=path/to/config.toml:/.config/tangram-vision/config.toml:ro \
    --workdir="/datasets" \
    --add-host=host.docker.internal:host-gateway \
    tangramvision/cli:latest \
    "$@";
    }

Using a License Key Offline

R&DGrowthEnterprise

MetriCal can validate a license via a local license-cache file, ensuring that internet hiccups don't cause license validation failures that interrupt critical calibration processes.

In order to use MetriCal without an active internet connection, you must run any MetriCal command with an active internet connection once. (This can be as simple as running metrical calibrate foo bar baz, even if foo, bar, and baz files do not exist.) This will create a license-cache file that is valid (and enables offline usage of MetriCal) for 1 week.

Every time MetriCal is run with an active connection, the license-cache file will be refreshed and valid for 1 week. If the license-cache file hasn't been refreshed in more than a week and MetriCal is run offline, it will exit with a "License-cache file is expired" error.

For Docker

Include an additional volume mount when running the docker container, so a license-cache file can persist between MetriCal runs. Update the metrical shell function to include the --volume=metrical-license-cache:... line shown below:

~/.bashrc

metrical() {
    docker run --rm --tty --init --user="$(id -u):$(id -g)" \
    --volume="$MOUNT":"/datasets" \
    # The following line enables offline licensing
    --volume=metrical-license-cache:/.cache/tangram-vision \
    --workdir="/datasets" \
    --add-host=host.docker.internal:host-gateway \
    tangramvision/cli:latest \
    "$@";
    }