Appearance

Application State Management ​

What You'll Learn

  • How Turbo manages application state in sandboxes during upgrades
  • How state migrations and settings normalization affect your users
  • How to operate and troubleshoot the state management system as an administrator

Overview ​

Turbo uses a state management system to protect user and application data stored in sandboxes. This system:

  • Detects when new application versions are available
  • Plans and executes state migrations inside each sandbox when needed
  • Normalizes important configuration settings into a consistent, queryable format
  • Provides telemetry and journaling so you can monitor and troubleshoot behavior

The goal is to make upgrades safe and predictable for stateful applications such as browsers, IDEs, terminal clients, and remote desktop tools, while giving administrators clear visibility into configuration across their fleet.

Typical scenarios where application state management matters:

  • Upgrading Chrome, VS Code, or similar apps without corrupting user profiles
  • Enforcing or auditing clipboard and file transfer policies for remote access tools
  • Understanding which sandboxes are using specific security-relevant settings

The system operates automatically as part of normal image rollout and application launch. Administrators generally interact with it through monitoring, reports, and the turbo state CLI when deeper investigation is required.

How application state management fits into Turbo Server ​

At a high level, state management connects the release process, sandbox migrations, and fleet reporting:

  1. Release detection

    • Background watchers track upstream releases for supported applications (for example, Chrome and VS Code).
    • New releases are recorded in a version catalog with app name, platform, channel, and published version.

  2. Image build and schema versioning

    • The build pipeline produces new Turbo images for each supported application and version.
    • Each image embeds a state schema version (SSV) that describes the expected structure of its configuration and data files.

  3. Sandbox state migration

    • When a user launches an application with a newer image, the migration engine compares the sandbox’s current SSV with the image’s SSV.
    • If a migration is required, the engine:
      • Creates a snapshot of the sandbox
      • Acquires a lock to prevent concurrent changes
      • Executes a sequence of small, reversible migration steps
      • Updates the sandbox metadata when complete

  4. Settings normalization and reporting

    • After migrations, the settings normalizer reads important configuration values from application files (for example, clipboard settings, proxy configuration, shared storage options).
    • These values are normalized into a common schema and stored for reporting and analytics.

From an administrator’s perspective, this system ensures that stateful applications move through upgrades safely and that their key configuration settings are visible and comparable across your environment.

Key concepts for administrators ​

Understanding a few core concepts will help you interpret logs, reports, and CLI output.

Sandbox ​

A sandbox is the container-scoped directory that holds an application’s persistent state for a particular user and device. It may contain:

  • Application configuration files
  • Caches and derived data
  • Local databases (for example, history or session stores)

Turbo’s state management system operates only within the sandbox and respects path confinement rules to prevent writes outside the sandbox root.

State units ​

Within a sandbox, the system treats different pieces of state as units. Examples:

  • VS Code settings file
  • Chrome preferences file and profile directory
  • RDP profile file
  • Registry hives or INI configuration files for tools like PuTTY or MobaXterm

Each unit has a type (INI, JSON, JSONC, SQLite, directory, registry, RDP, key-value store) and a role (for example, critical configuration vs. derived cache).

This granularity allows migrations to target exactly the data that needs to change for a new version, while leaving derived or cache data safely regenerable.

Profiles and instances ​

Many applications support multiple independent profiles (for example, Chrome’s Default, Profile 1, etc.).

The state management system models this as unit instances. A single logical unit (such as "Chrome preferences") can be present in multiple instances, one per profile.

Administrators may see this reflected in metadata or CLI output as identifiers with instance names, such as:

  • chrome.preferences[Default]
  • chrome.preferences[Profile 1]

Each instance can be inspected and migrated independently when necessary.

State schema version (SSV) ​

The state schema version (SSV) is a number that represents the expected shape and layout of all state units for a given application image. It is not the application’s upstream version, but a separate versioning system focused on data structures.

  • Each application image published in your environment is associated with a particular SSV.
  • A sandbox’s current SSV is stored in its metadata.
  • When an application runs with a newer image, the migration engine plans and executes a sequence of steps to move the sandbox from its current SSV to the image’s SSV.

This separation allows Turbo to handle complex changes in configuration and data layouts across app versions, while keeping migrations reversible and auditable.

Adapters (per-application knowledge) ​

Internally, each supported application has an adapter that:

  • Declares which files, directories, and registry locations contain meaningful state
  • Defines how to detect the current SSV from the sandbox
  • Provides migration rules for moving from older SSVs to newer ones
  • Describes how to read important configuration settings for reporting

Administrators do not need to write or maintain adapters, but it is useful to know that app behavior is defined per application, which explains why different apps may have different sets of reported settings and migration rules.

Normalized settings ​

The system extracts key configuration values from individual applications and normalizes them into a shared schema. Examples of normalized settings include:

  • Clipboard direction for remote desktop clients
  • Proxy configuration flags
  • Shared storage location and enablement
  • Application version and architecture

These settings are stored per app, user, device, and sandbox, and are used to power administrative reports and fleet views.

Lifecycle of a state migration ​

When a user launches an application on a newer image, the following sequence occurs within the sandbox:

  1. Detection

    • The migration engine reads sandbox metadata (meta.json) and other signals to determine the current SSV and the state of known units.

  2. Planning

    • Using the target SSV from the image and the current SSV from the sandbox, the engine composes a migration plan.
    • The plan is a series of small, idempotent steps (for example, updating configuration keys, restructuring a directory, or upgrading a local database schema).

  3. Snapshot and lock

    • A snapshot of the sandbox is created on the same volume where possible (for example, using hard links). If hard links are not available, a copy is made with rate limiting.
    • An exclusive lock file is taken in the sandbox so that only one migration can run at a time.

  4. Execution and journaling

    • Each step in the plan is executed in order.
    • For each step, the engine records start time, completion status, and any error details in a journal file.

  5. Verification

    • The engine runs built-in invariants (for example, schema checks, sandbox size limits) and app-specific verifiers (such as running the application with --version).

  6. Commit and cleanup

    • If all steps succeed, metadata is updated with the new SSV and unit signatures.
    • The snapshot is retained or discarded according to internal policies.

Failure and rollback ​

If any step fails, the engine:

  • Restores the snapshot, returning the sandbox to its last known good state
  • Records the failure in the journal
  • Surfaces errors through logs and metrics

From the user’s perspective, this means that a failed migration does not leave the sandbox in a partially upgraded or corrupt state. From an administrator’s perspective, the journal and metrics provide the information needed to understand and remediate the issue.

Sandbox metadata and journals ​

State management maintains metadata alongside each sandbox to support detection, planning, and troubleshooting.

Metadata location ​

Inside each sandbox, Turbo keeps a dedicated directory (for example, .appstate) containing:

  • A metadata file (meta.json) describing the current state
  • One or more journal files (journal-*.jsonl) with migration history

The exact layout may vary between versions, but administrators can rely on:

  • Metadata providing the current SSV and known state units
  • Journals providing a time-ordered record of migration steps and outcomes

Using metadata for troubleshooting ​

When investigating a problematic sandbox:

  1. Inspect the metadata file to confirm:

    • Which application and version the sandbox belongs to
    • The current SSV and last migration time
    • Which state units are known and how they are structured

  2. Review the journal files to:

    • Identify recent migrations
    • See which steps succeeded or failed
    • Gather error messages for support or deeper analysis

  3. Use the turbo state CLI (described below) to cross-check what the engine sees and to rerun verification where appropriate.

Settings and fleet views ​

Beyond managing on-disk state, the system also extracts key configuration settings into a centralized registry for analysis and reporting.

Setting schema ​

Turbo maintains a catalog of known settings with:

  • A stable setting ID (for example, clipboard.direction or proxy.enabled)
  • A human-readable label
  • A type (boolean, enum, integer, string, path, version)
  • A category used for grouping in the UI and analytics

These definitions ensure that configuration is represented consistently across different applications and versions.

Normalized setting records ​

For each sandbox, the settings normalizer:

  1. Reads configuration values from the relevant files (JSON, INI, registry, RDP, etc.)
  2. Computes the application value, taking into account defaults and any derivations
  3. Applies policy rules when configured to compute the effective value
  4. Stores the results together with provenance (which unit and path the value came from)

This produces a normalized view of application configuration that powers administrative reports, such as:

  • Which users have clipboard redirection enabled
  • How many sandboxes are using a specific file transfer mode
  • Where shared storage is enabled and which paths are in use

You will typically see these values exposed as columns in server reports and dashboards.

Operational workflows for administrators ​

While the state management system runs automatically in most environments, there are several common workflows where administrators may interact with it directly.

Planning and validating upgrades ​

Before rolling out new images broadly, consider:

  • Testing migrations against a set of representative sandboxes (for example, golden test profiles)
  • Monitoring migration success rates and durations during pilot rollouts
  • Using rollout controls to pause or slow down deployment if failure rates exceed acceptable levels

The system’s snapshot and rollback behavior helps protect user data, but proactive validation can catch issues early.

Using the turbo state CLI ​

The turbo state command-line interface provides advanced visibility and control for application state management. Typical administrative uses include:

  • Inspecting current state

    • turbo state detect --app chrome --sandbox <path>
    • Shows the detected SSV and information about state units in a sandbox.

  • Previewing migrations

    • turbo state plan --app vscode --target-ssv <version> --sandbox <path>
    • Displays what changes would be made if the sandbox were migrated to a given SSV.

  • Running migrations manually

    • turbo state run --plan <plan.json> --sandbox <path>
    • Executes a previously generated plan, useful in controlled environments or during troubleshooting.

  • Running verifiers

    • turbo state verify --app <app> --sandbox <path>
    • Runs post-migration checks without performing a migration, to validate integrity.

  • Inspecting settings for a single sandbox

    • turbo state settings --app <app> --sandbox <path> --out json
    • Emits normalized settings for ad-hoc analysis or comparison.

These commands are primarily intended for advanced troubleshooting, pre-production validation, and support workflows rather than everyday operation.

Troubleshooting failed migrations ​

If you suspect a migration issue (for example, users report problems after an upgrade, or monitoring shows increased migration failures):

  1. Check monitoring and logs

    • Look for state-related metrics and log entries (for example, migration status and durations).

  2. Inspect the affected sandbox

    • Review meta.json and journal files under the sandbox’s metadata directory.

  3. Use the CLI to reproduce or isolate the issue

    • Run turbo state detect and turbo state verify on the affected sandbox.
    • Optionally generate and inspect a migration plan with turbo state plan.

  4. Adjust rollout if necessary

    • Use existing rollout and image controls to pause or restrict the problematic version while you investigate.

If you open a support case, providing the relevant journal files and CLI output can significantly speed up diagnosis.

Monitoring, telemetry, and alerts ​

The state management system emits metrics and logs that can be integrated into your existing monitoring stack.

Key information exposed includes:

  • Migration durations and statuses per app and sandbox
  • Distribution of detected SSV values across the fleet
  • Counts and timing for settings normalization operations
  • Error rates broken down by application and unit type

You can use this data to:

  • Build dashboards showing migration success rate and latency during rollouts
  • Detect regressions when new images or adapters are introduced
  • Track how configuration changes propagate through your environment

For details on configuring and viewing server logs and metrics, see:

Security and privacy ​

State management is designed with security and privacy in mind:

  • No secrets in logs: Sensitive values used by applications (such as credentials or tokens) are not written in clear text to journaling or telemetry. When necessary, they are represented as presence/absence indicators or redacted values.
  • Path confinement: All read and write operations are constrained to the sandbox root, preventing migrations from modifying data elsewhere on the system.
  • Permissions hygiene: The system can enforce or restore secure permissions on sensitive paths (for example, SSH keys) after migrations.
  • Supply chain protections: Image and binary signing and verification are handled in the build and rollout pipeline, ensuring that only trusted images participate in state migrations.

Administrators should continue to apply standard hardening practices to servers and storage hosting sandboxes, including access control, encryption, and backup strategies.

Performance expectations ​

The state management system is designed to keep migration overhead low while protecting data.

Typical expectations on medium profiles:

  • Most migrations complete in a few seconds, with outliers depending on the size of local databases and directories.
  • Settings normalization generally adds only a small amount of latency per sandbox and may be cached where appropriate.

If you observe migrations taking significantly longer than expected:

  • Check for unusually large sandboxes (for example, very large caches or history databases)
  • Look for storage bottlenecks (IOPS limits, networked storage latency)
  • Review concurrent load from other operations on the same hosts

Adjusting rollout pacing and ensuring adequate storage performance can help maintain good user experiences during large-scale upgrades.

Frequently Asked Questions ​

Does Turbo modify application data in user sandboxes? ​

Yes. During migrations, Turbo’s state management system may modify configuration files, databases, and directories inside the sandbox to keep them compatible with the current application image. These changes are performed under snapshot and rollback protections so that failed migrations do not leave sandboxes in a partially updated state.

What happens if a migration fails? ​

If any migration step fails, the system restores the snapshot taken before the migration, returning the sandbox to its last known good state. The failure is recorded in the journal and surfaced through logs and metrics so that administrators can investigate.

How does this work in non-persistent VDI environments? ​

In non-persistent environments, sandbox persistence depends on how user profiles are managed. If profiles or sandboxes are discarded between sessions, migrations may occur more frequently but operate on smaller, shorter-lived sandboxes. If profiles are roamed or stored centrally, migrations behave similarly to persistent desktops.

Can I disable state management for a specific application? ​

State management is a core part of how Turbo handles upgrades for stateful applications. In most deployments it should remain enabled to ensure data integrity. If you have a specialized scenario where you need different behavior for a particular app, consult Turbo support for guidance on configuration options and best practices.

Turbo.net © 2025