Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion .agents/skills/build-openshell-mxc-windows/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -478,7 +478,7 @@ variable by default). Require both a nonempty response and the OpenShell proxy
CA issuer; never replace these assertions with an insecure TLS request. This
fixture permits unavailable CRL information using best-effort Schannel revocation
for the ephemeral private CA; this is not revocation qualification. This
scenario is not part of the default seven offline-capable E2E scenarios.
scenario is not part of the default offline-capable E2E scenarios.

The default `host-service` scenario runs the HTTP fixture on host `127.0.0.1`
and a dynamic port, then checks two nonce-bound replies from direct curl requests
Expand All @@ -489,6 +489,26 @@ firewall modification is required. A failed host health check or workload
request fails the test. This verifies direct localhost connectivity; retain
the existing shared proxy SSRF controls.

The default `gateway-kill` and `gateway-restart` scenarios cover gateway loss.
`gateway-kill` hard-kills the gateway and requires every sandbox process under it
(the supervisor, `wxc-exec`, the boundary and the workload) to end and a
replacement gateway to bind the port. `gateway-restart` sends a real Ctrl-C with
a persisted SQLite database, requires a logged graceful shutdown and every
sandbox process to end, then restarts on the same database and requires the
record to still be listed, its workload not to be running, and the record to be
deletable with its name reusable. Use `-Scenario gateway-kill` or
`-Scenario gateway-restart` for focused checks. Report the behavior accurately:
gateway exit ends workloads and MXC has no restart recovery, unlike the Docker,
Podman and VM drivers, which stop and recover sandboxes on a graceful restart
(MXC reports `gateway_manages_lifecycle: false`). Never describe MXC as
stop-and-recover. A graceful stop ends workloads with or without the
per-generation job; the job is what covers a hard kill, so do not cite
`gateway-restart` as evidence for the job. If recovery is added, update
`gateway-restart`, the driver README and `WINDOWS.md` together. These scenarios
send Ctrl-C and track process trees, so run them on a host you can disturb;
they track only processes under their own gateway and leave other sandboxes
alone.

When reporting `windows:ci`, distinguish these categories:

- Passed tests from the full x64 workspace test log.
Expand Down
5 changes: 3 additions & 2 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 10 additions & 1 deletion WINDOWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,16 @@ under development and is not a production-qualified security boundary:
Treat the gateway host as trusted.
- Foreground main-process attachment and ConPTY resize are unavailable. Create
command workloads with `--detach`.
- Gateway restart recovery for live MXC generations is not supported.
- Gateway exit ends sandbox workloads, and there is no restart recovery. When
the gateway process ends (a graceful stop with Ctrl-C, a crash, or a kill), the
sandbox processes it started end with it, workloads included. After the gateway
restarts on the same database, each sandbox record is still listed but its
workload is not restarted, and its phase is not updated to show that the
workload ended (for example `Provisioning` after a graceful stop, `Ready` after
a hard kill). Delete the record to reuse its name. The Docker, Podman and VM
drivers stop sandboxes on a graceful gateway stop and recover them on restart;
MXC does not provide that recovery. See
[gateway exit and restart](https://github.com/NVIDIA/OpenShell/blob/windows/crates/openshell-driver-mxc/README.md#gateway-exit-and-restart).

See the Windows branch's [MXC driver documentation](https://github.com/NVIDIA/OpenShell/blob/windows/crates/openshell-driver-mxc/README.md)
for the current capabilities and enforcement limits, and its
Expand Down
2 changes: 1 addition & 1 deletion crates/openshell-driver-mxc/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ uuid = { workspace = true }
openshell-mxc-boundary = { path = "../openshell-mxc-boundary" }
openshell-isolation-interface = { path = "../openshell-isolation-interface" }
openshell-sandbox-backend = { path = "../openshell-sandbox-backend" }
windows = { workspace = true, features = ["Win32_System_Kernel", "Win32_System_Performance", "Win32_System_SystemInformation"] }
windows = { workspace = true, features = ["Win32_Storage_FileSystem", "Win32_System_Console", "Win32_System_Diagnostics_ToolHelp", "Win32_System_JobObjects", "Win32_System_Kernel", "Win32_System_Performance", "Win32_System_Pipes", "Win32_System_SystemInformation", "Win32_UI_Shell"] }

[dev-dependencies]
anyhow = { workspace = true }
Expand Down
66 changes: 63 additions & 3 deletions crates/openshell-driver-mxc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,8 @@ not required; driver-owned guest TLS fields are rejected.
| Exec, signals, retained output | Authenticated Sandbox Protocol; ConPTY resize is not yet supported |
| Dynamic forwarding | Standard supervisor `ForwardTcp` path through sandbox loopback connect |
| ETW/OCSF audit | Optional Windows Sandboxing ETW consumer |
| Gateway restart recovery | Not yet supported; live MXC generations remain in-memory |
| Gateway exit | Ends the sandbox processes, workloads included ([details](#gateway-exit-and-restart)) |
| Gateway restart recovery | Not supported; live MXC generations remain in-memory and are not recovered |

Workloads receive the proxy CA in `NODE_EXTRA_CA_CERTS` and `DENO_CERT`, and a
combined bundle in `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, and
Expand Down Expand Up @@ -254,6 +255,44 @@ explicit UI policy (including `{}`) for drivers missing this capability; those
drivers need no UI-specific handling. UI policy itself does not require the
`allow_driver_config` opt-in. Recreate the sandbox to change these settings.

## Gateway exit and restart

The driver runs inside the gateway. Each sandbox generation runs in its own
Windows job object with kill-on-close: the host supervisor and `wxc-exec` are
created inside it (the job is named in the `CreateProcessW` call, so no process
of a generation ever exists outside its job, even if the gateway is killed
mid-spawn), and the boundary and workload processes below them inherit it. When a generation stops, the job is terminated, and when the gateway process
ends for any reason Windows closes the job and ends everything in it. In
practice:

- **Stop and delete** end the whole generation: supervisor, `wxc-exec`, boundary
and workload, not only the two direct children.
- **Graceful gateway stop** (Ctrl-C) ends every sandbox process, workloads
included, and frees the gateway port.
- **Gateway crash or hard kill** ends every sandbox process through the job, and
the listening socket is not inherited by any child, so a new gateway can bind
the port at once.

MXC does not recover sandboxes across a gateway restart. The Docker, Podman and
VM drivers stop their sandboxes on a graceful gateway stop and recover them when
the gateway starts again; MXC reports `gateway_manages_lifecycle: false`, so the
gateway skips that shutdown sweep and startup recovery for it, and live
generations exist only in the driver's memory. After a restart on the same
database:

- each sandbox record is still listed, with the phase it had when the gateway
went away (for example `Provisioning` after a graceful stop, `Ready` after a
hard kill); nothing updates it to show that the workload ended;
- no workload is running, and nothing restarts it;
- `openshell sandbox delete <name>` removes the record, and the name can then be
created again.

Treat a sandbox that was running when the gateway exited as lost, delete its
record, and create it again. The `gateway-kill` and `gateway-restart` E2E
scenarios (see [Validation](#validation)) check this behavior. Behavior for a
driver that runs as its own process, separate from the gateway, is not defined
yet.

## Validation

Windows build tasks embed the CRT in all four executables and Z3 in the
Expand Down Expand Up @@ -351,7 +390,7 @@ explicitly loads the boundary-injected CA bundle and records the peer certificat
success requires a nonempty response and the OpenShell proxy CA issuer. It does
not install a host trust root or disable CA/hostname verification. The fixture
uses best-effort Schannel revocation because the ephemeral private CA has no CRL
distribution point; it does not qualify revocation enforcement. The default seven E2E
distribution point; it does not qualify revocation enforcement. The default E2E
scenarios remain independent of Internet access.

The `forwarding` scenario starts a TCP listener inside MXC, then verifies two
Expand All @@ -375,12 +414,33 @@ host service is checked before launch and stopped after testing. Select it with
`-Scenario host-service`; no Internet access, LAN address, or firewall changes
are required. This verifies direct localhost connectivity.

The default `gateway-kill` scenario checks sandbox cleanup when the gateway dies
without warning. It creates a sandbox with a long-running workload, records the
sandbox process tree under that gateway, hard-kills the gateway, and requires
every recorded process to end and the gateway port to be bindable again (a
replacement gateway must start on it). Only processes under the scenario's own
gateway are tracked, so other sandboxes on the host are left alone. It relies on
each sandbox generation's kill-on-close job object; no workload outlives the
gateway. Select it with `-Scenario gateway-kill`.

The default `gateway-restart` scenario covers a graceful gateway stop with
persisted state. It runs the gateway on a SQLite file, creates a sandbox with a
long-running workload, sends a real Ctrl-C, and requires the gateway to log a
graceful shutdown and exit, every recorded sandbox process to end, and a restart
on the same database to start. After the restart the sandbox record must still be
listed (the observed phase is `Provisioning` and does not change), its workload
must not be running (MXC has no restart recovery), and the record must be
deletable with its name reusable. The scenario pins today's no-recovery behavior,
so it needs updating when recovery is added. A graceful stop ends the workloads
with or without the per-generation job; the job is what covers a hard kill.
Select it with `-Scenario gateway-restart`.

The `ws-agent.yaml` and `openclaw-gateway.yaml` policies preserve the Windows
branch's workload grants. `inference.yaml` is a template: replace its filesystem,
curl executable, inference host, and port placeholders before use. Authorize
curl, which owns the network socket, not its cmd launcher. These policies have
parser/mapper regression coverage; they do not add live WebSocket, OpenClaw,
or provider-backed inference scenarios to the seven-scenario E2E runner.
or provider-backed inference scenarios to the E2E runner.

With `-KeepRunning`, the runner restores the caller's environment but retains
the disposable CLI/runtime directory for the live gateway and prints its path.
Expand Down
Loading
Loading