@openclaw/mxc-sandbox

Official MXC sandbox execution plugin for OpenClaw.

This plugin lets OpenClaw run tool execution through MXC on Windows hosts with ProcessContainer support.

Install

openclaw plugins install @openclaw/mxc-sandbox

Restart the Gateway after installing or updating the plugin.

Configure

After installing the plugin, configure an agent to use the mxc sandbox backend:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "mxc",
        workspaceAccess: "none",
      },
    },
  },
}

This plugin is an early prerelease for testing, so expect configuration and readiness behavior to change as MXC host support matures.

Package

• Plugin id: mxc
• Package: @openclaw/mxc-sandbox
• Minimum OpenClaw install host: 2026.6.11
• Plugin API host requirement: 2026.9.6 or newer. An older host cannot run the current plugin even if the MXC executor is updated.

Plugin config

plugins.entries.mxc.config is validated with a strict schema: unknown keys and out-of-range values fail plugin activation with an actionable error (Invalid mxc plugin config: <reason>) instead of falling back silently.

Any other key is rejected. openclaw.plugin.json publishes the same schema (enums, minimum/maximum bounds) so openclaw config validation and CLI help stay in sync with plugin runtime validation.

Supported

• Windows hosts with the MXC executor installed through @microsoft/mxc-sdk.
• Explicit opt-in after plugin install with sandbox.backend: "mxc".
• MXC process containment, which resolves to Windows ProcessContainer.
• workspaceAccess:
  • none: only the isolated sandbox workdir is mounted, read-only. There is no separate mount for the real agent workspace.
  • ro: the isolated sandbox workdir is mounted read-only, plus a distinct read-only mount of the real agent workspace whenever it differs from the sandbox workdir.
  • rw: the active agent workspace is mounted read-write. If protected OpenClaw skill roots (skills, .agents/skills, or the materialized sandbox skills workspace) exist beneath it, MXC fails the command before launch because ProcessContainer cannot enforce a nested read-only grant beneath a writable parent. The filesystem bridge also rejects writes to those protected paths.
  • Use policy filesystem.additionalReadwritePaths for additional explicit writable host paths shared by every MXC sandbox.
• scope workspace selection:
  • session, agent, and shared choose the OpenClaw workspace directory passed to MXC.
• SDK-only executor discovery from @microsoft/mxc-sdk/bin/<arch> or @microsoft/mxc-sdk/bin; use mxcBinaryPath only for an explicit override.
• OpenClaw passes per-run command, environment, and filesystem config to the plugin's Node launcher through a short-lived local payload file, and deletes that file and its temp directory when the launcher or run finishes.
• @microsoft/mxc-sdk@0.8.0 then carries the full base64 request envelope on the native wxc-exec process argv. A host user with process-inspection rights can observe that command, environment, and policy data while the process is running. Do not put secrets in MXC command arguments or environment values until the SDK provides a non-argv transport (microsoft/mxc#626).

Not supported yet

• Non-Windows hosts.
• Docker-style long-lived containers per scope. MXC ProcessContainer runs are per command; scope controls workspace reuse, not container lifetime.
• Windows filesystem-deny and host-list network policy knobs are not exposed by this plugin until MXC can enforce them on ProcessContainer.

Test setup

Use an already configured OpenClaw installation with MXC installed and enabled on a supported Windows host. These commands create a uniquely named test agent and a new temporary workspace, leaving existing agents and workspaces alone. openclaw config patch --stdin applies sandbox settings only to that agent. Installation-wide MXC settings and policy files remain unchanged; review them before testing because they apply to the test agent too.

Run setup, testing, and cleanup in the same PowerShell session. Finish cleanup before running setup again. Stop if any command fails.

$mxcAgentCreated = $false
$mxcAgent = "mxc-test-" + [guid]::NewGuid().ToString("N")
$mxcWorkspace = Join-Path ([System.IO.Path]::GetTempPath()) $mxcAgent
New-Item -ItemType Directory -Path $mxcWorkspace -ErrorAction Stop | Out-Null

openclaw agents add $mxcAgent `
  --workspace $mxcWorkspace `
  --non-interactive
if ($LASTEXITCODE -ne 0) { throw "Agent creation failed; stop without patching or deleting an existing agent." }
$mxcAgentCreated = $true

$mxcConfigPatch = @"
{
  agents: {
    entries: {
      "$mxcAgent": {
        sandbox: {
          mode: "all",
          backend: "mxc",
          scope: "agent",
          workspaceAccess: "none",
        },
      },
    },
  },
}
"@

$mxcConfigPatch | openclaw config patch --stdin --dry-run
if ($LASTEXITCODE -ne 0) { throw "Sandbox validation failed; use Cleanup to remove the new test agent." }
$mxcConfigPatch | openclaw config patch --stdin
if ($LASTEXITCODE -ne 0) { throw "Sandbox setup failed; use Cleanup to remove the new test agent." }

Sandbox policy files

MXC reads optional host policy files listed in plugins.entries.mxc.config.mxcPolicyPaths. Policy files constrain the filesystem and process defaults used by every MXC sandbox run on the host. Omitting mxcPolicyPaths (or configuring an empty array) uses the built-in sandbox baseline only; MXC never reads an implicit user or machine policy path.

Every mxcPolicyPaths entry must be a non-empty absolute path; the plugin fails to activate with an actionable error the moment a relative, empty, or non-string entry is configured. JSON arrays preserve order, and MXC treats that order as the policy layering order.

Once a sandbox backend is created for an agent, MXC reads every configured policy file and fails closed instead of silently falling back to the baseline:

• A configured policy file that does not exist on the host is an error (Configured sandbox policy file <path> does not exist. Remove it from mxcPolicyPaths or create the file.), not a silent skip.
• A policy file that is malformed JSON or includes an unsupported field fails with an error naming the policy file path and the invalid field.
• Every filesystem.additionalReadonlyPaths and filesystem.additionalReadwritePaths entry must be an absolute Windows path that exists on the host at the time the sandbox activates; a missing path fails with an error naming the path, the policy file, and the field.

Example policy:

{
  "filesystem": {
    "restrictToProjectDir": true,
    "additionalReadonlyPaths": ["C:\\Tools\\OpenClaw\\shared-readonly"],
    "additionalReadwritePaths": ["D:\\OpenClawScratch"]
  },
  "process": {
    "timeoutSeconds": 120
  }
}

Policy schema:

• filesystem.restrictToProjectDir: true, default true. Hardening-only. The default already restricts the sandbox to the project/workspace directory; policy files can assert true but cannot loosen this.
• filesystem.additionalReadonlyPaths: string[], default []. Extra host paths to expose read-only. Each path must be absolute and must already exist on the host.
• filesystem.additionalReadwritePaths: string[], default []. Extra host paths to expose read-write. Each path must be absolute and must already exist on the host, and must not overlap read-only roots or protected skill overlays.
• process.timeoutSeconds: positive number, default 300. Per-command upper bound. Values must be finite and at least 1.

Only the filesystem and process sections are supported. Unknown sections or unknown fields are rejected so policy files fail closed when they drift from the implemented MXC ProcessContainer surface.

When multiple configured policy files exist, OpenClaw layers them deterministically in mxcPolicyPaths array order:

• readonly and read-write path arrays are appended and de-duplicated while preserving first-seen order.
• the effective timeout is the smallest value from the default and configured policy files.
• restrictToProjectDir remains enabled because the field is hardening-only.

The filesystem bridge keeps protected OpenClaw skill overlays read-only. For command execution, MXC fails closed before launch when workspaceAccess: "rw" or a configured read-write path overlaps a protected skill root, because ProcessContainer cannot safely enforce the nested read-only grant.

Run the TUI as that agent:

openclaw tui --session "agent:${mxcAgent}:main"

For local embedded testing without a Gateway:

openclaw tui --local --session "agent:${mxcAgent}:main"

Cleanup

In the same PowerShell session, remove only the agent created by setup:

if (-not $mxcAgentCreated) {
  throw "No successfully created test agent in this session; do not delete an existing agent."
}
openclaw agents delete $mxcAgent --force
if ($LASTEXITCODE -ne 0) { throw "Agent cleanup failed; inspect the error before retrying." }
$mxcAgentCreated = $false

The delete command removes the test agent's configuration and attempts to move its workspace and state to Trash. Check its output for any manual-cleanup warning. Do not remove the MXC plugin entry or shared policy files: other agents may still use them.

Host readiness

Before registering the sandbox backend, the plugin runs the MXC executor's own host probe (wxc-exec --probe) and requires it to select an isolation tier (base-container, appcontainer-bfs, or appcontainer-dacl). It probes the same executor it launches, including an mxcBinaryPath override. MXC's tier degradation warnings are logged but do not block activation. To inspect a host, run the executor directly:

& node_modules\@microsoft\mxc-sdk\bin\x64\wxc-exec.exe --probe

Use bin\arm64 on Arm64 hosts.

An existing mxcBinaryPath override must point to an MXC 0.8.0-compatible executor that supports --probe. An older executor stops plugin activation; the plugin cannot safely infer readiness from a Windows service name or probe a different binary. If the override fails, run that exact executable with --probe to see its error. Update the override to a compatible executor, or remove it to use the @microsoft/mxc-sdk@0.8.0 executor installed with the plugin:

openclaw config unset plugins.entries.mxc.config.mxcBinaryPath

Restart the Gateway after changing the override. If the SDK executor also fails --probe, address the reported host-readiness error before retrying.

Host preparation is advisory. If directory listing inside the sandbox fails with Access is denied, run this once from an elevated prompt:

wxc-host-prep prepare-system-drive

wxc-host-prep ships with @microsoft/mxc-sdk under node_modules/@microsoft/mxc-sdk/bin/<arch>/.

Testing

pnpm test:extension mxc

pnpm test extensions/mxc is also supported for the bundled extension test lane.

For policy-only edits, the focused coverage is in:

pnpm test:extension mxc extensions/mxc/test/config.test.ts extensions/mxc/test/sandbox-policy-loader.test.ts extensions/mxc/test/mxc-backend.test.ts