[tbyfield]

📖 Description

Adds a proposed design for an experimental Windows 365 for Agents (W365A) backend and links it from the development documentation. No implementation changes.

🔗 References

Refs #1615

🔍 Validation

• git diff --check origin/main...HEAD — passed.
• Runtime tests not run (documentation-only).

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• For features or changes requiring a spec: linked the issue with maintainer-applied feature-accepted
• For implementation: linked the required approved and merged design/API spec, or explained why no spec is required
• Feature issue remains open unless this PR completes all agreed implementation, validation, and documentation
• Updated documentation (if applicable)
• Updated Copilot instructions (if build, architecture, or conventions changed)
• If this PR changes Cargo.lock, the dependency-feed-check check passes (see pull request builds)

Implementation, Copilot-instruction and Cargo.lock checks are not applicable to this design-only PR. CLA status has not been verified.

📋 Issue Type

• Bug fix
• Feature
• Task

Microsoft Reviewers: Open in CodeFlow

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

The design treats transport loss or a remote error as normal execution completion with exit code -1, obscuring structured error and outcome-uncertainty details while colliding with a valid Windows exit code.

1 open issue

• Report uncertain transport loss instead of synthetic exit -1 · New

What changed in this PR

Proposes an experimental Windows 365 for Agents backend for MXC’s container lifecycle operations, supporting the remote Cloud PC workflow described in #1615. This PR changes documentation only.

Changes:

• Defines reservation, readiness, command execution, release, and failure-recovery behavior.
• Specifies development-contract settings, security boundaries, staged delivery, and planned CI and manual validation.
• Links the proposal from the development documentation.

File	Description
docs/​development/​README.md	Adds a link to the backend proposal.
docs/​development/​architecture/​designs/​1615-w365a-backend/​README.md	Defines the proposed backend’s scope, lifecycle, contracts, security, and validation plan.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The checkout mismatch assertion discards a valid session ID needed for stop/deprovision cleanup, so the error handling must preserve that identity or attempt release while retaining it if cleanup fails.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Preserve reservation identity when checkout computer ID mismatches

docs/​development/​architecture/​designs/​1615-w365a-backend/​README.md:414

[P2] When checkout returns a valid sessionId but a different computerId, this assertion discards a known reservation identity, leaving the caller without the ID required by stop/deprovision. Keep execution refused, but preserve an identity for cleanup in the structured error, or attempt release and retain that identity if cleanup fails. Align the identity and recovery sections with that choice, and distinguish this recoverable mismatch from a lost or malformed session ID in the fixture.

1 resolved since last review

• Report uncertain transport loss instead of synthetic exit -1

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Service-owner confirmation of pooled-ID equivalence and delegated-identity omission rules remains pending, alongside maintainer agreement on deferred nightly live validation and infrastructure ownership.

No open issues 🎉

_{Review effort: Balanced}

[Branden Bonaby (bbonaby)]

note: tbyfield looks like we're missing a api.md file to show the usage of this feature:
See: https://github.com/microsoft/mxc/blob/main/docs/development/guides/authoring-a-new-feature.md#write-the-spec

This will let us see how users are expected to use the new backend in the SDKs.

[Jeff Whiteside (jsidewhite)]

Why "No buffered SDK result/handle API in this milestone; callers may capture the executor's own output externally."?

[tbyfield]

Yeah, we initially tried to scope this down - after thinking this through it just makes sense to do it now. Will update the design and include in api.md examples

[tbyfield]

Updated in 1c9a98e. Removed that exclusion: the initial milestone now includes captured run-in-container results and pipe-backed process handles through the existing Dev SDK APIs. api.md has Rust, .NET and Node examples plus spawn guidance. The design and validation plan also cover stream ownership, error propagation and local disposal without implying remote termination or reservation release.

[Jeff Whiteside (jsidewhite)]

LGTM (not an SME in any form or fashion on w365 backends)

[Jeff Whiteside (jsidewhite)]

nit: Feels like this is more of a plan than an architecture ("Problem and scope", "non-goals", "### CI suites and hosts", "Open questions")

[Branden Bonaby (bbonaby)]

note: so far in mxc all the backends have been local to the machine. With this cloud backend, if the user loses internet connectivity and the cloud exec completes during that time. What happens when they regain connectivity? Is there a way to recover? I assume the exec call would fail on the client side (MXC with some http timeout error) when they lose connectivity. I guess with our current lifecycle APIs are is no current way to check. The backend would just think the exec call failed right?

[tbyfield]

Right, I don't think with the current MXC API set there'd be a way. I don't think our API would have a way at this point in time. Something potentially for future long running operation support I suppose. Though a caller could potentially determine some side effect e.g. fetch log in a subsequent exec.

[Branden Bonaby (bbonaby)]

thought: So there would be no networking enforcement? E.g ipv4/6 address filtering or in the proxy scenario, L7 filtering? I assume you can't say "turn off networking" because then how else would we be able to interact with it? I guess it's probably fine unless these agents have access to credentials passed in through a script via the exec API that could be exfiltrated out the PC.

[tbyfield]

Correct—MXC won’t enforce IPv4/IPv6 or proxy/L7 filtering for this backend. Checkout reserves an already-prepared Cloud PC; the current W365A pool/checkout APIs don’t expose workload filtering rules that MXC could apply. Administrators can use Intune to deploy security policies and required applications/scripts to the pool’s Cloud PCs, including the guest-side controls needed for their networking requirements. The actual restrictions depend on that deployment, not on MXC or checkout. Right now networking can't be specifically restricted, but in the future we'll allow bringing own VNets and then customer can completely configure.

The W365 relay needs connectivity, but workload traffic need not be unrestricted. You’re right about the exfiltration risk: credentials available to a command could be sent to any destination the environment permits. Callers must select an appropriately configured pool. MXC won’t establish or verify those restrictions and will reject unsupported network/proxy policy rather than silently ignore it.

[Branden Bonaby (bbonaby)]

issue: this shouldn't be done through just the executor. We have v1::dev namespaces in the SDKs that have APIs that accept our JSON based on our JSON schema. These apis are used for experimental and newly developed features.

Then in the future when it's time to move this backend out of experimental, we'd create the strongly type w365_agents containment type in the v1 namespace where folks using the stable v1 APIs can call it in production. Otherwise, they'd just have to use the api's in v1::dev namespace.

[tbyfield]

Agreed—updated the proposal in 1c9a98e to support the complete lifecycle through the existing Rust, .NET and Node V1.Dev JSON APIs with experimental opt-in. The initial scope includes captured execution and pipe-backed spawn, not just executor access. api.md includes examples for provision, start, repeated execution with the same ID, and explicit release. Typed W365 configuration and contract publication remain outside this milestone.

[Branden Bonaby (bbonaby)]

note: We might have to be careful, as I believe the error code MXC returns are HRESULTs. What kind of error codes are these?

[Branden Bonaby (bbonaby)]

question: for Synchronous stdin/stdout/stderr relay how were you thinking this would be done? does the W365A API give some ID that can be queried? I was trying to look in here: https://github.com/microsoft/windows-365-for-agents/blob/main/docs/api-reference.md but I didn't see anything on it.

[Branden Bonaby (bbonaby)]

note: I guess unlike other backends in MXC, if stop and deprovisioning fail, folks will be billed if they're actively running right? Might have to make sure the error details for this case raise the alarm so folks know to do it manually.

[Branden Bonaby (bbonaby)]

question: what do we mean by "reservation"? The cloud PC?

[Branden Bonaby (bbonaby)]

question: might be stupid to ask but I assume you should be able to spin up as many concurrent cloud PCs as your pools allow right? So if you had a pool of say 5, then through MXC you can concurrently spin up 5 and deprovision them separately from each other right?

[tbyfield]

correct, a single user can checkout multiple Cloud PCs at a time, use them independently and then dispose of them.

[Branden Bonaby (bbonaby)]

question: "CP/DP" what do they mean? Also when you say "Feature-enabled native build" are you saying this W365A backend would require a specific build of Windows? Same thing for the x64 requirement, would this also the Windows machine MXC is running on? This column is for that machine. The probe column is for anything we should know about probing whether tech the backend itself uses is available or not.

So, I'd expect something like a query to check if the cloud service or some endpoint is available to this device. E.g perhaps it can't reachout to that w365 service (blocked by IT) or something like that.

[Branden Bonaby (bbonaby)]

issue: since this is a web service in the cloud, wouldn't this be platform agnostic? Trying to figure out why arm64 wouldn't be available as well. If CI was a problem, there are windows-arm64 CI machines now.

[Copilot]

🔵 Needs a closer look

W365 service owners must confirm remote-backend identity and release/timeout guarantees, while maintainers must agree on deferring nightly live validation and assigning ownership of its infrastructure.

No open issues 🎉

_{Review effort: Balanced}

[Branden Bonaby (bbonaby)]

question: I do wonder though. On the cloud PC, what directory does cwd go into by default? Perhaps that should be documented as well.

[tbyfield]

Documented in 007fd69: when cwd is omitted or empty, exec currently uses the DesktopControl.Exec host process's working directory, normally its executable directory under the DesktopControl host launcher—not the user's home directory. The README notes that this default is subject to change and recommends an explicit absolute guest path for predictable behavior.

[Branden Bonaby (bbonaby)]

thought: About the caller, we probably would have to spell how the caller would be supplying the token to the mxc backend. Is there an api they use first to get the token? Win Cred manager? Just thinking about the flow end to end because I'm sure folks will want to try this out asap.

[Branden Bonaby (bbonaby)]

note: Yup, being able to manually run a test is probably be an ideal first step with this backend implementation, and then automate after that.

I'm curious what the w365A team does to do an end to end run. I think that would just consist of using mxc to provision, start, execute commands (1 or many), stop and deprovision one of these cloud PCs.

I do have one question about ownership of both the MXC backend and also the future automated tests. tbyfield is this safe to assume we can rely on your team to maintain this backend? We'd keep you in the loop for any MXC changes but ownership of things like bug fixes, feature requests, would good to your team.

[tbyfield]

Yes, pretty much flow would go through the life cycle with an exec in there (we'll keep those execs simple).

On the ownership, I discussed this the team and we are happy have issues etc routed to us and handle the bugs/feature requests etc. We currently have a weekly sync with Anis. Not sure how long that'll continue, but we will make sure that MXC team has all the necessary contacts (i.e. not just me :))

[Branden Bonaby (bbonaby)]

note: we should remove this addition to this file. I believe when you have a backend doc you can place a link to that in here.

[tbyfield]

Removed the link.

[Copilot]

🔵 Needs a closer look

Maintainer and W365 owner agreement is needed on pooled-session identity and lifecycle guarantees, infrastructure ownership, and the proposed deferral of nightly live validation.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Design approval awaits W365 service-owner confirmation of pooled identity and timeout semantics, plus maintainer and infrastructure-owner agreement on deferring nightly live validation and assigning ownership.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

W365 owners still need to confirm identity and release guarantees, while maintainers must agree on deferring nightly live-service validation and establish infrastructure ownership.

No open issues 🎉

_{Review effort: Balanced}