feat(k8s): add dockur windows pool exmaple (opensandbox-group#878)

* feat(k8s): add dockur windows pool exmaple

* feat(server): fix windows reboot

Author: Generalwin

examples/README.md

@@ -21,6 +21,7 @@ Examples for common OpenSandbox use cases. Each subdirectory contains runnable c
 - 🦞 [**nullclaw**](nullclaw): Launch a Nullclaw Gateway inside a sandbox
 - 🦞 [**openclaw**](openclaw): Run an OpenClaw Gateway inside a sandbox
 - 🖥️ [**desktop**](desktop): Launch VNC desktop (Xvfb + x11vnc) for VNC client connections
+- 🪟 [**windows**](windows): Run a Windows guest VM via KVM/QEMU with RDP and web console access
 - <img src="https://playwright.dev/img/playwright-logo.svg" alt="Playwright" width="16" height="16" style="display:inline-block;width:16px;height:16px;vertical-align:middle;margin-right:4px;" /> [**playwright**](playwright): Launch headless browser (Playwright + Chromium) to scrape web content
 - <img src="https://code.visualstudio.com/assets/favicon.ico" alt="VS Code" width="16" height="16" style="display:inline-block;width:16px;height:16px;vertical-align:middle;margin-right:4px;" /> [**vscode**](vscode): Launch code-server (VS Code Web) to provide browser access
 - <img src="https://www.google.com/chrome/static/images/chrome-logo.svg" alt="Google Chrome" width="16" height="16" style="display:inline-block;width:16px;height:16px;vertical-align:middle;margin-right:4px;" /> [**chrome**](chrome): Launch headless Chromium with DevTools port exposed for remote debugging

examples/windows/README.md

@@ -0,0 +1,182 @@
+# Windows Sandbox Example
+
+Run a Windows guest in an OpenSandbox sandbox via KVM/QEMU using the [`dockur/windows`](https://github.com/dockur/windows) image.
+
+## How it works
+
+OpenSandbox creates a Linux container running KVM/QEMU, which boots a Windows guest OS inside it. The Windows profile (`platform.os=windows`) automatically configures the required devices, capabilities, OEM scripts, and port mappings — you only need to specify `platform` and `resource` in the SDK call.
+
+## Prerequisites
+
+- OpenSandbox server running (e.g. `http://localhost:8080`)
+- Host with `/dev/kvm` and `/dev/net/tun` present
+- Server `storage.allowed_host_paths` configured for any host bind mounts
+
+## Start OpenSandbox server [local]
+
+```shell
+uv pip install opensandbox-server
+opensandbox-server init-config ~/.sandbox.toml --example docker
+opensandbox-server
+```
+
+## Run the example
+
+```shell
+uv pip install opensandbox
+python main.py
+```
+
+The script will:
+
+1. Create a Windows sandbox with `dockurr/windows:latest` and Windows 11
+2. Wait until the sandbox is healthy (first boot can take several minutes)
+3. Print the execd, RDP (3389), and web console (8006) endpoints
+4. Execute a test command and print the output
+
+## Environment Variables
+
+- `SANDBOX_DOMAIN`: Sandbox service address (default: `localhost:8080`)
+- `SANDBOX_API_KEY`: API key if your server requires authentication (optional for local)
+
+## Customization
+
+### Resource limits
+
+The Windows profile enforces minimum resources: **cpu >= 2, memory >= 4G, disk >= 64G**. The example uses 4 CPU, 8G RAM, and 64G disk. You can adjust these in the `main.py` `resource` dict.
+
+### Persistent storage
+
+Bind a host directory to `/storage` for a persistent system disk (add to the `SandboxSync.create` call):
+
+```python
+from opensandbox.models.sandboxes import Host, Volume
+
+volumes = [
+    Volume(
+        name="win-storage",
+        host=Host(path="/data/opensandbox/windows-storage"),
+        mount_path="/storage",
+        read_only=False,
+    ),
+]
+```
+
+### Local ISO
+
+Bind a Windows install ISO to `/boot.iso` to avoid repeated downloads:
+
+```python
+volumes = [
+    Volume(
+        name="win-iso",
+        host=Host(path="/data/iso/Win11_23H2.iso"),
+        mount_path="/boot.iso",
+        read_only=True,
+    ),
+]
+```
+
+### Windows guest configuration
+
+Pass [dockur/windows environment variables](https://github.com/dockur/windows) through the `env` parameter:
+
+```python
+env = {
+    "VERSION": "11l",
+    "USERNAME": "Docker",
+    "PASSWORD": "your-secure-password",
+    "LANGUAGE": "Chinese",
+    "REGION": "zh-CN",
+    "KEYBOARD": "zh-CN",
+}
+```
+
+Do not manually set `CPU_CORES`, `RAM_SIZE`, or `DISK_SIZE` — they are derived from `resourceLimits` automatically.
+
+## Exposed ports
+
+| Port | Service |
+|------|---------|
+| 44772 | execd (sandbox execution API) |
+| 8080 | HTTP service |
+| 3389 | RDP (native Remote Desktop) |
+| 8006 | Web console (noVNC) |
+
+## Troubleshooting
+
+- **`Unsupported platform.os 'windows'`**: Server build has no Windows profile; upgrade OpenSandbox server.
+- **`INVALID_PARAMETER` for resourceLimits**: Ensure cpu >= 2, memory >= 4G, disk >= 64G.
+- **Stays Pending a long time**: First Windows install is slow; check host resources and `/storage` space, increase `ready_timeout`.
+- **Status Running but endpoint unreachable**: Verify endpoint resolution returns a valid address; check `USER_PORTS` if you need additional ports forwarded.
+
+### ENI CNI network issue (Alibaba Cloud ACK)
+
+On clusters using ENI-based CNIs (e.g. Alibaba Cloud ACK Terway in ENI mode), dockur/windows fails at startup with:
+
+```
+❯ ERROR: This container does not support host mode networking!
+```
+
+or:
+
+```
+❯ ERROR: Status 1 while: ethtool -i "$VM_NET_DEV"
+```
+
+**Root cause**: The image's `network.sh` uses `ethtool -i` to check the network interface. ENI interfaces have real PCI bus-info, which triggers a false "host mode" detection. Standard veth-based CNIs (Calico, Flannel, Cilium) do NOT have this problem.
+
+**Solution**: Use the provided `main_fix_net.py` example, which patches the script at runtime and sets `NETWORK=slirp` for QEMU user-mode NAT:
+
+```shell
+python main_fix_net.py
+```
+
+See [`main_fix_net.py`](./main_fix_net.py) for the full implementation.
+
+**How it works**:
+
+1. `sed` replaces three lines in `/run/network.sh` with empty variable assignments (`result=""`, `nic=""`, `bus=""`), preventing the ethtool check from aborting the script.
+2. `NETWORK=slirp` tells the script to use QEMU's SLIRP networking (user-mode NAT), which doesn't require a real NIC.
+3. `exec /usr/bin/tini -s /run/entry.sh` launches the original image entrypoint after patching.
+
+This approach keeps the Pod's independent IP and requires no image rebuild or `hostNetwork`.
+
+## Windows Sandbox from pool
+
+Use a pre-warmed K8s pool for faster Windows sandbox startup.
+
+### 1. Create the pool
+
+Apply the pool manifest (the image, resources, device mounts, and OEM scripts are pre-configured):
+
+```shell
+kubectl apply -f pool-win-example.yaml
+```
+
+### 2. Start the OpenSandbox server [k8s]
+
+```shell
+uv pip install opensandbox-server
+opensandbox-server init-config ~/.sandbox.toml --example k8s
+opensandbox-server
+```
+
+### 3. Run the pool example
+
+```shell
+uv pip install opensandbox
+python main_use_pool.py
+```
+
+The script acquires a sandbox from `pool-win-example`, prints endpoints, and runs a command.
+
+### Environment variables (pool)
+
+- `SANDBOX_DOMAIN`: Sandbox service address (default: `localhost:8080`)
+- `SANDBOX_API_KEY`: API key if your server requires authentication
+
+## References
+
+- [Windows sandbox guide](../../docs/windows-sandbox.md)
+- [dockur/windows](https://github.com/dockur/windows)

examples/windows/main.py

@@ -0,0 +1,61 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Minimal Windows sandbox example using dockur/windows."""
+
+import os
+from datetime import timedelta
+
+from opensandbox import SandboxSync
+from opensandbox.config import ConnectionConfigSync
+from opensandbox.models.sandboxes import PlatformSpec
+
+
+def main() -> None:
+    cfg = ConnectionConfigSync(
+        domain=os.getenv("SANDBOX_DOMAIN", "localhost:8080"),
+        api_key=os.getenv("SANDBOX_API_KEY") or None,
+        request_timeout=timedelta(minutes=3),
+        use_server_proxy=True,
+    )
+
+    sbx = SandboxSync.create(
+        image="dockurr/windows:latest",
+        timeout=timedelta(hours=12),
+        ready_timeout=timedelta(minutes=30),
+        resource={
+            "cpu": "4",
+            "memory": "8G",
+            "disk": "64G",
+        },
+        env={"VERSION": "11"},
+        platform=PlatformSpec(os="windows", arch="amd64"),
+        connection_config=cfg,
+    )
+
+    try:
+        print(f"Created: {sbx.id}")
+        print(f"execd:    {sbx.get_endpoint(44772).endpoint}")
+        print(f"RDP:      {sbx.get_endpoint(3389).endpoint}")
+        print(f"Web:      {sbx.get_endpoint(8006).endpoint}")
+
+        exec = sbx.commands.run("cmd /c echo Hello from Windows sandbox")
+        print(f"Command output: {exec.logs.stdout[0].text}")
+    finally:
+        sbx.kill()
+        sbx.close()
+
+
+if __name__ == "__main__":
+    main()

examples/windows/main_fix_net.py

@@ -0,0 +1,92 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Windows sandbox example with ENI CNI network fix.
+
+Use this example on clusters with ENI-based CNIs (e.g. Alibaba Cloud ACK
+Terway in ENI mode) where dockur/windows fails with:
+
+    ERROR: This container does not support host mode networking!
+
+or:
+
+    ERROR: Status 1 while: ethtool -i "$VM_NET_DEV"
+
+The fix patches /run/network.sh at container startup to bypass the
+ethtool/bus-info check, then uses NETWORK=slirp for QEMU user-mode NAT.
+Standard veth-based CNIs (Calico, Flannel, Cilium) do NOT need this fix.
+"""
+
+import os
+from datetime import timedelta
+
+from opensandbox import SandboxSync
+from opensandbox.config import ConnectionConfigSync
+from opensandbox.models.sandboxes import PlatformSpec
+
+# sed command to bypass the ethtool/grep checks in network.sh.
+# Replaces three lines with empty variable assignments so that:
+# - ethtool -i (would fail on ENI with real PCI bus-info) is skipped
+# - grep on empty result (would fail with pipefail) is skipped
+_NETWORK_PATCH_CMD = (
+    "sed -i"
+    " -e 's/result=$(ethtool -i \"$VM_NET_DEV\")/result=\"\"/'"
+    " -e '/grep.*driver:/s/.*/  nic=\"\"/'"
+    " -e '/grep.*bus-info:/s/.*/  bus=\"\"/'"
+    " /run/network.sh"
+)
+
+# Original dockur/windows ENTRYPOINT
+_WINDOWS_ENTRYPOINT = "/usr/bin/tini -s /run/entry.sh"
+
+
+def main() -> None:
+    cfg = ConnectionConfigSync(
+        domain=os.getenv("SANDBOX_DOMAIN", "localhost:8080"),
+        api_key=os.getenv("SANDBOX_API_KEY") or None,
+        request_timeout=timedelta(minutes=3),
+        use_server_proxy=True,
+    )
+
+    sbx = SandboxSync.create(
+        image="dockurr/windows:latest",
+        timeout=timedelta(hours=12),
+        ready_timeout=timedelta(minutes=120),
+        resource={"cpu": "8", "memory": "16G", "disk": "64G"},
+        env={
+            "VERSION": "11",
+            "NETWORK": "slirp",  # Use QEMU built-in user-mode NAT
+        },
+        # Patch network.sh then exec the original entrypoint
+        entrypoint=["/bin/sh", "-c", f"{_NETWORK_PATCH_CMD} && exec {_WINDOWS_ENTRYPOINT}"],
+        platform=PlatformSpec(os="windows", arch="amd64"),
+        connection_config=cfg,
+    )
+
+    try:
+        print(f"Created: {sbx.id}")
+        print(f"execd:    {sbx.get_endpoint(44772).endpoint}")
+        print(f"RDP:      {sbx.get_endpoint(3389).endpoint}")
+        print(f"Web:      {sbx.get_endpoint(8006).endpoint}")
+
+        result = sbx.commands.run("cmd /c echo Hello from Windows sandbox")
+        print(f"Command output: {result.logs.stdout[0].text}")
+    finally:
+        sbx.kill()
+        sbx.close()
+
+
+if __name__ == "__main__":
+    main()