Semantic Layering

Use Semantic Layering to change values in application configuration files without replacing the complete file or editing the host copy.

What You'll Learn

• How semantic contributions preserve unrelated configuration
• How conditional contributions become traditional SVM layers
• How to configure native Codex and Claude settings without process wrappers

Windows Preview

Semantic Layering is currently a Windows Turbo Client preview. Standalone executables that bypass turbo.exe, older clients, and macOS launches do not apply these projections.

---

Overview

A semantic contribution identifies a virtual target file, pins an adapter, and applies addressed operations such as test, set, remove, or merge-map. At launch, turbo.exe reads the visible lower file, applies the ordered operations, and places the resulting static file in a generated SVM above the application layers. Writes from the application still go to its normal writable overlay.

The preview supports these adapters:

Adapter	Typical Files	Address Model
json@1	Strict JSON	JSON Pointer
jsonc@1	JSON with comments	JSON Pointer
toml@1	TOML configuration	Array of key names
ini@1	INI configuration	Section and key object
xml@1	XML configuration	Typed element, attribute, and text steps
dotenv@1	Environment files	Variable name

Semantic operations preserve values they do not address. Invalid manifests, ambiguous duplicate keys, failed test operations, and unsupported adapters fail the launch before any projected target is published.

Author a Contribution

Place authoring manifests below \__Turbo\SemanticConfig\ in an image-build container. turbo commit validates all manifests, compiles them into non-materialized SemanticFile entries, and removes the authoring files.

This Codex contribution changes two TOML keys while preserving other user configuration:

{
  "$schema": "https://schemas.turbo.net/semantic-layering/manifest-v1.schema.json",
  "version": 1,
  "target": "codex:user-config",
  "path": "@PROFILE@\\.codex\\config.toml",
  "adapter": "toml@1",
  "base": "visible-below-or-empty",
  "requires": [
    "deterministic-render",
    "address:toml-key-path",
    "operation:set"
  ],
  "operations": [
    {
      "op": "set",
      "address": ["approval_policy"],
      "value": "never"
    },
    {
      "op": "set",
      "address": ["sandbox_mode"],
      "value": "danger-full-access"
    }
  ]
}

Use base: "visible-below" when the file must already exist. Use base: "visible-below-or-empty" when a missing file can start as an empty document, or base: "empty" when the contribution intentionally ignores lower content.

Attach Native Layer Conditions

Put conditional manifests in a dedicated directory and add .semantic-layer.xml beside them. The descriptor contains one native VM condition tree:

\__Turbo\SemanticConfig\
  vscode-user-settings.semantic.json
  10-codex\
    .semantic-layer.xml
    codex-user-config.semantic.json
  20-claude\
    .semantic-layer.xml
    claude-user-settings.semantic.json

The Codex descriptor can activate its directory for a direct Codex launch or for an editor session that hosts all configured agents:

<SemanticLayer name="agent-codex-config" order="10">
  <Condition variable="BOOL" operator="OR">
    <Condition variable="LAYERVARIABLE" key="turbo-agent" operator="Equal" value="codex" />
    <Condition variable="LAYERVARIABLE" key="turbo-agent" operator="Equal" value="all" />
  </Condition>
</SemanticLayer>

At commit, Turbo creates a real condition-bearing SVM layer and moves the directory's semantic entries into it. If the source layer is also conditional, Turbo combines the conditions with AND. Greater order values have greater priority among descriptors compiled from the same source layer. A manifest without a same-directory descriptor remains in the source layer.

The descriptor uses the existing native condition format. XVM evaluates platform, architecture, file, registry, Boolean, and launch-variable predicates; the semantic projector does not duplicate that evaluation logic.

Understand Chained Conditional Edits

A single conditional contribution normally produces one conditional static layer. When independent conditions modify the same target, Turbo must also represent their combined result because a static file in a higher layer replaces the lower file.

For edits under conditions A and B, Turbo can materialize variants under A AND NOT B, NOT A AND B, and A AND B. Each variant is an ordinary conditional SVM layer. XVM chooses the active variant using its normal condition evaluation.

The preview limits each target to eight distinct native predicates and limits a launch to 512 generated projections and 256 MiB of generated variant content.

Configure Codex And Claude

The Windows agent-runtime image uses separate conditional layers:

• agent-codex-config sets Codex approval_policy to never and sandbox_mode to danger-full-access in %USERPROFILE%\.codex\config.toml.
• agent-claude-config shallow-merges permissions.defaultMode: "bypassPermissions" into %USERPROFILE%\.claude\settings.json, preserving sibling permission values such as allow and deny.

Select both layers for an editor session:

turbo run base,turbo-agent-runtime-arm64:TAG `
  --layer-variable=turbo-agent=all `
  --startup-file="C:\Program Files\Microsoft VS Code\Code.exe"

Select one layer for a direct CLI launch:

turbo run base,turbo-agent-runtime-arm64:TAG `
  --layer-variable=turbo-agent=codex `
  --startup-file="C:\path\to\codex.exe"

Use --layer-variable=turbo-agent=claude for Claude. These settings let the tools rely on Turbo as the outer confinement boundary without assigning either tool a process wrapper.

Security Boundary

Only use vendor sandbox-disabling settings when the complete process tree is launched inside the intended Turbo isolation and policy boundary. Semantic Layering changes configuration; it does not establish confinement by itself.

Launch-Time Contributions

You can supply additional host manifests with repeatable --semantic-config=<path> options on supported launch commands. Turbo applies explicit manifests after image and sandbox contributions in command-line order.

Launch-time manifests are unconditional. To use native conditions, compile the contribution into a condition-bearing SVM layer and supply the corresponding --layer-variable or other native condition input at launch.

Limitations

• Target-document schemas and per-operation authorization policy are not implemented.
• Secret references and canonical environment identity are not implemented.
• A writable-overlay file at the target path shadows the generated read-only projection.
• A runtime mount over the target path takes precedence, so Turbo rejects that target.
• Older clients can ignore first-class semantic entries; use only with a client version that explicitly supports the preview.

See also

• turbo run
• turbo commit
• Desktop Client Deployment