How to Configure UI Policies in MXC: A Complete Guide

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. When the backend is processcontainer, the SDK maps your policy fields as follows (excerpt from lines 278-280):

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 at line 21—structures these three fields for the backend:

// 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:

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:

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

Default-Deny Configuration

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

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:

{
  "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.

High-Level Spawning with spawnSandbox

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

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:

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:

{
  "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 (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.

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.

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