How the `--probe` Flag Enables Platform Capability Detection in Microsoft MXC

The --probe flag performs a side-effect-free detection of host capabilities by emitting a JSON document describing supported sandbox features, kernel version, and job object limits.

Platform capability detection in the Microsoft MXC repository allows tools and SDKs to discover what container isolation features are available on a host before attempting to launch workloads. The wxc-exec binary implements this detection through a dedicated --probe flag that executes a read-only inspection path, bypassing all sandbox initialization and container creation logic.

Architecture of the Probe Mechanism

When invoked with --probe, the MXC runtime immediately exits the standard execution flow and enters a detection-only mode. This design ensures zero side effects—no AppContainers are created, no job objects are assigned, and no file system sandboxes are mounted. The binary simply interrogates the Windows kernel and relevant subsystems, then serializes the findings to stdout as formatted JSON.

This fast path exists specifically to support SDK preflight checks and CI/CD validation scripts that must determine feature availability before configuring container workloads.

Implementation in the MXC Runtime

Entry Point in main.rs

The flag is parsed at the earliest possible stage in src/core/wxc/src/main.rs, before any COM initialization or backend selection occurs. The source code explicitly identifies this branch as the "detection-only fast path used by SDK" around lines 463–466. By handling the probe request here, the binary avoids the overhead and potential failures associated with sandbox setup, ensuring reliable execution even on hosts lacking full container support.

Backend Probe Logic in probe.rs

For Windows targets using the AppContainer backend, the actual inspection logic resides in src/backends/appcontainer/common/src/probe.rs. The core function run_probe (defined around lines 23–43) collects critical platform data:

• Kernel version and build numbers
• Job object limits (CPU rate control, memory constraints)
• Supported gates such as tier2_bfs and sandboxedAppContainer
• Base File System (BFS) compilation status

The function populates a ProbeOutput struct, which implements a to_json_pretty method (lines 152–159) to serialize the data into a human-readable JSON format suitable for piping to other tools.

SDK Integration and Consumption

Node.js SDK Implementation

The TypeScript SDK consumes the probe output in sdk/src/platform.ts (lines 144–170). It spawns the binary synchronously using execFileSync(wxcPath, ['--probe']), capturing the JSON response from stdout. This execution strategy blocks until the probe completes, ensuring that configuration decisions are made with complete information before any asynchronous container operations begin.

Parsing Platform Capabilities

The SDK parses the JSON into a PlatformInfo object, checking boolean flags such as bfsCompiledIn and sandboxedAppContainer to determine which isolation features are safe to enable. If the probe indicates that a specific gate is unsupported, the SDK can fall back to alternative execution strategies or emit clear preflight errors before the user attempts to launch an incompatible workload.

Practical Usage Examples

Command Line Inspection

Invoke the probe directly from the terminal to inspect the current host:

wxc-exec --probe

Typical output includes structured metadata about available capabilities:

{
  "kernelVersion": "10.0.19044",
  "bfsCompiledIn": true,
  "supportedGates": [
    "tier2_bfs",
    "sandboxedAppContainer"
  ],
  "jobObjectLimits": {
    "cpuRateControl": true,
    "memoryLimit": true
  }
}

PowerShell Validation Scripts

The repository's test harnesses, such as tests/scripts/Win25H2Safe-Tests.ps1 and tests/scripts/T3-Workloads.ps1, use the probe to validate host compatibility before executing expensive test suites:

$probe = & $WxcPath --probe 2>$null | ConvertFrom-Json -ErrorAction Stop
if (-not $probe.bfsCompiledIn) {
    throw "Preflight: binary does not expose `bfsCompiledIn` in its --probe output."
}

Programmatic SDK Access

Integrate the probe into Node.js applications to conditionally enable features:

import { execFileSync } from 'child_process';
import * as path from 'path';

const wxcPath = path.join(__dirname, '..', 'bin', 'wxc-exec.exe');
const probeJson = execFileSync(wxcPath, ['--probe'], { encoding: 'utf8' });
const platformInfo = JSON.parse(probeJson);

if (platformInfo.bfsCompiledIn && platformInfo.sandboxedAppContainer) {
  console.log('Full sandboxing available');
}

Summary

• --probe triggers a read-only detection mode in wxc-exec that inspects the host without creating sandboxes or containers.
• Source files src/core/wxc/src/main.rs and src/backends/appcontainer/common/src/probe.rs implement the fast path and JSON serialization via run_probe and ProbeOutput::to_json_pretty.
• SDK consumption occurs in sdk/src/platform.ts, where execFileSync captures the JSON output to populate a PlatformInfo object.
• Safe for automation because the probe executes without side effects, making it ideal for CI pipelines, installation scripts, and preflight checks.

Frequently Asked Questions

Is the --probe flag safe to run in production environments?

Yes. The probe performs read-only system queries and does not modify process state, create containers, or alter security policies. It is designed explicitly as a non-destructive diagnostic tool that can run repeatedly without impacting running workloads.

What specific data does the JSON output contain?

The output includes the Windows kernel version, whether the binary was compiled with Base File System (BFS) support, available job object limits (CPU and memory controls), and an array of supported capability gates such as tier2_bfs and sandboxedAppContainer.

How does the MXC SDK handle hosts with limited capabilities?

The SDK parses the probe JSON in sdk/src/platform.ts to construct a PlatformInfo object. If critical capabilities are missing, the SDK can degrade gracefully by disabling advanced sandboxing features or throwing explicit configuration errors before container launch attempts occur.

Can I use --probe without installing the full MXC SDK?

Yes. The wxc-exec binary is self-contained. You can distribute it independently and invoke --probe directly from shell scripts or external tooling to detect platform capabilities without importing the TypeScript SDK or its dependencies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}