Skip to main content

Environment variables

Learn how to configure Piiano Vault using environment variables.

You can set environment variables to configure Piiano Vault, which take precedence over the configuration file of the Piiano Vault settings.


The Set configuration variable REST API call and Set configuration variable CLI command enable some environment variables to be configured dynamically. Refer to the REST API or CLI documentation for details of the supported environment variables.

Piiano Vault license

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_SERVICE_LICENSEstringnoneAllA valid (not expired) license is required to start Vault. It is provided as a string of characters. To obtain a development license, see Install Piiano Vault locally.

Production and development mode

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_DEVMODEboolfalseAllAllows Vault to be run in the development mode. This setting also determines the default values for the environment variables listed here.

Variables whose default values depend on PVAULT_DEVMODE

NameDefault when PVAULT_DEVMODE is trueDefault when PVAULT_DEVMODE is false


NameTypeDefault (Dev / Server)EditionDetails
PVAULT_DB_HOSTNAMEstring"localhost"AllHostname of the running database
PVAULT_DB_NAMEstring"pvault"AllName of the database to connect to
PVAULT_DB_USERstring"pvault"AllUsername for the database
PVAULT_DB_PASSWORDstring"pvault"AllPassword for the database
PVAULT_DB_PORTint5432AllPort of the running database
PVAULT_DB_REQUIRE_TLSboolMode dependentAllVault tries to connect to the database with TLS. If this value is true and the connection fails, Vault does not start. If this value is false and the connection fails, Vault starts and connects without TLS
PVAULT_DB_MAX_OPEN_CONNSint16AllMaximum number of open connections to the backend database–do not modify unless requested to do so by the Piiano team
PVAULT_DB_MAX_IDLE_CONNSint16AllMaximum number of idle connections to the backend database–do not modify unless requested to do so by the Piiano team
PVAULT_DB_CONN_MAX_LIFETIME_MINUTESint5AllThe limit on the time, in minutes, a connection to the backend database is maintained–do not modify unless requested to do so by the Piiano team
PVAULT_DB_MAX_STRING_LENGTHint64AllThe maximum length of data types based on strings, including STRING, NAME, GENDER, CC_HOLDER_NAME, US_BANK_ACCOUNT_NUMBER, OBJECT_ID, TENANT_ID, and FOREIGN_ID.
PVAULT_DB_MIGRATION_AUTO_RUNbooltrueAllWhether Vault sets up the database during migration. Set to false when performing the database migration externally
PVAULT_DB_MIGRATION_ENABLE_RETRIESbooltrueAllWhether Vault performs retries for the database migration. When running the migration in Vault and multiple instances are running, this option must be true to handle race conditions. When running the migration externally, this can be set to false
PVAULT_DB_MIGRATION_INITIAL_WAIT_BETWEEN_RETRIESstring20msAllThe initial wait duration between retries for the migration exponential backoff
PVAULT_DB_MIGRATION_MAX_WAIT_BETWEEN_RETRIESstring5sAllThe maximum wait duration between retries for the migration exponential backoff
PVAULT_DB_MIGRATION_MAX_RETRIESint25AllThe maximum number of retries attempts for the migration exponential backoff
PVAULT_DB_GC_GRACE_PERIOD_DAYSint30AllThe number of days deleted and expired objects and tokens are held before they are hard-deleted by the purge objects and tokens REST API operation and CLI command.

Key management service

A key management service (KMS) should be configured. For more information on using a KMS and property encryption, see Key management service on the encryption page.

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_KMS_URIstring""AllThe KMS key URI used for property encryption
PVAULT_KMS_SEEDstring""AllGenerate a local KMS using this seed (KMS_URI can be unset)

Service and features

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_SERVICE_LISTEN_ADDRstring""AllListener address of Vault
PVAULT_SERVICE_ADMIN_API_KEYstring"pvaultauth"AllThe admin API key for authentication
PVAULT_SERVICE_FORCE_ACCESS_REASONbooltrueAllWhether Vault should force a valid access reason to be provided with calls
PVAULT_SERVICE_ADMIN_MAY_READ_DATAboolMode dependentAllWhether Admin is allowed to read data
PVAULT_FEATURES_ENCRYPTIONbooltrueAllThis variable is ignored in production. In production, properties set as is_encrypted are always stored encrypted. When this variable is set to false (only in PVAULT_DEVMODE), properties stored unencrypted.
PVAULT_FEATURES_API_KEY_HASHINGbooltrueAllWhether API keys for users are hashed when stored on the database
PVAULT_FEATURES_POLICY_ENFORCEMENTbooltrueAllWhether policy management is enforced
PVAULT_FEATURES_MASK_LICENSEboolfalseAllWhether Vault's service license will be masked while retrieving it using Get license API or Get license CLI
PVAULT_FEATURES_CUSTOM_TYPES_ENABLEboolfalseAllWhether Vault should read the pvault.types.toml file and apply the custom types, transformations and validators that it includes.
PVAULT_SERVICE_TIMEOUT_SECONDSfloat30AllTimeout in seconds for REST API calls
PVAULT_SERVICE_DEFAULT_PAGE_SIZEint100AllThe default page size for object queries when the page size is not specified. The page size is the maximum number of objects that may be requested in one call.
PVAULT_SERVICE_MAX_PAGE_SIZEint1000AllThe maximum page size that can be specified for a call. The page size is the maximum number of objects that may be requested in one call.
PVAULT_SERVICE_CACHE_REFRESH_INTERVAL_SECONDSint30AllThe refresh interval in seconds of the control data cache that serves the data APIs (under /api/pvlt/1.0/data/). If this value is zero the cache is disabled.

Logs and telemetry

See Logs for more information on logs and telemetry.

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_LOG_LEVELstring"info"AllLog level (supports debug, info, warn, and error)
PVAULT_LOG_DATADOG_ENABLEbooltrueAllEnable Datadog logs and metrics
PVAULT_LOG_DATADOG_ENVstring"prod"AllControls env field of logs sent to Datadog
PVAULT_LOG_DATADOG_APM_ENABLEboolfalseAllEnable Datadog application performance monitoring (APM)
PVAULT_SENTRY_ENABLEbooltrueAllEnable Sentry telemetry logging
PVAULT_LOG_CUSTOMER_IDENTIFIERstring AllIdentifies the customer in all the observability platforms
PVAULT_LOG_CUSTOMER_ENVstring AllIdentifies the environment in all the observability platforms. Recommended values are PRODUCTION, STAGING, and DEV


See TLS for more information on configuring Piiano Vault to use TLS.

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_TLS_SELFSIGNEDboolfalseAllWhether Vault runs with a self-signed TLS key (valid for 24h)
PVAULT_TLS_ENABLEboolMode dependentAllWhether Vault listens on HTTPS (TLS). If false, Vault listens on HTTP. If PVAULT_TLS_SELFSIGNED is true, this setting is ignored and Vault listens on HTTPS.
PVAULT_TLS_CERT_FILEstring""AllPath to the TLS certificate file. Must be valid to enable listening on HTTPS (TLS)
PVAULT_TLS_KEY_FILEstring""AllPath to the TLS key file. Must be valid to enable listening on HTTPS (TLS)

Time to live

NameTypeDefault (Dev / Server)EditionDetails
Objects don't expire
AllDefault time to live (TTL) for tokens.
Objects don't expire
AllDefault time to live (TTL) for associated object.
Objects don't expire
AllDefault time to live (TTL) for unassociated object.

The duration string is a decimal fraction with a time unit suffix, such as "300ms", "-1.5h", or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", and "h".

Docker Compose configurations

These environment variables can be used when installing Piiano Vault server using Docker Compose:

SERVER_API_PORTint8123Server / ServerXListener port for Vault Server and of the router (Traefik) for ServerX
CONTROL_API_PORTint8123ServerXListener port for the control plane of Vault
DATA_API_PORTint8123ServerXListener port for the data plane of Vault
TRAEFIK_DASH_PORTint8080ServerXListener port for the router (Traefik) dashboard