# How to Configure UI Policies in MXC: A Complete Guide

> Configure MXC UI policies for granular control over window creation, clipboard access, and input injection using the ui block in SandboxPolicy. Learn to manage these settings effectively.

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

---

**MXC UI policies are configured through the `ui` block of a `SandboxPolicy`, allowing granular control over window creation, clipboard access, and input injection via the `allowWindows`, `clipboard`, and `allowInputInjection` fields.**

Configuring UI policies in MXC (microsoft/mxc) allows developers to precisely control how sandboxed processes interact with the Windows GUI subsystem. The SDK provides a cross-platform `ui` configuration block that translates into concrete Job Object restrictions on Windows, ensuring that untrusted code cannot create windows, access the clipboard, or inject input events unless explicitly permitted.

## Understanding MXC UI Policy Configuration

### The Three Core UI Restrictions

When you configure UI policies in MXC, you control three specific security dimensions that govern a sandboxed process's interaction with the Windows GUI:

| UI Field | Description | Default (v0.5.0+) |
|----------|-------------|-------------------|
| `allowWindows` | Enables or disables the creation of visible windows (Win32k system calls) | `false` |
| `clipboard` | Determines clipboard access level: `"none"`, `"read"`, `"write"`, or `"all"` (alias `"readwrite"`) | `"none"` |
| `allowInputInjection` | Allows the process to synthesize input events (e.g., `SendInput`) | `false` |

These fields are part of the **cross-platform** `ui` block within a `SandboxPolicy`. MXC translates this high-level policy into a concrete `UiConfig` object that the Windows *processcontainer* backend applies via Job Object UI restrictions.

## How UI Policies Flow from Policy to Backend

The translation from policy declaration to enforcement happens in [`sdk/src/sandbox.ts`](https://github.com/microsoft/mxc/blob/main/sdk/src/sandbox.ts). When the backend is **processcontainer**, the SDK maps your policy fields as follows (excerpt from lines 278-280):

```ts
ui: {
    // UI is disabled when allowWindows is false (or omitted)
    disable: !(policy.ui?.allowWindows ?? false),
    clipboard: policy.ui?.clipboard ?? "none",
    injection: policy.ui?.allowInputInjection ?? false,
}

```

The resulting `UiConfig` type—defined in [`sdk/src/types.ts`](https://github.com/microsoft/mxc/blob/main/sdk/src/types.ts) at line 21—structures these three fields for the backend:

```ts
// From sdk/src/types.ts#L21-L28
interface UiConfig {
    disable: boolean;      // Mapped from !allowWindows
    clipboard: "none" | "read" | "write" | "all";
    injection: boolean;    // Mapped from allowInputInjection
}

```

The function `createConfigFromPolicy()` validates your policy version, builds a `ContainerConfig`, and injects the UI settings into `config.processContainer.ui` before spawning the sandbox.

## Practical Configuration Examples

### Enabling UI Access for Windows Applications

To allow a sandboxed process to display windows with read-only clipboard access and input injection capabilities:

```ts
import { SandboxPolicy, createConfigFromPolicy } from "mxc/sdk";

const policy: SandboxPolicy = {
  version: "0.5.0-alpha",
  ui: {
    allowWindows: true,          // Enable GUI creation
    clipboard: "read",           // Read-only clipboard access
    allowInputInjection: true,  // Allow synthetic input events
  },
};

const config = createConfigFromPolicy(policy, "process");
console.log(JSON.stringify(config.processContainer?.ui, null, 2));

```

The generated configuration object will contain:

```json
{
  "disable": false,
  "clipboard": "read",
  "injection": true
}

```

### Default-Deny Configuration

When you omit the `ui` block, MXC applies a secure-by-default posture:

```ts
import { SandboxPolicy, createConfigFromPolicy } from "mxc/sdk";

const policy: SandboxPolicy = {
  version: "0.5.0-alpha",
  // No ui block specified
};

const config = createConfigFromPolicy(policy, "process");
console.log(config.processContainer?.ui);

```

Output:

```json
{
  "disable": true,
  "clipboard": "none",
  "injection": false
}

```

Because `allowWindows` is omitted, the SDK defaults to `disable: true`, effectively blocking all UI interactions as implemented in [`sdk/src/sandbox.ts`](https://github.com/microsoft/mxc/blob/main/sdk/src/sandbox.ts).

### High-Level Spawning with spawnSandbox

For streamlined usage, pass UI policies directly to the `spawnSandbox` helper:

```ts
import { spawnSandbox } from "mxc/sdk";

await spawnSandbox("untrustedScript.ps1", {
  version: "0.6.0-alpha",
  ui: {
    allowWindows: true,
    clipboard: "all",          // Full clipboard read/write access
    allowInputInjection: false, // Block input synthesis
  },
});

```

The `spawnSandbox` function internally calls `createConfigFromPolicy()` before launching the sandbox with the generated `ContainerConfig`.

### Debugging Generated UI Configurations

Inspect the exact UI fields sent to the backend for verification:

```ts
import { SandboxPolicy, createConfigFromPolicy } from "mxc/sdk";

const policy: SandboxPolicy = { 
  version: "0.5.0-alpha", 
  ui: { allowWindows: true } 
};

const config = createConfigFromPolicy(policy, "process");

console.log("ProcessContainer UI:", config.processContainer?.ui);

```

This outputs:

```json
{
  "disable": false,
  "clipboard": "none",
  "injection": false
}

```

Unspecified sub-fields automatically fall back to their safe defaults (`"none"` for clipboard, `false` for injection).

## Critical Implementation Details

### Version Requirements

UI restrictions are enforced only on schema versions **≥ 0.5.0-alpha**. Earlier versions ignore the `ui` block entirely. Always specify `version: "0.5.0-alpha"` or later in your `SandboxPolicy`.

### Backend Scope

Currently, only the **processcontainer** backend (Windows) understands and enforces UI policy flags. Other backends—including Linux bubblewrap, macOS seatbelt, and MicroVM—silently ignore the `ui` block. This limitation is inherent to the Windows-specific Job Object UI restrictions used for enforcement.

## Summary

- **Three control dimensions**: MXC UI policies manage `allowWindows` (GUI creation), `clipboard` (access levels), and `allowInputInjection` (synthetic input) through the `ui` policy block.
- **Default-deny posture**: Omitting UI fields results in `disable: true`, `clipboard: "none"`, and `injection: false` for maximum security.
- **Translation layer**: The SDK converts policy declarations to `UiConfig` in [`sdk/src/sandbox.ts`](https://github.com/microsoft/mxc/blob/main/sdk/src/sandbox.ts) (lines 278-280), which the Windows processcontainer backend enforces via Job Objects.
- **Version dependency**: UI policies require schema version 0.5.0-alpha or later; earlier versions ignore the configuration.
- **Windows-only enforcement**: Only the processcontainer backend applies these restrictions—Linux and macOS backends do not implement UI policy controls.

## Frequently Asked Questions

### What is the default UI policy in MXC?

By default, MXC blocks all UI interactions. If you omit the `ui` block from your `SandboxPolicy`, the SDK sets `allowWindows` to `false`, `clipboard` to `"none"`, and `allowInputInjection` to `false`. This default-deny approach ensures that sandboxed processes cannot interact with the Windows GUI unless you explicitly grant permissions.

### Which MXC backend supports UI policy restrictions?

Only the **processcontainer** backend on Windows supports UI policy enforcement. The SDK translates your `ui` block into Windows Job Object restrictions. Other backends—Linux bubblewrap, macOS seatbelt, and MicroVM—currently ignore the `ui` configuration block entirely, according to the source code in [`sdk/src/sandbox.ts`](https://github.com/microsoft/mxc/blob/main/sdk/src/sandbox.ts).

### How do I enable clipboard access in an MXC sandbox?

Set the `clipboard` field to `"read"`, `"write"`, or `"all"` (alias `"readwrite"`) within your policy's `ui` block. For read-only access, use `clipboard: "read"`; for full access, use `clipboard: "all"`. The default value is `"none"`, which blocks all clipboard operations. Remember that this enforcement only works with the Windows processcontainer backend on schema version 0.5.0-alpha or later.

### Can I configure UI policies on Linux or macOS?

No. UI policy configuration in MXC is currently **Windows-specific**. The `ui` block in your `SandboxPolicy` is only processed when using the `process` (processcontainer) backend on Windows. The Linux and macOS backends do not implement UI restrictions, and any `ui` settings you specify will be ignored when targeting those platforms.