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

> Discover how the --probe flag in Microsoft MXC detects platform capabilities. Learn how it emits a JSON doc detailing sandbox features, kernel version, and job limits for efficient system analysis.

- Repository: [Microsoft/mxc](https://github.com/microsoft/mxc)
- Tags: how-to-guide
- Published: 2026-06-07

---

**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`](https://github.com/microsoft/mxc/blob/main/main.rs)

The flag is parsed at the earliest possible stage in [`src/core/wxc/src/main.rs`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/probe.rs)

For Windows targets using the AppContainer backend, the actual inspection logic resides in [`src/backends/appcontainer/common/src/probe.rs`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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:

```bash
wxc-exec --probe

```

Typical output includes structured metadata about available capabilities:

```json
{
  "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:

```powershell
$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:

```typescript
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`](https://github.com/microsoft/mxc/blob/main/src/core/wxc/src/main.rs) and [`src/backends/appcontainer/common/src/probe.rs`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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.