Skip to content

Commit fafdcc5

Browse files
committed
docs(rfc): clarify Windows proxy and gateway topology
Signed-off-by: Shailendra Singh <[email protected]>
1 parent e99fbb7 commit fafdcc5

1 file changed

Lines changed: 69 additions & 33 deletions

File tree

‎rfc/0013-native-windows-mxc/README.md‎

Lines changed: 69 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ This is worth an RFC rather than a single issue because it is a cross-cutting
5454
architectural decision: it adds a new compute-driver model (in-process,
5555
supervisor-free), a new platform target with its own build/CI lane, a new
5656
policy-translation seam between OpenShell policy and MXC config, and a new
57-
deployment shape (the gateway as a long-lived Windows Service). It also commits
57+
host-side enforcement model for native Windows sandboxes. It also commits
5858
OpenShell to a set of dependencies on the Microsoft MXC team. These decisions
5959
deserve broad review and a durable record.
6060

@@ -75,7 +75,8 @@ the Windows work continues to live outside the public project.
7575
`ComputeDriverService` adapter for MXC. The driver is in-process.
7676
- Full L7/port/binary-scoped policy enforcement inside MXC itself. MXC network
7777
filtering is host/IP/CIDR-level; rich policy stays on the host proxy.
78-
- MSI/WinGet packaging and installer UX
78+
- MSI/WinGet packaging, installer UX, auto-start, and background gateway
79+
management.
7980
- GPU passthrough into MXC sandboxes.
8081
- Changing Linux or macOS build, runtime, or driver behavior. All Windows code is
8182
gated behind `cfg(target_os = "windows")`.
@@ -85,36 +86,68 @@ the Windows work continues to live outside the public project.
8586
### Layered architecture
8687

8788
OpenShell on Windows is a four-layer stack with a single hard trust boundary at
88-
the MXC sandbox. The gateway runs as a long-lived Windows Service; the MXC
89-
compute driver and the host CONNECT proxy live inside that one process. The agent
90-
runs inside an MXC AppContainer with all egress redirected back to the host
91-
proxy.
89+
the MXC sandbox. For the current scope, the gateway runs as a user-launched
90+
native Windows process. The MXC compute driver and per-sandbox host CONNECT proxy
91+
tasks live inside that process. The agent runs inside an MXC AppContainer with
92+
all egress redirected to its assigned host proxy listener.
9293

9394
```mermaid
94-
flowchart TB
95-
cli["Clients<br/>openshell.exe (CLI) · TUI · Python SDK"] -->|"gRPC + mTLS"| gw
95+
flowchart LR
96+
clients["Clients<br/>CLI · TUI · SDK"]
97+
upstreams["Internet / configured upstreams"]
9698
97-
subgraph svc["openshell-gateway.exe — Windows Service (NetworkService)"]
98-
gw["control plane<br/>auth · sandbox state (SQLite) · policy · providers · OCSF audit"]
99-
drv["openshell-driver-mxc (in-process)<br/>wxc-exec invoker · per-sandbox registry · policy→MXC · creds"]
100-
proxy["CONNECT proxy · 127.0.0.1:N<br/>OPA · L7 · inference router · privacy router"]
101-
end
99+
subgraph host["Windows host"]
100+
direction LR
101+
102+
subgraph gateway["openshell-gateway.exe - one native Windows process"]
103+
direction TB
104+
105+
control["Control plane<br/>auth · sandbox state · policy · audit"]
106+
driver["openshell-driver-mxc (in-process)<br/>one backend · N sandbox entries"]
107+
108+
subgraph proxies["Per-sandbox host proxy tasks and listeners (N)"]
109+
direction TB
110+
proxy_a["Proxy A<br/>127.0.0.1:port_A<br/>policy A · agent identity A"]
111+
proxy_n["Proxy N<br/>127.0.0.1:port_N<br/>policy N · agent identity N"]
112+
end
102113
103-
drv -->|"wxc-exec --config-base64 ...<br/>provision · start · exec · stop · deprovision"| wxc["wxc-exec.exe (unmodified)"]
104-
wxc -->|"creates &amp; holds"| box
114+
control --> driver
115+
driver -->|"owns HostProxyHandle A"| proxy_a
116+
driver -->|"owns HostProxyHandle N"| proxy_n
117+
end
105118
106-
subgraph box["MXC AppContainer (processcontainer default) — isolated"]
107-
agent["agent (OpenClaw / Hermes / Codex / python / node)<br/>creds via process.env"]
119+
wxc["wxc-exec.exe invocation(s)"]
120+
121+
subgraph sandboxes["MXC AppContainers (N)"]
122+
direction TB
123+
sandbox_a["Sandbox A<br/>agent workload A only<br/>no OpenShell supervisor"]
124+
sandbox_n["Sandbox N<br/>agent workload N only<br/>no OpenShell supervisor"]
125+
end
126+
127+
driver -->|"launch and configure"| wxc
128+
wxc -->|"creates and runs"| sandbox_a
129+
wxc -->|"creates and runs"| sandbox_n
130+
131+
sandbox_a -.->|"MXC network.proxy<br/>localhost:port_A"| proxy_a
132+
sandbox_n -.->|"MXC network.proxy<br/>localhost:port_N"| proxy_n
108133
end
109134
110-
agent -.->|"egress via MXC network.proxy"| proxy
111-
proxy -.->|"filtered"| net["Internet / inference"]
135+
clients -->|"gRPC + mTLS"| control
136+
proxy_a -->|"policy-filtered egress"| upstreams
137+
proxy_n -->|"policy-filtered egress"| upstreams
112138
```
113139

114-
The defining property is that the OpenShell value layers — egress policy, L7
115-
inspection, inference routing, and the privacy router — live on the host inside
116-
the gateway process, not inside the sandbox. A native Windows agent therefore
117-
gets the Linux feature set without an in-sandbox supervisor.
140+
The gateway-to-sandbox relationship is 1:N for control and lifecycle, but the
141+
proxy-listener-to-sandbox relationship is 1:1. Each sandbox registry entry owns
142+
one `HostProxyHandle`, one sandbox-specific policy, and one unique ephemeral
143+
loopback listener. The listener identifies the sandbox without attributing
144+
connections arriving on a shared proxy port.
145+
146+
The defining property is that OpenShell network enforcement lives on the host
147+
inside the gateway process, not inside the sandbox. The current host-mode path
148+
provides L4 policy and plaintext/forward-proxy L7 handling. HTTPS MITM trust
149+
bootstrap, inference/privacy routing, and gateway event-bus wiring remain
150+
follow-up work.
118151

119152
This still allows the existing supervisor networking code to be reused as a
120153
host-side proxy component. The boundary is that Windows does not run
@@ -138,7 +171,8 @@ library entry points and configuration structs on both platforms.
138171
- `openshell-core/build.rs` selects a vendored `protoc` per platform
139172
(`protoc-bin-vendored` on Windows, `protobuf-src` elsewhere) so proto
140173
compilation succeeds under MSVC.
141-
- Windows path defaults resolve SQLite/data under `%APPDATA%`/`%ProgramData%`.
174+
- Windows path defaults resolve configuration under `%APPDATA%` and state/data
175+
under `%LOCALAPPDATA%`.
142176
- Validation runs through a dedicated `mise` lane (`tasks/windows.toml` →
143177
`tasks/scripts/windows-msvc.ps1`) invoked as `mise run --skip-tools windows:*`,
144178
separate from the default Linux `ci` task. The wrapper discovers Visual
@@ -167,7 +201,7 @@ trait — there is no separate binary, no surrogate, and no tonic adapter.
167201
| registry | In-memory `Arc<Mutex<…>>` mapping OpenShell sandbox id/name ⇄ MXC session id + phase state + exec/PTY handles. Source of truth for Get/List/Watch (MXC has no list-sessions API). |
168202
| `mxc.rs` | Builds MXC config JSON, base64-encodes it, runs `wxc-exec`, parses envelopes; encapsulates exec-vs-non-exec stdout semantics and error-code mapping. |
169203
| `policy.rs` | Translates the `SandboxPolicy` proto → MXC config and rejects unenforceable rules. Delegates to the embedded policy mapper (see Part 3). |
170-
| `proxy.rs` | Hosts the existing OpenShell CONNECT proxy on `127.0.0.1:N`, attributes inbound loopback connections to a sandbox, applies that sandbox's policy. Reuses the Linux proxy/OPA/L7/router code unchanged. |
204+
| `openshell-supervisor-network::host` | Starts one host CONNECT proxy task per sandbox on a unique `127.0.0.1:<ephemeral-port>` listener, applies that sandbox's trimmed network policy and static agent identity, and retains its `HostProxyHandle` in the driver registry. |
171205

172206
#### Workload and software availability
173207

@@ -242,7 +276,7 @@ ephemeral port. It starts the existing OpenShell host CONNECT proxy with that
242276
sandbox's trimmed network-only policy, then writes the allocated port to MXC's
243277
`network.proxy = { localhost: N }` redirect. Loopback inside an AppContainer is
244278
host loopback, so sandbox egress reaches the proxy running in the in-process MXC
245-
driver and gateway service.
279+
driver inside the gateway process.
246280

247281
The host-listener-to-sandbox topology is **1:1**, not many-to-one. Multiple
248282
sandboxes share `127.0.0.1`, but each active sandbox owns a unique ephemeral port
@@ -324,10 +358,11 @@ kernel-level defense-in-depth.
324358
this RFC. Consequence: governed egress on the opt-in `isolation_session`
325359
backend depends on Microsoft extending `network.proxy` to that backend; until
326360
then the design defaults to `processcontainer`, where it works today.
327-
- **D3 — Gateway as a long-lived Windows Service** under
328-
`NT AUTHORITY\NetworkService`. Clients connect over gRPC (loopback or remote
329-
mTLS). SQLite at `%ProgramData%\OpenShell\openshell.db`, Windows Event Log
330-
integration, mTLS bootstrap on first run.
361+
- **D3 — User-launched native Windows gateway for the current scope.** Run
362+
`openshell-gateway.exe` as a regular user process. Clients connect over gRPC
363+
(loopback or remote mTLS), and existing per-user configuration and state paths
364+
remain in effect. Installation, auto-start, background process management,
365+
and Windows Event Log integration are outside this RFC.
331366
- **D4 — Reduce the gRPC footprint to the client-facing API only.** Supervisor
332367
removal deletes the supervisor and sandbox-relay boundaries; in-process MXC
333368
removes the wire protocol on the gateway↔driver boundary. Only client↔gateway
@@ -349,9 +384,10 @@ are never affected and the changes can land additively.
349384
`ValidateSandboxCreate` with `invalid_argument` naming the rule. HTTPS MITM,
350385
inference/privacy routing, and gateway event-bus wiring follow after host-mode
351386
trust bootstrap is available.
352-
- **Gateway as a Windows Service.** Package `openshell-gateway.exe` as a Windows
353-
Service with SQLite under `%ProgramData%`, Windows Event Log integration, and
354-
mTLS bootstrap on first run.
387+
- **Gateway runtime.** Run `openshell-gateway.exe` directly as a regular user
388+
process with the existing per-user configuration, SQLite, TLS, and logging
389+
paths. Installation, auto-start, and background process management are
390+
follow-up work.
355391
- **Hardening.** Validate collision-free per-sandbox ephemeral port allocation
356392
and `processcontainer` concurrency. Persist the sandbox-id ⇄ session-id
357393
mapping so a gateway restart can reconcile or clean up orphaned sessions, and

0 commit comments

Comments
 (0)