Appearance

Variable Substitution ​

Use variable substitution in policy files to avoid storing sensitive credentials (passwords, API keys, etc.) in plaintext. Variables are resolved by the Sandbox Manager service before the policy is delivered to the Launcher.

What You'll Learn

  • How to reference secrets without storing plaintext in policy
  • Variable syntax
  • CRED source backed by Windows Credential Manager
  • ENV source backed by process environment variables
  • Resolution flow and fallback behavior
  • How to sanity-check CRED and ENV variable resolution
  • Example: Proxy flags with credentials

Syntax ​

Variables use the format:

{{SOURCE:key:field}}

Where:

  • SOURCE: The variable source (CRED for Windows Credential Manager, ENV for environment variables)
  • key: The identifier for the credential or variable
    • For CRED: The credential key (without the turbo: prefix)
    • For ENV: The name of the environment variable
  • field: The specific field to retrieve (for CRED, username or password; ignored for ENV)

Windows Credential Manager (CRED) ​

The CRED source reads credentials from Windows Credential Manager using the naming convention turbo:{key}.

Example:

json
{
  "configuration": {
    "launch": {
      "flags": [
        "--proxy-server=socks5://{{CRED:PolicyProxy001:username}}:{{CRED:PolicyProxy001:password}}@proxy.corporate.local:1081"
      ]
    }
  }
}

Environment variables (ENV) ​

The ENV source reads values from environment variables on the host operating system. This is useful when your deployment tooling or service manager already injects secrets into the Sandbox Manager or Launcher process environment (for example, via systemd, launchd, container environment variables, or other configuration management tools).

json
{
  "configuration": {
    "launch": {
      "flags": [
        "--proxy-server=socks5://{{ENV:PROXY_USER}}:{{ENV:PROXY_PASS}}@proxy.corporate.local:1081"
      ]
    }
  }
}

Syntax ​

text
{{ENV:VARNAME}}
  • VARNAME: The name of the environment variable to read.
  • If the environment variable is not defined in the process environment, the substitution resolves to an empty string.
  • An optional third field segment is ignored for ENV, but the recommended form is the two-part {{ENV:VARNAME}}.

Platform and process context ​

The ENV source uses the environment of the process that resolves policy:

  • In managed deployments, ensure the Sandbox Manager service (or equivalent host service) is started with the required environment variables defined.
  • On Windows, macOS, and Linux, use your standard tooling (for example, service configuration, systemd units, launchd plists, container environment settings, or secret-management agents) to inject the variables.

Using ENV lets you keep secrets in your existing secret-management pipeline (for example, OS-native keychains, cloud secret managers, or CI/CD systems) and only expose them to Turbo via process environment variables, without storing the plaintext values in policy files.

Setting Up Windows Credentials ​

Credentials must be stored in Windows Credential Manager with target names that start with turbo: (required prefix) under the account context where the Sandbox Manager service runs (typically SYSTEM).

Simple example:

cmdkey /generic:"turbo:PolicyProxy001" /user:"proxyuser" /pass:"SecurePass123!"

Verify credentials:

cmdkey /list | findstr "turbo"

Service account context matters

cmdkey stores credentials for the current Windows account only. The Sandbox Manager resolves CRED variables using the Windows Credential Manager store for the account that the Sandbox Manager service runs under (typically SYSTEM, or a configured domain service account).

  • Run cmdkey in the Sandbox Manager service account context so that CRED-backed variables referenced in policy are readable by the service.
  • Credentials created under a different interactive user account are not visible to the Sandbox Manager; in that case, those substitutions resolve to empty strings and authentication fails (for example, proxy connections always fail with authentication errors).
  • For managed deployments, provision these credentials via your standard configuration tooling (for example, GPO, configuration management, or RMM) using the correct service account.

Security Model ​

  • Policy file (%PROGRAMDATA%\Turbo\Launcher\policy.json): Contains variable references (no plaintext secrets).
  • Credentials: Stored in Windows Credential Manager under the Sandbox Manager service account context.
  • Resolution: Performed by the Sandbox Manager service before delivering policy to the Launcher.

Fallback behavior

If the Sandbox Manager is unavailable, the Launcher reads policy directly but cannot resolve credentials from the service account context. In this case, variables resolve to empty strings.

Testing and diagnostics ​

When introducing new {{CRED:...}} variables, validate resolution in a controlled way before rolling changes into production.

Quick sanity check for CRED variables

  1. Confirm the Sandbox Manager account
    Identify which Windows account the Sandbox Manager service runs under (typically SYSTEM or a domain service account).

  2. Create credentials for that account
    Run cmdkey in that account's context so the credentials are written to the correct Windows Credential Manager store, for example:

    cmd
    cmdkey /generic:"turbo:PolicyProxy001" /user:"proxyuser" /pass:"SecurePass123!"
cmdkey /list | findstr "turbo"

  3. Use a benign diagnostic flag
    In a test policy, reference the credential in a non-sensitive flag or argument so you can confirm substitution without exposing the secret value. For example:

    json
    {
  "configuration": {
    "launch": {
      "flags": [
        "--diag-cred-test=PolicyProxy001:{{CRED:PolicyProxy001:username}}"
      ]
    }
  }
}

  4. Inspect resolved policy or logs On a test device, let the Sandbox Manager resolve policy, then:

    • Inspect the resolved policy or Launcher logs for --diag-cred-test=PolicyProxy001:<username>.
    • Verify that the flag is present and the username is correct. The password is never logged and should not be printed.

When available in your environment, use CLI-based policy inspection tools to review a resolved copy of policy (with variables substituted) on a secure admin workstation. Refer to the Turbo CLI documentation for the exact command syntax and options.

Common Use Cases ​

Proxy with Authentication (Global Configuration) ​

json
{
  "version": "1.1",
  "configuration": {
    "launch": {
      "flags": [
        "--proxy-server=socks5://{{CRED:PolicyProxy001:username}}:{{CRED:PolicyProxy001:password}}@proxy.corporate.local:1081"
      ]
    }
  }
}

See also ​

Turbo.net © 2025