Client Configuration

The configuration for Backend.AI API includes the endpoint URL prefix, API keypairs (access and secret keys), and a few others.

There are two ways to set the configuration:

  1. Setting environment variables before running your program that uses this SDK.

  2. Manually creating APIConfig instance and creating sessions with it.

The list of supported environment variables are:





Other configurations are set to defaults.

Note that when you use our client-side Jupyter integration, BACKEND_VFOLDER_MOUNTS is the only way to attach your virtual folders to the notebook kernels.

ai.backend.client.config.get_env(key, default=None, *, clean=<function <lambda>>)[source]

Retrieves a configuration value from the environment variables. The given key is uppercased and prefixed by "BACKEND_" and then "SORNA_" if the former does not exist.

  • key (str) – The key name.

  • default (Optional[Any]) – The default value returned when there is no corresponding environment variable.

  • clean (Callable[[str], Any]) – A single-argument function that is applied to the result of lookup (in both successes and the default value for failures). The default is returning the value as-is.


The value processed by the clean function.


Returns the configuration for the current process. If there is no explicitly set APIConfig instance, it will generate a new one from the current environment variables and defaults.


Sets the configuration used throughout the current process.

class ai.backend.client.config.APIConfig(*, endpoint=None, endpoint_type=None, domain=None, group=None, version=None, user_agent=None, access_key=None, secret_key=None, hash_type=None, vfolder_mounts=None, skip_sslcert_validation=None)[source]

Represents a set of API client configurations. The access key and secret key are mandatory – they must be set in either environment variables or as the explicit arguments.

  • endpoint (Union[str, URL, None]) – The URL prefix to make API requests via HTTP/HTTPS.

  • version (Optional[str]) – The API protocol version.

  • user_agent (Optional[str]) – A custom user-agent string which is sent to the API server as a User-Agent HTTP header.

  • access_key (Optional[str]) – The API access key. If deliberately set to an empty string, the API requests will be made without signatures (anonymously).

  • secret_key (Optional[str]) – The API secret key.

  • hash_type (Optional[str]) – The hash type to generate per-request authentication signatures.

  • vfolder_mounts (Optional[Iterable[str]]) – A list of vfolder names (that must belong to the given access key) to be automatically mounted upon any Kernel.get_or_create() calls.

DEFAULTS = {'domain': 'default', 'endpoint': '', 'endpoint_type': 'api', 'group': 'default', 'hash_type': 'sha256', 'version': 'v4.20190315'}

The default values except the access and secret keys.