Customer environment variables for self-hosted Masker

If you are running Masker in your own VPC or on-premises, a small set of environment variables controls how Masker handles encryption keys and authenticates CLI commands against your server. Hosted SaaS customers on masker-voice.fly.dev do not configure these directly — they are managed by Masker’s infrastructure. This page covers only the variables that you, as a self-hosted operator, are responsible for setting.

For deployment configuration (server address, database URL, upstream LLM endpoint, and so on), see the deployment guide, which includes annotated Docker and Kubernetes examples.

Encryption keys

Masker uses symmetric 256-bit keys for tokenization and AEAD operations. Each key is identified by a key ID (kid) that matches a corresponding entry in your mask policy. The environment variable name is always MASKER_KEY_<KID>, where <KID> is the key ID in uppercase.

Variable	Example value	Description
`MASKER_KEY_K_HEALTHCARE`	`base64(32 bytes)`	Active encryption key for the `K_HEALTHCARE` kid. Required if your policy uses `kid: K_HEALTHCARE`.
`MASKER_KEY_K_HEALTHCARE_OLD`	`base64(32 bytes)`	Previous key, kept during rotation so that tokens minted under the old key can still be rehydrated.

Generate a key with:

openssl rand -base64 32

The value must be a base64-encoded 32-byte (256-bit) secret. Masker will refuse to start if a kid referenced in the policy has no matching key variable.

Never put raw key values in source control, Dockerfiles, or unencrypted config files. Inject them from your secret store (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Kubernetes Secret, or flyctl secrets set).

Key rotation

Masker supports zero-downtime key rotation. The process is:

Generate a new key

NEW_KEY=$(openssl rand -base64 32)

Set both the new and old keys

Add the new key as MASKER_KEY_K_HEALTHCARE and move the current key to MASKER_KEY_K_HEALTHCARE_OLD. Both variables must be present during the grace period.

# Example using flyctl secrets
flyctl secrets set \
  MASKER_KEY_K_HEALTHCARE="$NEW_KEY" \
  MASKER_KEY_K_HEALTHCARE_OLD="$CURRENT_KEY"

Restart Masker

Masker picks up the new key at boot. New tokens are minted under the new key. Rehydration of existing tokens falls back to _OLD automatically.

Re-encrypt the vault (optional)

If you are using vault-deterministic tokenization, you can re-encrypt all stored tokens under the new key:

masker vault rotate-key --new-kid K_HEALTHCARE

This is optional — the _OLD key handles rehydration of legacy tokens for as long as you keep it set.

Remove the old key after the grace period

Once you are confident no sessions are holding unrehydrated tokens from the old key, remove MASKER_KEY_K_HEALTHCARE_OLD. After this point, tokens minted under the old key can no longer be rehydrated.

The default grace period Masker tracks internally is 30 days. Any token older than that is unlikely to be waiting for rehydration in an active session.

CLI authentication

The masker CLI can talk to a remote Masker server for commands like masker sessions list, masker report, and masker policy reload. These commands require a session credential.

Variable	Description
`MASKER_SESSION`	Session cookie for authenticating CLI commands against a remote server.

To obtain the value, sign in to your Masker portal, open your browser’s developer tools, and copy the value of the masker_session cookie.

export MASKER_SESSION=ey...

# Then use any remote command:
masker sessions list --server https://masker.your-vpc.example
masker report --server https://masker.your-vpc.example --since 7d --output weekly.pdf

A scoped, long-lived CLI token that does not require copying a browser cookie is on the May 30 roadmap. Until then, MASKER_SESSION is the supported authentication mechanism for remote CLI commands.

Config file path

Variable	Default	Description
`MASKER_CONFIG`	`./masker.toml`	Path to the `masker.toml` CLI configuration file. Overrides the default search path.

The CLI resolves its config file in this order:

--config <path> flag
MASKER_CONFIG environment variable
./masker.toml in the current directory
~/.config/masker/config.toml

See the CLI reference for the full masker.toml format.

Setting variables in common environments

Docker
Kubernetes
Fly.io

Pass secrets via an env file rather than inline flags to avoid values appearing in ps output or shell history:

# masker.secrets.env (never commit this file)
MASKER_KEY_K_HEALTHCARE=<base64 key>
MASKER_KEY_K_HEALTHCARE_OLD=<base64 previous key>
MASKER_SESSION=<portal cookie>

docker run -d \
  --env-file ./masker.secrets.env \
  ghcr.io/masker-dev/masker:latest

Store keys in a Kubernetes Secret and mount them as environment variables:

apiVersion: v1
kind: Secret
metadata:
  name: masker-keys
stringData:
  MASKER_KEY_K_HEALTHCARE: "<base64 key>"
  MASKER_KEY_K_HEALTHCARE_OLD: "<base64 previous key>"

# In your Deployment spec
envFrom:
  - secretRef:
      name: masker-keys

Use flyctl secrets set — values are encrypted at rest and injected at runtime:

flyctl secrets set \
  MASKER_KEY_K_HEALTHCARE=$(openssl rand -base64 32) \
  MASKER_SESSION=ey...

Get Started

Masking

Integrations

Compliance

Configuration

Customer environment variables for self-hosted Masker

Encryption keys

Key rotation

CLI authentication

Config file path

Setting variables in common environments

Get Started

Masking

Integrations

Compliance

Configuration

Documentation Index

​Encryption keys

​Key rotation

​CLI authentication

​Config file path

​Setting variables in common environments

Encryption keys

Key rotation

CLI authentication

Config file path

Setting variables in common environments