Skip to content

feat(policy): add portable UI controls for MXC sandboxes #3022

Open

Description

@shailendra-nv

User Story

As an OpenShell operator, I want a platform-neutral UI policy so I can
explicitly control graphical UI access, clipboard direction, and synthetic
input without embedding backend-specific or operating-system-specific concepts
in an OpenShell policy.

Problem Statement

OpenShell cannot currently express portable UI controls. The MXC mapper has an
intermediate restrictive top-level ui representation, but the active typed
driver path does not carry that representation into wxc-exec, so there is no
end-to-end UI policy enforcement today.

MXC process containers can enforce the proposed controls. MXC isolation
sessions and the current Docker, Podman, Kubernetes, and VM drivers cannot
enforce the complete contract. Without an explicit driver capability boundary,
OpenShell could accept a UI policy on a backend that cannot truthfully report it
as enforced.

Impact / Why This Matters

Windows process-container users cannot opt into a graphical application,
selectively allow clipboard reads or writes, or permit input injection through
an OpenShell policy. Bypassing or modifying the mapper loses the portable
OpenShell policy boundary and is unsuitable for managed sandboxes.

More broadly, silently accepting UI policy on an unsupported backend would
weaken policy integrity. Operators need sandbox creation to fail before
provisioning when the selected backend cannot enforce an explicitly requested
UI contract.

Proposed Design

Add an optional, typed, static ui section to the version 1 OpenShell policy:

ui:
  allow_graphical_ui: false
  clipboard: none
  allow_input_injection: false

The field names describe portable capabilities rather than Windows APIs.
clipboard accepts none, read, write, or all. Within an explicitly
present UI section on a supporting backend, omitted fields default to deny.
Absence of the entire section means no UI-policy request and preserves existing
runtime behavior.

Compute drivers advertise whether their configured backend can enforce the
complete UI policy contract. Before any lifecycle side effect, OpenShell rejects
an explicitly present UI section, including ui: {} or a deny-only section, if
the selected driver does not advertise support.

Driver or backend Explicit ui section Absent ui section
MXC process_container Enforce all three capabilities exactly Preserve the existing restrictive MXC output
MXC isolation_session Reject before invoking MXC Preserve existing backend behavior; claim no UI restriction
Docker, Podman, Kubernetes, VM Reject before provisioning Preserve existing behavior
Future drivers Accept only after advertising complete UI-policy enforcement Preserve existing behavior

On MXC process containers, map the three capabilities to MXC's top-level
ui.disable, ui.clipboard, and ui.injection. Do not expose MXC's
Windows-specific desktop, system-settings, IME, or isolation controls.

The section is immutable after sandbox creation and participates in static
policy comparison and hashing. Driver capability checks apply at sandbox
creation; live policy mutation cannot add, remove, or change UI policy.

Current MXC Contract

Microsoft MXC models top-level ui as a one-shot configuration field. Its
state-aware isolation-session provision contract does not include ui, and MXC
maintains explicit rejection fixtures for isolation-session configurations that
supply the field:

OpenShell therefore rejects explicit UI policy for MXC isolation_session
itself, producing stable fail-closed behavior across MXC versions without
relying on whether a particular MXC build rejects or ignores the unsupported
field.

Alternatives Considered

  • Scope UI controls as MXC-specific configuration. Rejected because the policy
    fields describe portable security capabilities and future drivers may
    implement the same complete contract.
  • Expose MXC's JSON shape directly. Rejected because it would leak
    backend-specific and Windows-specific concepts into an OS-agnostic policy.
  • Add generic host-device or desktop-system-control fields now. Rejected
    because the semantics are not portable across operating systems.
  • Silently accept UI policy and apply a more restrictive backend default.
    Rejected because OpenShell could not truthfully report the requested policy
    as enforced.
  • Treat an absent UI section as a universal deny guarantee. Rejected because
    backends without UI enforcement cannot make that claim; absence must preserve
    existing behavior.
  • Silently discard explicit UI policy on MXC isolation_session. Rejected
    because requested security policy must not be reported as enforced when it is
    not representable.

Acceptance Criteria

  • The version 1 protobuf and YAML policy surface includes the typed,
    optional, platform-neutral UI section and preserves absent versus
    explicitly empty presence.
  • Within an explicit UI section, omitted fields default to deny.
  • Compute drivers advertise complete UI-policy enforcement support.
  • Sandbox creation fails before provisioning when an explicit UI section is
    supplied to a driver or configured backend that does not advertise UI
    policy support.
  • UI policy is static, hash-significant, deterministic, and round-trips
    through protobuf/YAML conversions.
  • MXC process containers map every UI capability exactly and preserve the
    legacy restrictive output when the OpenShell section is absent.
  • MXC isolation sessions preserve existing behavior when UI is absent and
    reject any explicit UI section before invoking MXC.
  • Docker, Podman, Kubernetes, and VM preserve existing behavior when UI is
    absent and reject any explicit UI section before provisioning.
  • Mapper, schema, conversion, hashing, capability, create-validation, and
    platform-boundary tests cover the new behavior.
  • Real-MXC contract tests cover process-container mapping and
    isolation-session rejection against supported baseline and current MXC
    revisions.
  • Relevant architecture, user, crate, and agent-skill documentation is
    updated with the capability matrix and absence semantics.
  • Cross-platform CI and supported Windows architecture validation pass.

Activity

  1. elezar commented on Aug 31, 2026

    @elezar
    Member

    📋 triage-agent

    Triage Assessment

    Classification: needs-information

    Thanks for the detailed proposal. The capability is reasonable, but we cannot validate this as a portable top-level policy feature yet.

    Today, allow_graphical_ui, clipboard access, and input injection appear enforceable only by MXC. Docker, Podman, Kubernetes, and VM backends do not have equivalent enforcement paths. Please clarify which contract you propose:

    1. Scope this as an MXC-specific configuration feature; or
    2. Define portable semantics and require sandbox creation to fail whenever an explicit UI policy cannot be enforced by the selected backend.

    Silently accepting the policy while default-denying it elsewhere would conflict with the proposal's policy-integrity rationale.

    We also need a minimal reproduction of the claimed current failure: the exact Windows/MXC (wxc-exec) version, backend mode, generated invocation/configuration, and resulting error. The current active MXC invocation path does not appear to forward a top-level UI object, so the asserted isolation-session rejection is not yet established.

    Once those points are resolved, please update the proposed design and acceptance criteria, including the expected behavior on each supported compute driver.

  2. added
    state:needs-infoAssessment needs specific evidence or reproduction details
    and removed
    state:triage-neededOpened without agent diagnostics and needs triage
    on Aug 31, 2026
  3. shailendra-nv commented on Aug 31, 2026

    @shailendra-nv
    CollaboratorAuthor

    📋 triage-agent

    Triage Assessment

    Classification: needs-information
    Thanks for the detailed proposal. The capability is reasonable, but we cannot validate this as a portable top-level policy feature yet.
    Today, allow_graphical_ui, clipboard access, and input injection appear enforceable only by MXC. Docker, Podman, Kubernetes, and VM backends do not have equivalent enforcement paths. Please clarify which contract you propose:

    1. Scope this as an MXC-specific configuration feature; or
    2. Define portable semantics and require sandbox creation to fail whenever an explicit UI policy cannot be enforced by the selected backend.

    Silently accepting the policy while default-denying it elsewhere would conflict with the proposal's policy-integrity rationale.
    We also need a minimal reproduction of the claimed current failure: the exact Windows/MXC (wxc-exec) version, backend mode, generated invocation/configuration, and resulting error. The current active MXC invocation path does not appear to forward a top-level UI object, so the asserted isolation-session rejection is not yet established.
    Once those points are resolved, please update the proposed design and acceptance criteria, including the expected behavior on each supported compute driver.

    This is valid feedback. I rechecked both the pre-change OpenShell path and the current MXC contract. First, a correction to the issue: the pre-change mapper synthesized a restrictive top-level ui object in its intermediate JSON, but the active typed OpenShell driver path did not forward that object to wxc-exec. Therefore, there was no existing end-to-end OpenShell isolation-session failure. I will remove that claim from the problem statement.
    We propose the second contract: portable semantics with fail-closed backend validation.
    Any explicitly present ui section—including ui: {} or a deny-only section—must cause sandbox creation to fail before lifecycle side effects when the selected driver/backend cannot enforce the complete UI contract. Absence of the section preserves existing behavior for existing policies.

    Driver/backend Explicit ui Absent ui
    MXC process_container Enforce all three capabilities exactly Preserve the existing restrictive MXC output
    MXC isolation_session Reject before invoking MXC Preserve existing backend behavior; no UI restriction is claimed
    Docker, Podman, Kubernetes, VM Reject before provisioning Preserve existing behavior
    Future drivers Accept only when the driver advertises complete UI-policy enforcement Preserve existing behavior

    “Missing fields default to deny” will be scoped to an explicit UI section on a supporting backend. It will no longer be presented as a universal guarantee for backends that do not implement UI enforcement.

  4. added
    state:acceptedA maintainer decided OpenShell should pursue this issue
    and removed
    state:needs-infoAssessment needs specific evidence or reproduction details
    on Sep 1, 2026
  5. moved this from Planning to In progress in OpenShell Roadmapon Oct 12, 2026
  6. github-actions commented on Oct 17, 2026

    @github-actions

    This issue has had no activity for 14 days and is now marked stale. It may be closed in 14 days if there is no further activity. Comment or remove the state:stale label to keep it open.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

state:acceptedA maintainer decided OpenShell should pursue this issuestate:staleInactive item at risk of automatic closure.

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions