Policy Schema Reference

Field-by-field reference for application policies, file types, file associations, file policies, and global configuration. See concept pages for behavior details.

What You'll Learn

The structure of the policy.json file
Field definitions for apps, file types, and routing
Global configuration options for runtime and network

Concepts: Policy Overview
Authorization & Visibility: Authorization & Visibility
Matchers & Patterns: Matchers & Patterns
Modifications & Flags: Modifications & Flags
Launch Profiles: Launch Profiles
File Types & Routing: File Types & Routing
Merging & Precedence: Merging & Precedence

Top-level structure

json

{
  "policyVersion": 1,
  "policySignature": "base64-cms",
  "signatureCertificateThumbprints": ["AA11...BB22"],
  "configuration": { ... },
  "configurationTemplates": [ ... ],
  "apps": [ ... ],
  "fileTypes": [ ... ],
  "fileAssociations": [ ... ],
  "files": [ ... ]
}

Top-level fields

policyVersion (integer) — Monotonic version for rollout/rollback tracking.
policySignature (string) — Detached CMS/PKCS#7 signature in base64 for this policy.
signatureCertificateThumbprints (string[]) — Allowed signer certificate thumbprints used to validate policySignature. Accepts 64‑hex (SHA‑256) or 40‑hex (SHA‑1).
configuration templates (configurationTemplates, array) — Enterprise-defined reusable constraints for environment variables and mounts. See: Configuration Templates.

Schema versioning and compatibility

The policy JSON has two distinct version concepts:

policyVersion (integer, field on the policy object)
- Monotonic counter used for rollout, rollback, and telemetry.
- Interpreted only by policy distribution/orchestration systems and audit tooling.
- Does not describe the shape of the policy or which fields are allowed.
Schema version (version of the JSON Schema that defines the policy shape)
- Describes which fields, enums, and structures are valid.
- Evolves over time as new features are added or behavior changes.
- Is independent from policyVersion.

Do not overload policyVersion as a schema version. Use it strictly for deployment tracking (for example, "production=42", "canary=43"), while schema evolution is managed by the $schema directive and the compatibility rules below.

Schema artifacts and SemVer

The Launcher policy schema follows Semantic Versioning (SemVer):

MAJOR — Backward-incompatible changes, such as:
- Removing fields or changing field types.
- Changing behavior in a way that would cause older clients to mis-enforce policy.
MINOR — Backward-compatible extensions, such as:
- Adding new optional fields or enum values.
- Adding new nested objects that clients may safely ignore if unknown.
PATCH — Backward-compatible bug fixes, such as:
- Clarifications, documentation-only fixes, or schema corrections that do not change which instances are valid.

Schemas are exposed via a stable URL and, when needed, versioned URLs:

Stable latest for the current supported MAJOR line (recommended for most editors):
- https://schemas.turbo.net/launcher-policy.schema.json
Explicit versions (example pattern):
- https://schemas.turbo.net/launcher-policy/schema.json

The stable URL always points to the latest backward-compatible MINOR/PATCH within the currently supported MAJOR line.

Client behavior with schema versions

When loading a policy, the Launcher evaluates schema compatibility before enforcing the policy.

Determine the policy schema version
- From the $schema URL when present, or
- From internal schema metadata bundled with the client when $schema is omitted.
Compare the policy schema MAJOR with the client’s supported MAJOR
- If the policy MAJOR is greater than the client MAJOR (for example, policy is 2.x, client only supports 1.x):
  - The policy is treated as unsupported.
  - The client must not attempt partial enforcement.
  - The client should:
    - Prefer fail-closed behavior by falling back to a last-known-good (LKG) policy when configured, or
    - Deny launches and surface an explicit error if no LKG policy exists.
- If the policy MAJOR is equal but MINOR/PATCH are higher:
  - The policy is treated as forward-compatible and the rules below apply.
Forward-compatibility rules within the same MAJOR
Clients must behave as follows to tolerate newer MINOR/PATCH schemas:
- Unknown fields on known objects:
  - Must be ignored while preserving the rest of the object.
- Unknown enum values for known fields:
  - For configuration fields, unknown values are treated as unsupported and the documented default or safest fail-closed behavior applies.
- Unknown top-level sections:
  - Must be ignored; they are reserved for future expansion.
- Optional fields that become required in a newer schema:
  - Older clients treat them as optional; behavior is governed by the documented defaults.
These rules ensure that a 1.3 client can safely consume a policy authored against a 1.5 schema, provided no MAJOR breaking changes were introduced.
Telemetry and troubleshooting
Clients emit telemetry containing:
- Applied policyVersion.
- Effective schema MAJOR.MINOR.PATCH used for validation.
- Any forward-compatibility fallbacks applied (for example, unknown fields, unknown enum values, unsupported sections).

Deprecation policy

To minimize breaking changes:

Fields and enum values are first marked as deprecated in this documentation and release notes.
Deprecated fields remain accepted for at least one full MAJOR schema line (for example, all 1.x) before removal.
When a field is deprecated:
- New policies should avoid using it.
- Clients continue to accept it but may log a warning.
Removal of deprecated fields or behavior changes that cannot be made backward-compatible only occur in a new MAJOR schema version.

Identity and uniqueness

apps[].id: Required. Unique within apps[]; stable identifier referenced by fileAssociations.verbs[].appRef. When two enabled app policies have the same priority, ties break by id (alphabetical).
apps[].profiles[].id: Required. Unique within its parent application. Stable identifier used for profile-level merges and tie-breaks; not globally unique across apps.
apps[].profiles[].displayName: Required. UI text; not used for identity.
fileTypes[].id: Required. Unique within fileTypes[]; referenced by fileAssociations[].fileTypeRef.
fileAssociations[].id: Recommended. Unique within fileAssociations[]; stable rule identity and tie‑break key after priority (alphabetical). If missing, fallback to rule displayName.
files[].id: Recommended. Unique within files[]; stable rule identity and tie‑break key after priority (alphabetical). If missing, fallback to rule displayName.
Handler arrays (routing verbs open/edit/print/preview): Handlers are not named. If multiple handlers are eligible:
- First pick any handler with default: true (within the selected rule).
- Else pick from the rule with highest priority.
- If still tied across rules, use rule id alphabetical (fallback to rule displayName when id is missing).
- Within a single rule and no explicit default: array order applies.
appRef refers to apps[].id. If no enabled app policy with action: "allow" matches the target executable, the routing handler is ignored.

Profile Naming Conventions

Use distinct labels for each profile-related concept to avoid confusion in policies and support tickets.

Launch profiles (apps[].profiles[]): Treat these as app variants. Use id values that describe the action (chrome-incognito, word-readonly) and displayName text that reads well in the context menu (for example, "Run Chrome (Incognito)").
User configurations (user-profiles.json → profiles[]): Refer to these as configurations in UI text and documentation to distinguish them from launch profiles. Use stable, kebab-case ids that include the template purpose (user-project-alpha, user-p4-shared) and keep displayName user-friendly ("Project Alpha Configuration").
Configuration templates (configurationTemplates[].id and apps[].configurationTemplates): Name templates after the constraint set they enforce (p4-shared-environment, dlp-reviewed-mounts) and avoid reusing the same id/displayName strings used by launch profiles or user configurations.
In customer-facing text, prefer “launch profile” for context menu variants, “user configuration” for per-user files, and “configuration template” for enterprise-governed constraints.

Application policy (apps[] items)

Field	Type	Required	Description
id	string	Yes	Immutable unique identifier for the app policy; unique within apps[]; referenced by fileAssociations.verbs[].appRef; used for tie-break at equal priority. Use stable, URL-safe ids (kebab-case recommended).
displayName	string	Yes	Human-readable label shown in UI and examples.
enabled	boolean	Yes	Whether this policy is active.
priority	number	Yes	Higher numbers take precedence in merges; ties break by id (alphabetical).
visibility	"visible" or "hidden"	No	Controls UI presence; hidden apps can still be used by routing. See: Authorization & Visibility.
visibilityConstraints	VisibilityConstraints	No	Restricts visibility to specific selected sites. See: Sites.
targetPath	string	No	Direct executable path (alternative to `matchAll`/`matchAny` for system utilities). Supports Windows environment variables (e.g., `%SYSTEMROOT%`).
matchAll	(Matcher \| MatchGroup)[]	Yes*	Logical AND: all items must match. Can contain nested groups. See: Matchers & Patterns.
matchAny	(Matcher \| MatchGroup)[]	Yes*	Logical OR: at least one item must match. Can contain nested groups.
action	"allow" or "deny"	Yes	Authorization action. Deny explicitly blocks matching executables and takes precedence over allow when both match. See: Merging & Precedence.
identityRequirements	string[]	No	List of identity checks that must also validate: "publisherCertificate", "fileHash", "version". All listed requirements must pass in addition to matchAll/matchAny.
authorization	Authorization	No	ABAC requirements and optional approval gating evaluated after allow matchers and before launch (userAttributes, contextConstraints, and approval). See: Authorization & Visibility.
modifications	Modifications	No	VM flags, structured mounts, and argument edits applied when launching. See: Modifications & Flags.
profiles	Profile[]	No	Additional launch variants. See: Launch Profiles.
capabilities	AppCapability[]	No	Per-app declaration of supported file types and verbs. See below.
configurationTemplates	string[]	No	Template ids enabling user configurations for this app. See: Configuration Templates.

Either matchAll or matchAny is required. You can only have one of each at each level (AND or OR), but they can be nested.

VisibilityConstraints

Field	Type	Required	Description
siteRefs	string[]	No	Array of site IDs. App is visible only when the selected site matches one of these.

Matcher

json

{ "type": "targetPath", "pattern": "C:\\\\**\\\\myapp.exe", "patternType": "glob" }

Field	Type	Required	Description
type	enum	Yes	shortcutName, targetPath, arguments, publisherCertificate, fileHash, version
pattern	string	Yes	Pattern text.
patternType	enum	Yes	exact, regex, glob. See: Matchers & Patterns.
field	enum	No	For `publisherCertificate` matchers, specifies certificate field to match: thumbprint, subjectCN, issuerCN, subjectDN, issuerDN.

Publisher certificate field targeting

If type is publisherCertificate and field is provided:
- field: "thumbprint" → patternType must be "exact" and pattern must match ^(?:[A-Fa-f0-9]{64}|[A-Fa-f0-9]{40})$.
- field: "subjectDN" or "issuerDN" → patternType must be "regex" (apply to the full DN; anchor on CN= to avoid ambiguity).
- All comparisons are case-insensitive.

Authorization (apps[].authorization)

Augments allow policies with attribute- and context-based constraints, evaluated after an allow policy matches and before launch. All specified requirements must pass; otherwise the launch is denied.

Structure

json

{
  "authorization": {
    "requirements": {
      "userAttributes": [
        { "attribute": "usPersonStatus", "allowedValues": ["verified"] }
      ],
      "contextConstraints": {
        "allowedGeos": ["US"],
        "requireCompliantHost": true
      }
    },
    "approval": {
      "mode": "required",
      "workflowRef": "manager-approval-app-launch",
      "reuse": {
        "policy": "perUserPerApp",
        "ttlSeconds": 86400
      }
    }
  }
}

Fields

requirements.userAttributes[]:
- attribute (string): key defined in configuration.identity.claimsMapping (e.g., "usPersonStatus")
- allowedValues (string[]): one or more normalized values
requirements.contextConstraints.allowedGeos (string[]): ISO 3166-1 alpha-2 country codes (e.g., "US")
requirements.contextConstraints.requireCompliantHost (boolean): requires compliant host per configuration.security.hostAttestation

Semantics

Evaluated only when an enabled app policy with action: "allow" matches (matchAll/matchAny).
Deny-on-fail: if any requirement fails (attributes mismatch or host non-compliant under enforce mode), the launch is denied.
Complements identityRequirements; both may be present.
When authorization.approval.mode is set to "required", a successful approval workflow is also required before appLaunch is allowed. Approval workflows are defined globally under configuration.launch.runtime.approval.
See behavior and examples: Authorization & Visibility.

Authorization Approval (apps[].authorization.approval)

Optional approval gating evaluated after matchers and ABAC requirements. Use this when you want applications to appear in the Applications tab but require an approval workflow before launch or for specific in-app operations.

Fields

mode (string, optional): "none" | "required" | "conditional".
- "none" (default): no approval gate; behavior matches existing ABAC-only authorization.
- "required": approval is required before appLaunch is allowed.
- "conditional": implementation may request approval under certain runtime conditions (for example, elevated risk posture). Semantics are implementation-defined; use when coordinated with platform guidance.
workflowRef (string, optional): references configuration.launch.runtime.approval.workflows[].id. When set and mode is not "none", this workflow is used to gate appLaunch. When omitted, the runtime may fall back to configuration.launch.runtime.approval.defaults.appLaunchWorkflowRef.
reuse (object, optional): Controls when approvals can be reused instead of re-requested.
- policy (string, required when reuse is present): "perLaunch" | "perSession" | "perUserPerApp".
- ttlSeconds (integer, optional): time-to-live in seconds for an approval within the chosen reuse boundary. When omitted, the runtime default applies.
operations (array, optional): optional per-operation approval rules for in-app actions.
- operations[].operationId (string, required): logical operation identifier (for example, "appOperation.crm.exportSensitiveData").
- operations[].workflowRef (string, required): workflow id to use for this operation. References configuration.launch.runtime.approval.workflows[].id.
- operations[].reuse (object, optional): same shape as authorization.approval.reuse.

Notes

Use mode: "required" on authorization.approval to make discovered applications visible but require approval before launch into the Secure Sandbox runtime.
Operation identifiers under authorization.approval.operations[] provide a flexible contract for app-specific actions. Apps or external processors raise events with the configured operationId values, and the policy engine uses the associated workflows to gate those actions.

Modifications

json

{
  "runtime": {
    "isolation": { "remoteSandbox": true }
  },
  "arguments": { "prepend": "--safe-mode", "append": "--incognito", "replace": "--kiosk" },
  "mounts": [
    { "name": "Desktop", "source": "@DESKTOP@", "destination": "@DESKTOP@", "options": ["read-write"] }
  ]
}

Field	Type	Required	Description
runtime	Runtime	No	Structured runtime settings (isolation, composition, visual, clipboard, files.contexts, devices, extensions). Replaces raw flags.
arguments	Arguments	No	Command-line edits. `replace` overrides prepend/append. Scope precedence: Launch Profile > Policy > Global.
mounts	StructuredMount[]	No	Validated mounts applied when this app launches. See: Modifications & Flags.

Runtime

Field	Type	Required	Description
clipboard	Clipboard	No	VM clipboard size and direction settings.
isolation	Isolation	No	Session isolation settings.
visual	Visual	No	Visual appearance settings.

Clipboard

Field	Type	Required	Description
mode	string	No	Clipboard direction. Values: `Bidirectional`, `InboundOnly`, `OutboundOnly`, `Isolated`. Synthesized as `--clipboard-mode`.
size	number	No	Maximum clipboard size in bytes for both directions. Set to 0 for unlimited. Synthesized as `--clipboard-size`.
sizeInbound	number	No	Maximum inbound clipboard size in bytes (host to session). Overrides `size` for inbound. Synthesized as `--clipboard-size-inbound`.
sizeOutbound	number	No	Maximum outbound clipboard size in bytes (session to host). Overrides `size` for outbound. Synthesized as `--clipboard-size-outbound`.
imageMaxPixels	number	No	Maximum clipboard image size in pixels (width × height). Set to 0 for unlimited. Synthesized as `--clipboard-image-max-pixels`.

Isolation

Field	Type	Required	Description
remoteSandbox	boolean	No	Run in a remote sandbox. Synthesized as `--remote-sandbox`.

Visual

Field	Type	Required	Description
borderColor	string	No	Border color for testing/authoring. Format: `"#AARRGGBB"` (alpha-ARGB) or named color. Example: `"#80008200"`. Synthesized as `--skin-border-color`.

Arguments

Field	Type	Required	Description
prepend	string	No	Added before base args.
append	string	No	Added after base args.
replace	string	No	Replaces entire arg string.

StructuredMount

Field	Type	Required	Description
name	string	No	Optional identity key used for merge/tie-breaks.
source	string	Yes	Host path; supports well-known tokens and Windows env vars.
destination	string	Yes	Container path inside the runtime.
options	("read-write" \| "read-only")[]	No	Mount access options.

Launch Profile

json

{
  "id": "profile-id",
  "displayName": "Chrome (Incognito)",
  "actionText": "Run Chrome (Incognito)",
  "arguments": { "append": "--incognito" },
  "runtime": { "clipboard": { "size": 200 } },
  "mounts": [ { "name": "DiagDump", "source": "%TEMP%\\MyApp\\Diag", "destination": "P:\\Diag", "options": ["read-write"] } ],
  "postLaunchAction": { "type": "OpenFolder", "path": "%LOCALAPPDATA%\\Turbo\\Containers\\sandboxes\\{ContainerId}\\logs" }
}

Field	Type	Required	Description
id	string	Yes	Unique within this app; identity for profile conflict resolution.
displayName	string	Yes	Profile name.
actionText	string	No	UI text for the context menu action.
arguments	Arguments	No	Profile-scope argument edits.
runtime	Runtime	No	Profile-scope runtime settings.
mounts	StructuredMount[]	No	Mounts applied only when this profile is selected.
postLaunchAction	PostLaunchAction	No	Action after launch (OpenFolder).

PostLaunchAction

Field	Type	Required	Description
type	enum	Yes	"OpenFolder".
path	string	Yes	Path; supports `{ContainerId}` and Windows env vars (e.g., `%LOCALAPPDATA%`).

AppCapability (apps[].capabilities[])

json

{
  "fileTypeRef": "pdf",
  "verbs": {
    "open": { "arguments": "\"%1\"" },
    "print": { "arguments": "/p \"%1\"" },
    "extract": { "arguments": "/c tar -xf \"%1\" -C \"%~dpn1\"" }
  }
}

Field	Type	Required	Description
fileTypeRef	string	Yes	References fileTypes[].id.
verbs	Dictionary<string, CapabilityVerbOptions>	No	Dictionary mapping verb names to invocation details. Supports standard verbs (`open`, `edit`, `print`) and custom verbs (e.g., `extract`).

CapabilityVerbOptions

Field	Type	Required	Description
arguments	string	No	Command string; supports variable substitution (`%1`, `%~dp1`, `%~n1`, `%~dpn1`).
vmFlags	string[]	No	Additional flags for this verb; supports variable substitution.

File Types (fileTypes[] items)

Central registry defining what a file “is” and how to match it.

json

{
  "id": "pdf",
  "displayName": "PDF",
  "match": { "extensions": ["pdf"] },
  "defaultPreviewProvider": "builtInPdf"
}

Field	Type	Required	Description
id	string	Yes	Immutable unique id; kebab-case recommended.
displayName	string	Yes	Human-readable label.
match	FileMatch	Yes	Single match definition for the type. Case-insensitive extension match.
defaultPreviewProvider	enum	No	Default preview provider: builtInPdf, builtInImage, builtInText.

FileMatch

Field	Type	Required	Description
extensions	string[]	Yes	One or more extensions (no leading dot), matched case-insensitively.

File Associations (fileAssociations[] items)

Central UX for file type actions, including preview, open, edit, print, and custom verbs.

json

{
  "id": "pdf-routing",
  "displayName": "PDF",
  "enabled": true,
  "priority": 250,
  "fileTypeRef": "pdf",
  "actions": [
    { "verb": "preview", "displayName": "Preview", "provider": "builtInPdf", "default": true },
    { "verb": "open", "displayName": "Open", "appRef": "example-app", "showInContextMenu": true }
  ]
}

Field	Type	Required	Description
id	string	Yes	Stable rule identity; unique within fileAssociations[]; used for tie‑break after priority.
displayName	string	No	Human-readable label for diagnostics.
enabled	boolean	Yes	Whether the rule is active.
priority	number	Yes	Higher numbers first; ties break by rule id (alphabetical) or rule displayName when id is missing.
fileTypeRef	string	Yes	References fileTypes[].id.
actions	FileAssociationAction[]	Yes	Flat array of actions for this file type.

FileAssociationAction

json

{ "verb": "open", "displayName": "Open", "appRef": "ms-word", "default": true, "showInContextMenu": true, "showInOpenWith": true }

Field	Type	Required	Description
verb	string	Yes	Verb name (e.g., `preview`, `open`, `edit`, `print`, `extract`). Must match a verb in the app's capabilities (or be `preview` for built-in preview).
displayName	string	Yes	Display name for menu labels.
appRef	string	No*	Id of an application policy (`apps[].id`) to launch. Required for non-preview actions.
provider	string	No*	Built-in preview provider (`builtInPdf`, `builtInImage`, `builtInText`). Required for `preview` verb only.
default	boolean	No	Marks as default action for double-click.
showInContextMenu	boolean	No	Show in main context menu (default: `true`).
showInOpenWith	boolean	No	Include in Open With submenu (default: `true`).
match	FileMatch	No	Narrows this action within the file type (e.g., split doc vs docx).

*Either appRef or provider is required depending on the verb: use provider for preview verb, appRef for all other verbs.

Security gating

An action references an app via appRef. There must be an enabled app policy with action: "allow" that matches the executable; otherwise the action is ignored. See: File Types & Routing.

Custom verbs

Actions support any verb name defined in app capabilities (not limited to open, edit, print).
Context menu actions are built dynamically from available actions at runtime.

File policies (files[] items)

Rule

json

{
  "id": "deny-import-executables",
  "displayName": "Block importing executables",
  "enabled": true,
  "priority": 1000,
  "operation": "import",
  "fileTypeRef": "executable",
  "action": "deny"
}

Field	Type	Required	Description
id	string	No (recommended)	Stable identifier; unique within files[]; used for tie‑break after priority (alphabetical). If absent, fallback to displayName.
displayName	string	Yes	Human‑readable rule label; must be unique in files[]; used as tie‑break only when id is missing.
enabled	boolean	Yes	Whether the rule is active.
priority	number	Yes	Higher numbers first; ties break by rule id (alphabetical) or rule displayName when id is missing.
operation	enum	Yes	list, import, export, open, delete. Defaults: list Allow, import Allow, export Deny, open Allow, delete Allow.
fileTypeRef	string	Yes	References fileTypes[].id.
action	enum	Yes	"allow" or "deny".

List operation

Controls visibility in the Files tab (file browser) listing; this operation does not execute a verb.
action: "allow" shows matching items; action: "deny" hides matching items from the listing.
Conflicts resolve by rule priority (descending), then rule id alphabetical (fallback to displayName when id is missing), consistent with other file operations.

Configuration Templates (top-level)

Fields

configurationTemplates: Template[]

Template

id (string, required)
description (string, optional)
constraints (object, optional)
- environmentVariables: EnvVarConstraint[]
  - key (string, required)
  - required (boolean, optional)
  - validationPattern (string, optional)
  - patternType ("regex" | "exact", optional)
- mounts (object, optional)
  - rules[] (array)
    - description (string, optional)
    - allowedSourcePatterns: PatternSpec[]
    - allowedDestinationPatterns: PatternSpec[]
    - allowedOptions: ("read-write"|"read-only")[]

PatternSpec

pattern (string)
patternType ("glob" | "regex")

Notes

Use glob for Windows path patterns; regex for value validation.
Environment variables in patterns are resolved at validation time.
Path-oriented matches are case-insensitive by default.
Link apps to templates via apps[].configurationTemplates (string[]).

Global configuration

json

{
  "configuration": {
    "launch": {
      "runtime": {
        "isolation": { "remoteSandbox": true }
      },
      "mounts": [
        { "name": "Desktop", "source": "@DESKTOP@", "destination": "@DESKTOP@", "options": ["read-write"] },
        { "name": "Documents", "source": "@DOCUMENTS@", "destination": "@DOCUMENTS@", "options": ["read-write"] }
      ]
    },
    "network": {
      "capabilities": {
        "outboundAllowed": true,
        "dnsAllowed": true,
        "egressDefaultAction": "allow"
      }
    }
  }
}

Field	Type	Required	Description
`configuration.discovery`	DiscoveryConfig	No	Application discovery providers executed at Launcher startup.
`configuration.sites`	SitesConfig	No	Definition of user-selectable sites. See: Sites.
`configuration.launch.runtime`	Runtime	No	Global runtime settings applied to all launches (replaces raw flags). See: Merging & Precedence.
`configuration.launch.mounts`	StructuredMount[]	No	Structured mounts applied globally.
`configuration.network`	NetworkConfig	No	Global networking: capabilities (egress/inbound/DNS, protocols/ports, DNS servers/suffixes), proxies catalog, and destination-based proxy routing.
`configuration.trust.revocationMode`	"online" \| "offline" \| "none"	No	Revocation checking mode for publisher certificate validation.
`configuration.trust.revocationFallback`	"fail-closed" \| "allow-cache-only"	No	Behavior when revocation services are not reachable.
`configuration.trust.requireTimestamp`	boolean	No	Require a trusted RFC3161 timestamp on code signatures.
`configuration.trust.allowedSigners`	string[]	No	Allowed signer certificate thumbprints (64‑hex SHA‑256 or 40‑hex SHA‑1).
`configuration.trust.allowedIssuers`	string[]	No	Allowed issuing CA subjects or identifiers.
`configuration.policySource.url`	string (uri)	No	HTTPS endpoint hosting the policy.json.
`configuration.policySource.expectedSha256`	string (64 hex)	No	Expected SHA‑256 of the downloaded policy content.
`configuration.policySource.etagTracking`	boolean	No	Track ETag for efficient updates.
`configuration.policySource.fallbackToLkgOnFailure`	boolean	No	Fallback to last‑known‑good on verification failure.

Sites (configuration.sites)

Structure

json

{
  "configuration": {
    "sites": {
      "selectionMode": "auto",
      "defaultSelectionStrategy": "lowestLatency",
      "profiles": [
        {
          "id": "san-jose",
          "displayName": "San Jose",
          "anchor": { "type": "proxy", "proxyRef": "proxy-us" }
        },
        {
          "id": "shanghai",
          "displayName": "Shanghai",
          "anchor": { "type": "proxy", "proxyRef": "proxy-cn" }
        }
      ]
    }
  }
}

Fields

defaultSiteId (string, optional): Site id to use when the selection mode cannot determine the active site. Must match an entry in profiles[].id.
selectionMode (enum, optional): "user" | "device" | "policy-assigned" | "auto". Controls how the active site is selected.
defaultSelectionStrategy (string, optional): Strategy used when selectionMode: "auto". Current value: "lowestLatency".
profiles[] (array, required when Sites are used): List of site profiles available to select.
profiles[].id (string, required): Stable identifier; referenced by siteRefs.
profiles[].displayName (string, required): UI label for the site.
profiles[].anchor (object, optional): Anchor used by auto-selection.
- type (enum, required): "proxy".
- proxyRef (string, optional, deprecated): Single proxy reference. References configuration.network.proxies[].id. Deprecated; use proxyRefs for new configurations.
- proxyRefs (string[], optional): Multiple proxy references. Each entry references configuration.network.proxies[].id.

*Exactly one of proxyRef or proxyRefs must be specified when proxy anchor is present.

Semantics

When selectionMode is "auto", the client evaluates anchors on each profile and selects a site according to defaultSelectionStrategy.
With defaultSelectionStrategy: "lowestLatency", the client performs a TCP connect test to the referenced proxy endpoints and selects the site with the lowest measured latency. Profiles without anchors (or with unreachable anchors) are ignored or treated as high latency.
If no active site can be determined, the Launcher behaves secure-by-default: policy entries are ineligible until a site is selected.

Network (global) and overrides (app/profile)

Networking controls the VM/runtime network posture and destination-based proxy routing.

Locations

Global: configuration.network (NetworkConfig)
Per-app: apps[].modifications.network (NetworkOverrides)
Per-launch profile: apps[].profiles[].network (NetworkOverrides)

Structure (global)

json

{
  "configuration": {
    "network": {
      "capabilities": {
        "outboundAllowed": true,
        "inboundAllowed": false,
        "dnsAllowed": true,
        "protocols": ["tcp","udp"],
        "ports": { "allow": ["80","443","10000-10100"], "deny": ["25"] },
        "dnsServers": ["1.1.1.1","2606:4700:4700::1111"],
        "dnsSearchSuffixes": ["corp.local"],
        "egressDefaultAction": "deny"
      },
      "proxies": [
        {
          "id": "corp-proxy",
          "type": "https",
          "url": "https://proxy.corp.local:8443",
          "tls": { "verify": true }
        }
      ],
      "proxyRouting": [
        {
          "id": "rfc1918-direct",
          "enabled": true,
          "priority": 900,
          "match": { "cidrs": ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"] },
          "action": { "type": "direct" }
        },
        {
          "id": "internet-via-proxy",
          "enabled": true,
          "priority": 800,
          "match": { "hosts": [ { "pattern": "*", "patternType": "glob" } ], "protocol": "tcp" },
          "action": { "type": "proxy", "proxyRef": "corp-proxy", "failover": "deny" }
        }
      ]
    }
  }
}

Overrides (app/profile)

apps[].modifications.network and apps[].profiles[].network support:
- capabilities (same shape as global)
- proxyRouting (rules only; proxies are defined globally and referenced via proxyRef)

Selection and precedence (summary)

Scope precedence: Launch Profile > Policy > Global
Proxy routing: Rules are additive across scopes; for a connection, choose the matching rule with highest priority (desc), then rule id alphabetical. Deny acts immediately.
Capabilities:
- Booleans last-wins by scope (e.g., outboundAllowed).
- Arrays (protocols, dnsServers, dnsSearchSuffixes): last-wins replacement by scope.
- ports.allow/deny: within a scope, deny overrides allow; across scopes, last-wins replacement of the entire ports object.

See details:

Networking
Matchers & Patterns: Network destination matching
Merging & Precedence: Networking precedence and routing selection
Security Best Practices: Network hardening and proxy pinning

Security Posture (configuration.security)

Centralizes cryptographic requirements and host integrity validation for regulated environments.

json

{
  "configuration": {
    "security": {
      "cryptography": {
        "fipsMode": "enforced",
        "keyManagement": {
          "integrationMode": "externalKms",
          "kmsProviderConfigRef": "platform-kms-aws-govcloud",
          "customerManagedKeyRef": "key-id-12345"
        }
      },
      "hostAttestation": {
        "mode": "enforce",
        "providerConfigRef": "platform-attestation-crowdstrike-zta",
        "requirements": {
          "requireManagedDevice": true,
          "minimumComplianceScore": 75,
          "requireActiveThreatProtection": true
        },
        "onFailure": "denyAccess"
      }
    }
  }
}

Cryptography (configuration.security.cryptography)

Field	Type	Required	Description
fipsMode	enum	No	FIPS 140-2/140-3 enforcement: `"disabled"` \| `"enabled"` \| `"enforced"`. Default: `"disabled"`.
keyManagement.integrationMode	enum	No	Key management integration: `"none"` \| `"platform"` \| `"externalKms"`. Default: `"none"`.
keyManagement.kmsProviderConfigRef	string	No	Reference to external KMS provider configuration. Required when `integrationMode` is `"externalKms"`.
keyManagement.customerManagedKeyRef	string	No	Reference to customer-managed encryption key in the KMS.

FIPS Mode Semantics:

disabled: No FIPS requirement; system default cryptographic providers are used.
enabled: Prefer FIPS-validated modules when available; warn if unavailable.
enforced: Require FIPS-validated modules; fail operations if unavailable. Required for CMMC Level 2+ and ITAR.

Host Attestation (configuration.security.hostAttestation)

Field	Type	Required	Description
mode	enum	No	Attestation enforcement: `"disabled"` \| `"audit"` \| `"enforce"`. Default: `"disabled"`.
providerConfigRef	string	No	Reference to attestation provider configuration (e.g., CrowdStrike ZTA, Microsoft Intune).
requirements.requireManagedDevice	boolean	No	Require device to be enterprise-managed. Default: `false`.
requirements.minimumComplianceScore	integer	No	Minimum device compliance score (0–100). Default: `0`.
requirements.requireActiveThreatProtection	boolean	No	Require active endpoint protection. Default: `false`.
onFailure	enum	No	Behavior when attestation fails: `"denyAccess"` \| `"notify"` \| `"auditOnly"`. Default: `"auditOnly"`.

Host Attestation Mode Semantics:

disabled: No host posture checking.
audit: Evaluate posture and log results; do not enforce.
enforce: Evaluate posture; apply onFailure action when requirements are not met.

Host attestation integrates with ABAC via apps[].authorization.requirements.contextConstraints.requireCompliantHost. See: Authorization & Visibility.

Data Classification (configuration.dataClassification)

Integrates classification providers and maps external labels to normalized values for policy authoring and runtime DLP.

json

{
  "configuration": {
    "dataClassification": {
      "onClassificationFailure": "deny",
      "onUnknownClassification": "deny",
      "providers": [
        {
          "id": "corp-purview",
          "type": "purview",
          "capabilities": ["document", "clipboard", "window"],
          "confidenceThreshold": 0.8,
          "cacheTtlSeconds": 30,
          "connection": { /* provider-specific auth/endpoint details */ }
        }
      ],
      "mappings": [
        {
          "providerId": "corp-purview",
          "externalLabelId": "11111111-2222-3333-4444-555555555555",
          "normalized": ["CUI", "CUI//SP-CTI"]
        }
      ],
      "normalizedVocabulary": ["ITAR", "CUI", "CUI//SP-CTI", "CUI//SP-EXPT", "CUI//SP-PRVCY", "EAR", "EAR99"]
    }
  }
}

Field	Type	Required	Description
onClassificationFailure	enum	No	Behavior when providers are unreachable: `"deny"` \| `"allow"` \| `"auditOnly"`. Default: `"deny"`.
onUnknownClassification	enum	No	Behavior when content has no classification: `"deny"` \| `"inherit"` \| `"allow"`. Default: `"inherit"`.
providers	Provider[]	Yes	Classification provider configurations.
providers[].id	string	Yes	Stable identifier; referenced by `mappings[].providerId`.
providers[].type	enum	Yes	Provider type: `"purview"` \| `"digitalGuardian"` \| `"titus"` \| `"custom"`.
providers[].capabilities	string[]	No	Supported classification targets: `"document"`, `"clipboard"`, `"window"`.
providers[].confidenceThreshold	number	No	Minimum confidence (0.0–1.0) for classification to apply. Default: `0.8`.
providers[].cacheTtlSeconds	integer	No	Cache duration for classification results. Default: `30`.
providers[].connection	object	No	Provider-specific authentication and endpoint configuration.
mappings	Mapping[]	Yes	Maps provider labels to normalized vocabulary.
mappings[].providerId	string	Yes	References `providers[].id`.
mappings[].externalLabelId	string	Yes	Provider-specific label identifier (e.g., Purview label GUID).
mappings[].normalized	string[]	Yes	Normalized classification values from `normalizedVocabulary`.
normalizedVocabulary	string[]	No	Defines allowed normalized values. See: Normalized Classification Vocabulary.

Normalized Classification Vocabulary

The normalizedVocabulary defines the set of classification labels that can be used in policy rules. Labels follow standard marking formats:

CUI (Controlled Unclassified Information)

Per NARA CUI Registry and 32 CFR Part 2002:

Label	Description
`CUI`	CUI Basic — default handling requirements
`CUI//SP-CTI`	CUI Specified — Controlled Technical Information (DFARS 252.204-7012)
`CUI//SP-EXPT`	CUI Specified — Export Controlled (EAR/ITAR related but CUI-marked)
`CUI//SP-PRVCY`	CUI Specified — Privacy Act information
`CUI//SP-SBU`	CUI Specified — Sensitive But Unclassified (legacy; prefer specific categories)

Export Control

Label	Description
`ITAR`	International Traffic in Arms Regulations (22 CFR 120-130)
`EAR`	Export Administration Regulations (15 CFR 730-774)
`EAR99`	EAR items not on Commerce Control List

Format Rules

Use double-slash (//) to separate CUI from specified categories per NARA CUI Marking Handbook.
Use hyphen (-) within category abbreviations (e.g., SP-CTI).
Labels are case-sensitive in policy; use uppercase as shown.
Multiple labels can apply to the same content; use arrays in mappings[].normalized.

Extending the Vocabulary Organizations may extend normalizedVocabulary with custom labels for internal classification schemes. Custom labels should:

Use a prefix to avoid collision (e.g., ACME-INTERNAL, ACME-RESTRICTED)
Be documented in organizational policy
Map to provider labels via mappings[]

Data Motion (runtime) — classification matcher

rules[].match.classifications

json

{
  "classifications": {
    "normalized": ["CUI", "CUI//SP-CTI", "ITAR"],
    "provider": { "name": "corp-purview", "labels": ["1111…"], "match": "any" },
    "state": "known"                      // known | unknown (optional)
  }
}

Semantics

Use normalized enumerations for portable policies. Optionally constrain against provider labels.
Values inside a group are OR; different matcher groups (e.g., mimeTypes AND classifications) are AND.
If configuration.dataClassification.enabled: false, this matcher is non-applicable and other matchers/defaultAction decide.

settings.screenCapture.watermark (mirrored in settings.screenShare.watermark)

text (string): Template with variables and filters. Variables: Organization, User.UPN, User.DisplayName, Device.Hostname, Timestamp.UTC, Timestamp.Local, Classification.
style (enum): center | topLeft | bottomRight | diagonalRepeating. If set, overrides legacy position.
persistent (boolean): When true, applies consistently to captures/streams.
variablesAllowlist (string[], optional): Restrict which variables may render.
redactionDefaults (object, optional):

Example

json

{
  "settings": {
    "screenCapture": {
      "enabled": true,
      "mode": "foreground-only",
      "watermark": {
        "text": "CUI//SP-CTI\nControlled by: {Organization}\n{User.UPN|hash(8)} @ {Timestamp.UTC}",
        "opacity": 0.3,
        "persistent": true,
        "style": "diagonalRepeating",
        "variablesAllowlist": ["Organization","User.UPN","Timestamp.UTC"],
        "redactionDefaults": { "pii": "hash", "hashAlgorithm": "sha256", "salt": "env:PII_SALT" }
      }
    }
  }
}

Audit redaction extensions

settings.audit

json

{
  "settings": {
    "audit": {
      "logDecisions": true,
      "sampleRate": 1.0,
      "redaction": {
        "pii": "hash",                     // mask | hash | drop | none
        "variablesAllowlist": ["Classification"],
        "hashAlgorithm": "sha256",
        "salt": "env:PII_SALT"
      }
    }
  }
}

Audit event extension fields

classification: { state, normalized[], provider: { name, labels[] }, confidence }
watermarkTemplateUsed: boolean
userIdentifiers: { upn: string | null } — value redacted per settings.audit.redaction

Audit (runtime) — failure policy and export extensions

The Audit settings under configuration.launch.runtime.audit.settings have been extended for CMMC alignment:

failurePolicy.onFailure: continue | degrade | block (new value: block = fail closed when auditing cannot be guaranteed)
failurePolicy.requireHealthyFor: string[]; supports token "all" to gate all sensitive operations
export.mode: platform | siemForwarding | localOnly (added values)
export.deliveryGuarantee: bestEffort | atLeastOnceConfirmed (new)
export.complianceMetadata.retentionPolicyRef: string (new)

See semantics and examples: Audit Trails — integrity failure policy and export

Failure Semantics

Multiple policy features include failure handling. This section clarifies the scope and interaction of each failure-related field.

Failure Mode Decision Matrix

Failure Type	Field Path	Values	Scope	Default	CMMC Control
Classification provider unreachable	`dataClassification.onClassificationFailure`	`deny` \| `allow` \| `auditOnly`	Data motion classification checks	`deny`	SC-7, AC-4
Content has no/unknown classification	`dataClassification.onUnknownClassification`	`deny` \| `inherit` \| `allow`	Data motion classification checks	`inherit`	AC-4
Host attestation fails	`security.hostAttestation.onFailure`	`denyAccess` \| `notify` \| `auditOnly`	App launch (ABAC context)	`auditOnly`	AC-3, IA-3
Audit pipeline unhealthy	`audit.settings.failurePolicy.onFailure`	`block` \| `degrade` \| `continue`	All audited operations	`degrade`	AU-5
External processor unreachable	`integrations.processors[].limits.offlinePolicy`	`deny` \| `allow` \| `skipProcessor`	Data motion pipeline step	`deny`	SC-7
Pipeline step fails	`dataMotion.rules[].action.onProcessorFailure`	`deny` \| `allow` \| `skipStep`	Data motion pipeline	`deny`	AC-4
Policy signature verification fails	`policySource.fallbackToLkgOnFailure`	`true` \| `false`	Policy load	`true`	CM-3
Code signing revocation check fails	`trust.revocationFallback`	`fail-closed` \| `allow-cache-only`	App launch (identity)	`fail-closed`	IA-5

Failure Handling Recommendations by Environment

CMMC Level 2 / ITAR:

json

{
  "dataClassification": {
    "onClassificationFailure": "deny",
    "onUnknownClassification": "deny"
  },
  "security": {
    "hostAttestation": { "mode": "enforce", "onFailure": "denyAccess" }
  },
  "audit": {
    "settings": {
      "failurePolicy": { "onFailure": "block", "requireHealthyFor": ["all"] }
    }
  },
  "trust": {
    "revocationMode": "online",
    "revocationFallback": "fail-closed"
  }
}

Standard Enterprise:

json

{
  "dataClassification": {
    "onClassificationFailure": "auditOnly",
    "onUnknownClassification": "inherit"
  },
  "security": {
    "hostAttestation": { "mode": "audit", "onFailure": "auditOnly" }
  },
  "audit": {
    "settings": {
      "failurePolicy": { "onFailure": "degrade", "requireHealthyFor": ["screenShare"] }
    }
  },
  "trust": {
    "revocationMode": "online",
    "revocationFallback": "allow-cache-only"
  }
}

Interaction Between Failure Modes

Classification + Data Motion: When onClassificationFailure: "deny", data motion rules that match on classifications will deny if the provider cannot classify. When onUnknownClassification: "deny", unclassified content is denied regardless of other rule matches.
Host Attestation + ABAC: When hostAttestation.mode: "enforce" and a rule specifies requireCompliantHost: true, launch is denied if attestation fails and onFailure: "denyAccess".
Audit + Operations: When failurePolicy.onFailure: "block", operations listed in requireHealthyFor are blocked until the audit pipeline recovers. Use ["all"] to block all sensitive operations.
Processor + Pipeline: Per-processor offlinePolicy applies first. If the processor is reachable but returns an error, onProcessorFailure at the pipeline level applies.

Defaults and behaviors

Allowlist model: Only apps with at least one matching enabled app policy (action: "allow") can launch. Hidden apps are excluded from Applications UI but can be used by routing.
Explicit deny precedence: If any matching enabled policy has action: "deny", the app is not authorized and is not visible or eligible for routing. See: Merging & Precedence.
Merge rules: Scope precedence Launch Profile > Policy > Global. See: Merging & Precedence.
Paths: Prefer glob for Windows paths; escape backslashes in JSON. See: Matchers & Patterns.
Routing selection: Defaults resolve first by explicit default: true, then by routing rule priority, then by routing rule id alphabetical. Open With includes handlers where showInOpenWith: true.

Using the JSON Schema

Add a $schema directive at the top of your policy.json to enable editor validation and IntelliSense.

Recommended (stable URL):

json

{
  "$schema": "https://schemas.turbo.net/launcher-policy.schema.json"
}

Alternatively (when editing inside this repo):

json

{
  "$schema": "./schema.json"
}

Validate with AJV:

bash

# Compile schema (optional)
npx ajv compile -s docs/src/policy/reference/schema.json

# Validate a policy file
npx ajv validate -s docs/src/policy/reference/schema.json -d path/to/policy.json

VS Code

With $schema set, VS Code provides IntelliSense and inline errors according to the schema.

User configurations JSON (per-user)

For the per-user configurations file at %LOCALAPPDATA%\\Turbo\\Launcher\\user-profiles.json, use the dedicated schema:

Header

json

{
  "$schema": "https://schemas.turbo.net/launcher-user-configurations.schema.json",
  "userProfilesVersion": 1,
  "profiles": []
}

Local (when editing inside this repo)

json

{
  "$schema": "./user-configurations-schema.json",
  "userProfilesVersion": 1,
  "profiles": []
}

Validate with AJV

bash

npx ajv validate \
  -s docs/src/policy/reference/user-configurations-schema.json \
  -d "%LOCALAPPDATA%/Turbo/Launcher/user-profiles.json"

Policy Schema Reference ​

Top-level structure ​

Top-level fields ​

Schema versioning and compatibility ​

Schema artifacts and SemVer ​

Client behavior with schema versions ​

Deprecation policy ​

Identity and uniqueness ​

Profile Naming Conventions ​

Application policy (apps[] items) ​

VisibilityConstraints ​

Matcher ​

Authorization (apps[].authorization) ​

Authorization Approval (apps[].authorization.approval) ​

Modifications ​

Launch Profile ​

AppCapability (apps[].capabilities[]) ​

File Types (fileTypes[] items) ​

File Associations (fileAssociations[] items) ​

File policies (files[] items) ​

Configuration Templates (top-level) ​

Global configuration ​

Sites (configuration.sites) ​

Network (global) and overrides (app/profile) ​

Security Posture (configuration.security) ​

Cryptography (configuration.security.cryptography) ​

Host Attestation (configuration.security.hostAttestation) ​

Data Classification (configuration.dataClassification) ​

Normalized Classification Vocabulary ​

Data Motion (runtime) — classification matcher ​

Screen capture/share watermark extensions ​

Audit redaction extensions ​

Audit (runtime) — failure policy and export extensions ​

Failure Semantics ​

Failure Mode Decision Matrix ​

Failure Handling Recommendations by Environment ​

Interaction Between Failure Modes ​

Defaults and behaviors ​

Using the JSON Schema ​

User configurations JSON (per-user) ​

Policy Schema Reference

Top-level structure

Top-level fields

Schema versioning and compatibility

Schema artifacts and SemVer

Client behavior with schema versions

Deprecation policy

Identity and uniqueness

Profile Naming Conventions

Application policy (apps[] items)

VisibilityConstraints

Matcher

Authorization (apps[].authorization)

Authorization Approval (apps[].authorization.approval)

Modifications

Launch Profile

AppCapability (apps[].capabilities[])

File Types (fileTypes[] items)

File Associations (fileAssociations[] items)

File policies (files[] items)

Configuration Templates (top-level)

Global configuration

Sites (configuration.sites)

Network (global) and overrides (app/profile)

Security Posture (configuration.security)

Cryptography (configuration.security.cryptography)

Host Attestation (configuration.security.hostAttestation)

Data Classification (configuration.dataClassification)

Normalized Classification Vocabulary

Data Motion (runtime) — classification matcher

Screen capture/share watermark extensions

Audit redaction extensions

Audit (runtime) — failure policy and export extensions

Failure Semantics

Failure Mode Decision Matrix

Failure Handling Recommendations by Environment

Interaction Between Failure Modes

Defaults and behaviors

Using the JSON Schema

User configurations JSON (per-user)