Variables Registry

The Variables Registry lets you store and manage key-value configuration variables that modules and workflows can read at runtime. Access it in the portal at Operations → Variables Registry, or via the CLI with cs config and the PowerShell module with Get-CSConfig / Set-CSConfig.

On-premises — Docker Compose .env file

The Docker Compose stack reads configuration from /opt/cloudsmith/.env inside the cloudsmith-docker VM. The installer generates this file during setup. You can edit it and run docker compose -f /opt/cloudsmith/docker-compose.yml up -d to apply changes.

# SSH into the CloudSmith VM
ssh cloudsmith@192.168.100.10

# Edit the .env file
sudo nano /opt/cloudsmith/.env

# Apply changes
sudo docker compose -f /opt/cloudsmith/docker-compose.yml up -d

Required variables

Optional variables

Relay environment variables

The CloudSmith Relay runs as a Docker container on a Linux host inside the cluster network. Configure it with the following environment variables when deploying the cloudsmith-relay container.

The relay persists its enrolled identity in /var/lib/cloudsmith-relay/identity. Mount a named Docker volume at this path so the identity survives container restarts:

docker run -d --name cloudsmith-relay --restart=always \
  -e RELAY_PAAS_URL=https://<your-paas-api-url> \
  -e RELAY_ENROLLMENT_TOKEN=<one-time-token> \
  -e RELAY_AGENT_ENROLLMENT_TOKEN=<your-agent-secret> \
  -e RELAY_DISPLAY_NAME=relay-prod-hci-01 \
  -p 8443:8443 \
  -v cloudsmith-relay-identity:/var/lib/cloudsmith-relay/identity \
  ghcr.io/cloudsmith-cloud/cloudsmith-relay:latest

See Install the CloudSmith Relay for the full deployment procedure.

Agent environment variables

The CloudSmith Agent is a Windows Service. It reads configuration from Windows Service environment variables stored in the registry under HKLM\SYSTEM\CurrentControlSet\Services\CloudSmithAgent\Environment. Set these registry values before starting the service.

$regPath = 'HKLM:\SYSTEM\CurrentControlSet\Services\CloudSmithAgent\Environment'
New-Item -Path $regPath -Force | Out-Null
New-ItemProperty -Path $regPath -Name 'AGENT_RELAY_URL'        -Value 'http://<relay-lan-ip>:8443' -PropertyType String -Force
New-ItemProperty -Path $regPath -Name 'AGENT_ENROLLMENT_TOKEN' -Value '<your-agent-secret>'        -PropertyType String -Force

Required variables

Optional variables

See Install the CloudSmith Agent for the full installation procedure.

OpenTelemetry / Azure Monitor variables (on-premises)

These variables are optional on-premises. Configure them when you want to forward telemetry to Azure Monitor or a self-hosted OpenTelemetry Collector.

On-premises — appsettings.json

appsettings.json is embedded in the cloudsmith-api container image at /app/appsettings.json. In most deployments, all configuration is supplied via environment variables (which take precedence over appsettings.json). Override individual settings by mounting a custom appsettings.Local.json volume.

{
  "CloudSmith": {
    "DeploymentMode": "OnPremises",
    "PublicUrl": "",
    "MasterKey": "",
    "UpdateCheckEnabled": true,
    "UpdateCheckIntervalHours": 24,
    "MaxRelayHeartbeatIntervalSeconds": 60
  },
  "ConnectionStrings": {
    "DefaultConnection": ""
  },
  "Jwt": {
    "ExpiryMinutes": 15,
    "RefreshTokenDays": 7
  },
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    }
  },
  "OpenTelemetry": {
    "Enabled": true,
    "ServiceName": "cloudsmith-api",
    "AzureMonitorWorkspaceEndpoint": "",
    "AzureMonitorDceEndpoint": "",
    "OtlpExporterEndpoint": ""
  }
}

To apply a custom override:

# In docker-compose.yml
services:
  cloudsmith-api:
    volumes:
      - /opt/cloudsmith/appsettings.Local.json:/app/appsettings.Local.json:ro

Azure PaaS — Azure Container Apps environment variables

In the PaaS model, all configuration is supplied as ACA environment variables. Variables marked as secrets in the Bicep template are stored in Azure Key Vault and injected into the container via ACA secret references — they never appear in plaintext in the ACA environment variable list.

Required ACA environment variables

Optional ACA environment variables

PaaS — Key Vault secret references

The master encryption key is a sensitive value that must never appear in plaintext in a container app environment variable list or in version control. In the PaaS deployment, CloudSmith stores it as a Key Vault secret and references it via the ACA secret reference pattern.

How it works

1. During azd up, the Bicep template creates the cloudsmith-master-key secret in Key Vault.
2. The API container app is configured with an ACA secret that references the Key Vault secret URI.
3. ACA resolves the secret value at startup and injects it as the CLOUDSMITH_MASTER_KEY environment variable inside the container.
4. The Managed Identity attached to the API container app has the Key Vault Secrets User role assignment on the Key Vault, which grants read access to the secret.

The secret value is never visible in the Azure portal’s container app environment variable list — it appears as (hidden).

Rotating the master key

# Set a new master key value in Key Vault
$newKey = [System.Convert]::ToHexString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
az keyvault secret set `
    --vault-name 'kvcloudsmithprodcus001...' `
    --name 'cloudsmith-master-key' `
    --value $newKey

# Force a new ACA revision to pick up the updated secret
az containerapp update `
    --name 'ca-cloudsmith-api-prod-cus-001' `
    --resource-group 'rg-cloudsmith-prod-cus-001'

Warning: Rotating the master key without first re-encrypting all secrets stored in the database will make those secrets unreadable. Key rotation requires a database re-encryption step. This procedure is documented in the troubleshooting guide.

azd environment parameters

When deploying with the Azure Developer CLI, configuration is supplied as azd environment variables rather than ACA environment variables directly. The Bicep template maps azd parameters to ACA and Key Vault at deploy time.

See Azure PaaS install — step 4 for the full azd env set reference.

Key parameters: