Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

Windows: Cua Spaces manages its own container runtime (WSL 2 distribution with Docker) (#6740)

ddupontca8673efa0eb
diff --git a/apps/cua-spaces-desktop/src/model/app-model.ts b/apps/cua-spaces-desktop/src/model/app-model.ts
index 05725f0228..4cc106fed7 100644
--- a/apps/cua-spaces-desktop/src/model/app-model.ts
+++ b/apps/cua-spaces-desktop/src/model/app-model.ts
@@ -694,6 +694,18 @@ export class AppModel {
this.runtimeAdvice = null;
return;
}
+ // Windows: Cua Spaces runs its own engine in WSL 2; when the doctor says why it cannot
+ // (WSL 2 or virtualization off), that is the reason, not "install Docker Desktop".
+ const managed = runtimes.details.get("managed");
+ if (process.platform === "win32" && managed && /wsl|virtual|not enough disk space/i.test(managed)) {
+ this.runtimeAdvice = {
+ reason: managed,
+ fix: /Windows feature|wsl --install/i.test(managed)
+ ? { action: "open-windows-features", label: "Open Windows Features", note: "Turn on the listed features, then restart this PC and open Cua Spaces again.", busy: false, termsUrl: null }
+ : null,
+ };
+ return;
+ }
if (w) this.runtimeAdvice = await w.advice().catch(() => null);
else if (this.linuxRuntime) this.runtimeAdvice = await this.linuxRuntime.advice(runtimes.details.get("container")).catch(() => null);
}
@@ -726,7 +738,7 @@ export class AppModel {
localAvailable: backends ? backends.length > 0 : true,
localReason:
backends && backends.length === 0
- ? (this.runtimeAdvice?.reason ?? noLocalRuntimeReason(process.platform, runtimes?.details.get("container")))
+ ? (this.runtimeAdvice?.reason ?? noLocalRuntimeReason(process.platform, runtimes?.details.get("container"), runtimes?.details.get("managed")))
: undefined,
localBackends: backends,
localDetails: runtimes?.details,
diff --git a/apps/cua-spaces-desktop/src/model/local-runtime.test.ts b/apps/cua-spaces-desktop/src/model/local-runtime.test.ts
index 199e386d5d..1ad7b088e6 100644
--- a/apps/cua-spaces-desktop/src/model/local-runtime.test.ts
+++ b/apps/cua-spaces-desktop/src/model/local-runtime.test.ts
@@ -26,6 +26,12 @@ describe("noLocalRuntimeReason", () => {
expect(noLocalRuntimeReason("win32", "container engine at npipe://x is not running")).toMatch(/isn't running/);
});
+ it("on Windows says what the built-in runtime needs when WSL 2 cannot run it, never to install Docker", () => {
+ const why = "the built-in Linux runtime cannot run here: Virtualization is turned off on this PC. Restart into the BIOS/UEFI setup";
+ expect(noLocalRuntimeReason("win32", "container engine: Socket not found: //./pipe/dockerDesktopLinuxEngine", why)).toBe(why);
+ expect(noLocalRuntimeReason("win32", "no Docker-API socket found", "some other detail")).toMatch(/Docker Desktop/);
+ });
+
it("names the group command when Docker is there but the account may not use it (CUA-1763)", () => {
expect(noLocalRuntimeReason("linux", "permission denied on unix:///var/run/docker.sock: add yourself")).toContain("usermod -aG docker");
});
diff --git a/apps/cua-spaces-desktop/src/model/local-runtime.ts b/apps/cua-spaces-desktop/src/model/local-runtime.ts
index 79576820ba..9b4765c5e8 100644
--- a/apps/cua-spaces-desktop/src/model/local-runtime.ts
+++ b/apps/cua-spaces-desktop/src/model/local-runtime.ts
@@ -10,8 +10,11 @@ const DOCKER_DESKTOP_URL = "https://docs.docker.com/desktop/setup/install/window
* is the runtime doctor's detail for the container engine, when it gave one
* (for example "container engine at npipe://... is not running").
*/
-export function noLocalRuntimeReason(platform: string, containerDetail?: string): string {
+export function noLocalRuntimeReason(platform: string, containerDetail?: string, managedDetail?: string): string {
if (platform === "darwin") return "No local runtime found (Docker or Lume).";
+ // Windows: Cua Spaces runs its own container engine in WSL 2. When it cannot, its
+ // detail says what to turn on (WSL 2, Virtual Machine Platform, virtualization).
+ if (platform === "win32" && managedDetail && /wsl|virtual|not enough disk space/i.test(managedDetail)) return managedDetail;
const detail = (containerDetail ?? "").toLowerCase();
const installedButStopped = /not running|did not answer|not listening|start |socket not found|pipe\/dockerdesktop/.test(detail);
if (platform === "win32") {
diff --git a/docs/content/docs/cua-sdk/guides/local-runtimes.mdx b/docs/content/docs/cua-sdk/guides/local-runtimes.mdx
index ffa3b92627..c994e737b9 100644
--- a/docs/content/docs/cua-sdk/guides/local-runtimes.mdx
+++ b/docs/content/docs/cua-sdk/guides/local-runtimes.mdx
@@ -200,6 +200,43 @@ stops when none of its Spaces runs:
is not enough it refuses with `HostCapacity`, naming the processes that
hold the most descriptors. Fix it by stopping Spaces or VMs you do not use.
+## The Linux runtime on Windows
+
+A PC with no container engine runs Linux Spaces in a WSL 2 distribution that
+cua imports and starts itself. Nothing is installed first: not Docker Desktop,
+not a `docker` CLI. The first Linux Space downloads a pinned Alpine rootfs
+(4 MB, SHA-256 checked) and Alpine's Docker packages (about 90 MB), and
+shows that as the create's progress. After that the runtime starts in a few
+seconds.
+
+- **Its own distribution.** `cua-runtime-<tag>`, where `<tag>` identifies the
+ cua home, with its disk under `<cua home>\runtimes\linux\wsl`. A released
+ Cua Spaces and Cua Spaces Local (each its own cua home) have separate
+ distributions and pipes. cua never starts, stops or changes any other
+ distribution (your Ubuntu, `docker-desktop`) and never touches Docker
+ Desktop. The distribution cannot see your Windows drives and has no Windows
+ interop, so a container engine running as root in it cannot reach your
+ files; for the same reason a Space cannot mount a Windows folder yet.
+- **A pipe, not a port.** Windows reaches Docker at the named pipe
+ `\\.\pipe\cua-engine-<tag>`, served by the cua daemon for your user only.
+ Docker is not published on a TCP port.
+- **Starts on demand, stops when idle.** A hidden `wsl.exe` keeps Docker
+ running; the runtime stops about two minutes after the last Linux Space
+ (`CUA_RUNTIME_LINUX_IDLE_SECS`), like the Mac's. Its memory and processors
+ are WSL's: set them in `%UserProfile%\.wslconfig` (`[wsl2]`), which cua
+ never edits.
+- **When WSL 2 cannot run.** `cua runtime doctor` and the New Space page say
+ what to turn on: the Windows features *Windows Subsystem for Linux* and
+ *Virtual Machine Platform* (`wsl --install --no-distribution` in an
+ administrator PowerShell, then restart), or virtualization in the firmware.
+- **Settings.** `runtime.linux` picks the engine as on a Mac: `auto` uses a
+ working Docker engine on the PC (Docker Desktop, say) and the built-in one
+ otherwise, `builtin` always the built-in one, `system` only the PC's own.
+ Remove host setup deletes the distribution and its disk.
+- **Today.** Spaces run under `runc` (the Mac's runtime adds gVisor), and
+ the distribution shares WSL's VM with your other distributions, so its
+ Docker networks use `10.230.0.0/24` and `10.231.0.0/16`.
+
## Your own cloud
Sandboxes and Spaces can run in a cloud account you own: `--on aws` (EC2),
diff --git a/libs/cua/crates/cua-cli/src/lib.rs b/libs/cua/crates/cua-cli/src/lib.rs
index 55dcf9b003..543d813fbe 100644
--- a/libs/cua/crates/cua-cli/src/lib.rs
+++ b/libs/cua/crates/cua-cli/src/lib.rs
@@ -3423,7 +3423,9 @@ fn runtime_optional_with(
};
let linux_ready = r.backends.iter().any(|b| {
b.ready && matches!(b.backend, B::Qemu | B::Container)
- || b.backend == B::Managed && r.host.os == HostOs::Macos && (b.ready || b.provisionable)
+ || b.backend == B::Managed
+ && matches!(r.host.os, HostOs::Macos | HostOs::Windows)
+ && (b.ready || b.provisionable)
});
let mut optional: Vec<String> = r
.backends
diff --git a/libs/cua/crates/cua-vmm/src/auto.rs b/libs/cua/crates/cua-vmm/src/auto.rs
index 455f6c1f9b..74fea2448d 100644
--- a/libs/cua/crates/cua-vmm/src/auto.rs
+++ b/libs/cua/crates/cua-vmm/src/auto.rs
@@ -551,6 +551,7 @@ pub async fn doctor() -> DoctorReport {
let managed_status = managed_status(
crate::managed::LinuxSource::current(),
container_status.ready,
+ wsl_probe().await,
);
if !container_status.ready && managed_status.provisionable {
container_status
@@ -814,35 +815,86 @@ fn note_kvm_with(
/// The built-in Linux runtime ([`crate::managed`]) for `doctor`: ready
/// while its VM runs; else used (set up or booted on demand) when the
/// `runtime.linux` setting picks it here.
-fn managed_status(source: crate::managed::LinuxSource, engine_ready: bool) -> BackendStatus {
- use crate::managed::{self, LinuxSource};
+fn managed_status(
+ source: crate::managed::LinuxSource,
+ engine_ready: bool,
+ wsl: Option<crate::managed::wsl::Probe>,
+) -> BackendStatus {
+ use crate::managed::{self, LinuxSource, wsl::Probe};
let mb = managed::first_use_download() >> 20;
+ if let Some(Probe::Unavailable(why)) = &wsl
+ && source.allows_builtin()
+ && !engine_ready
+ {
+ // Windows without a usable WSL 2: say what to turn on (never
+ // "install Docker").
+ return BackendStatus {
+ backend: BackendKind::Managed,
+ ready: false,
+ provisionable: false,
+ detail: why.clone(),
+ missing: vec!["WSL 2".into()],
+ provisioning: vec![],
+ };
+ }
let picked = source.allows_builtin()
&& (source == LinuxSource::Builtin || managed::exists() || !engine_ready);
+ // Windows: the runtime's disk and downloads go under the cua home; say
+ // so now, not midway, when that drive has no room for them.
+ if picked
+ && cfg!(windows)
+ && !managed::exists()
+ && let Err(e) = crate::disk::ensure_space(
+ &nearest_existing(&managed::root()),
+ managed::wsl::SETUP_DISK_BYTES,
+ "set up the built-in Linux runtime",
+ )
+ {
+ return BackendStatus {
+ backend: BackendKind::Managed,
+ ready: false,
+ provisionable: false,
+ detail: e.to_string(),
+ missing: vec!["disk space".into()],
+ provisioning: vec![],
+ };
+ }
let running = picked && managed::running();
BackendStatus {
backend: BackendKind::Managed,
ready: running,
provisionable: picked && !running,
detail: if !managed::supported() {
- "the built-in Linux runtime runs on macOS".into()
+ "the built-in Linux runtime runs on macOS and Windows".into()
} else if source == LinuxSource::System {
"Linux Spaces are set to use this Mac's own container engine".into()
+ } else if running && cfg!(windows) {
+ "built-in Linux runtime running (WSL 2, runc)".into()
} else if running {
"built-in Linux runtime running (gVisor)".into()
} else if picked && managed::exists() {
"built-in Linux runtime, started on demand".into()
+ } else if picked && cfg!(windows) {
+ format!("{}, about {mb} MB", managed::STATUS_WINDOWS)
} else if picked {
format!("{}, about {mb} MB", managed::STATUS)
} else {
"not used: this Mac's own container engine runs Linux Spaces".into()
},
missing: vec![],
- provisioning: if picked && !running && !managed::exists() {
+ provisioning: if picked && !running && !managed::exists() && cfg!(windows) {
+ vec![
+ format!("download the built-in Linux runtime (about {mb} MB)"),
+ "import it as a WSL 2 distribution of cua's own and install Docker in it".into(),
+ "start Docker".into(),
+ ]
+ } else if picked && !running && !managed::exists() {
vec![
format!("download the built-in Linux runtime (about {mb} MB)"),
"boot its VM".into(),
]
+ } else if picked && !running && cfg!(windows) {
+ vec!["start its WSL 2 distribution and Docker".into()]
} else if picked && !running {
vec!["boot its VM".into()]
} else {
@@ -851,6 +903,22 @@ fn managed_status(source: crate::managed::LinuxSource, engine_ready: bool) -> Ba
}
}
+/// `path`, or its nearest ancestor that exists (a volume to ask about).
+fn nearest_existing(path: &std::path::Path) -> std::path::PathBuf {
+ path.ancestors()
+ .find(|p| p.exists())
+ .unwrap_or(path)
+ .to_path_buf()
+}
+
+/// What WSL 2 gives the built-in Linux runtime on Windows (`None` elsewhere).
+async fn wsl_probe() -> Option<crate::managed::wsl::Probe> {
+ if !cfg!(windows) {
+ return None;
+ }
+ Some(crate::managed::wsl::probe(&crate::managed::wsl::WslExe).await)
+}
+
/// Choose a backend for `req` given a [`doctor`] report.
pub fn select(req: &SelectRequest, report: &DoctorReport) -> Result<Selection> {
let host = &report.host;
@@ -991,6 +1059,74 @@ fn lume_builtin_allowed() -> bool {
mod tests {
use super::*;
+ /// The disk-space source is process-wide: tests that read or fake it take turns.
+ #[cfg(windows)]
+ static DISK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+ /// A drive without room for the runtime's disk says so before setup
+ /// starts (a fake free-space source; no disk is filled).
+ #[cfg(windows)]
+ #[test]
+ fn windows_without_disk_room_says_how_much_is_needed() {
+ use crate::disk::{Space, SpaceProbe, set_probe};
+ use crate::managed::{LinuxSource, wsl::Probe};
+ let _disk = DISK.lock().unwrap_or_else(|e| e.into_inner());
+ struct Low;
+ impl SpaceProbe for Low {
+ fn space(&self, _: &std::path::Path) -> std::io::Result<Space> {
+ Ok(Space {
+ available: 1 << 30,
+ total: 100 << 30,
+ })
+ }
+ }
+ set_probe(Some(std::sync::Arc::new(Low)));
+ let s = managed_status(
+ LinuxSource::Builtin,
+ false,
+ Some(Probe::Available { distro: false }),
+ );
+ set_probe(None);
+ assert!(!s.provisionable && !s.ready, "{s:?}");
+ assert!(s.detail.contains("not enough disk space"), "{}", s.detail);
+ assert_eq!(s.missing, vec!["disk space".to_string()]);
+ }
+
+ /// A PC whose WSL 2 cannot run says what to turn on, and is not offered
+ /// as a runtime that sets itself up.
+ #[cfg(windows)]
+ #[test]
+ fn windows_without_wsl_says_what_to_turn_on() {
+ let _disk = DISK.lock().unwrap_or_else(|e| e.into_inner());
+ use crate::managed::{LinuxSource, wsl::Probe};
+ let why = "virtualization is turned off";
+ let s = managed_status(
+ LinuxSource::Auto,
+ false,
+ Some(Probe::Unavailable(why.into())),
+ );
+ assert!(!s.ready && !s.provisionable);
+ assert_eq!(s.detail, why);
+ assert_eq!(s.missing, vec!["WSL 2".to_string()]);
+ let ok = managed_status(
+ LinuxSource::Auto,
+ false,
+ Some(Probe::Available { distro: false }),
+ );
+ assert!(ok.provisionable, "{ok:?}");
+ assert!(
+ ok.provisioning.iter().any(|p| p.contains("WSL 2")),
+ "{ok:?}"
+ );
+ // A working engine of the PC's own is used as it is.
+ let sys = managed_status(
+ LinuxSource::Auto,
+ true,
+ Some(Probe::Unavailable(why.into())),
+ );
+ assert!(sys.missing.is_empty());
+ }
+
fn report(
qemu_ready: bool,
lume_ready: bool,
diff --git a/libs/cua/crates/cua-vmm/src/managed.rs b/libs/cua/crates/cua-vmm/src/managed.rs
index c00f60346a..3816cd0eb9 100644
--- a/libs/cua/crates/cua-vmm/src/managed.rs
+++ b/libs/cua/crates/cua-vmm/src/managed.rs
@@ -46,6 +46,9 @@
use std::path::{Path, PathBuf};
+#[path = "managed_wsl.rs"]
+pub mod wsl;
+
use crate::error::{Result, VmmError};
use crate::host;
@@ -154,6 +157,9 @@ pub fn disk_pin() -> Pin {
/// Everything the first Linux Space downloads, in bytes.
pub fn first_use_download() -> u64 {
+ if cfg!(windows) {
+ return wsl::first_use_download();
+ }
colima_pin().size + lima_pin().size + disk_pin().size
}
@@ -161,6 +167,10 @@ pub fn first_use_download() -> u64 {
pub const STATUS: &str =
"built-in Linux runtime (a small VM with Docker and gVisor), set up on first use";
+/// [`STATUS`] on Windows.
+pub const STATUS_WINDOWS: &str =
+ "built-in Linux runtime (a WSL 2 distribution of cua's own with Docker), set up on first use";
+
/// The setting that picks the Linux engine: `runtime.linux` in
/// `$CUA_HOME/config.toml`, overridden by `CUA_RUNTIME_LINUX`.
pub const SETTING_ENV: &str = "CUA_RUNTIME_LINUX";
@@ -226,9 +236,10 @@ impl LinuxSource {
}
}
-/// The built-in runtime runs on macOS 13+ (Virtualization.framework).
+/// The built-in runtime runs on macOS 13+ (Virtualization.framework) and
+/// on Windows (a WSL 2 distribution, [`wsl`]).
pub fn supported() -> bool {
- cfg!(target_os = "macos")
+ cfg!(any(target_os = "macos", windows))
}
/// Local Linux Spaces run on the built-in runtime here, as [`choose`]
@@ -271,11 +282,17 @@ pub fn socket() -> PathBuf {
/// The socket as an engine endpoint.
pub fn endpoint() -> String {
+ if cfg!(windows) {
+ return wsl::endpoint();
+ }
format!("unix://{}", socket().display())
}
/// Whether an engine endpoint is the built-in runtime's.
pub fn is_endpoint(uri: &str) -> bool {
+ if cfg!(windows) {
+ return uri == wsl::endpoint();
+ }
Path::new(uri.trim_start_matches("unix://")).starts_with(root())
}
@@ -286,12 +303,18 @@ fn instance_dir() -> PathBuf {
/// The VM was created (it may be stopped).
pub fn exists() -> bool {
+ if cfg!(windows) {
+ return wsl::provisioned();
+ }
instance_dir().join("lima.yaml").is_file()
}
/// Whether the VM as it runs now shares every job directory (Lima's
/// configuration of the running instance names each).
pub fn shares_job_dirs() -> bool {
+ if cfg!(windows) {
+ return false;
+ }
let Ok(y) = std::fs::read_to_string(instance_dir().join("lima.yaml")) else {
return false;
};
@@ -302,11 +325,18 @@ pub fn shares_job_dirs() -> bool {
/// The VM runs and its Docker engine answers on [`socket`].
pub fn running() -> bool {
+ #[cfg(windows)]
+ {
+ if !wsl::pipe_exists() {
+ wsl::reattach();
+ }
+ wsl::pipe_exists()
+ }
#[cfg(unix)]
{
std::os::unix::net::UnixStream::connect(socket()).is_ok()
}
- #[cfg(not(unix))]
+ #[cfg(not(any(unix, windows)))]
{
false
}
@@ -773,6 +803,9 @@ pub const SETTING_UP: &str = "Setting up the Linux runtime";
/// progress.
#[cfg(feature = "lume")]
pub async fn ensure() -> Result<String> {
+ if cfg!(windows) {
+ return ensure_windows().await;
+ }
if running() {
trim_running_vm_once().await;
return Ok(endpoint());
@@ -785,7 +818,7 @@ pub async fn ensure() -> Result<String> {
if !supported() {
return Err(VmmError::missing(
"a container engine",
- "the built-in Linux runtime runs on macOS; install Docker",
+ "the built-in Linux runtime runs on macOS and Windows; install Docker",
));
}
// Its VM would never start here: say so now, not after a minute of
@@ -865,6 +898,93 @@ pub async fn ensure() -> Result<String> {
Ok(endpoint())
}
+/// When the Windows runtime's engine last answered a check.
+static WINDOWS_VERIFIED: std::sync::Mutex<Option<std::time::Instant>> = std::sync::Mutex::new(None);
+
+/// [`ensure`] on Windows: this home's WSL 2 distribution is imported and
+/// set up when it is not ([`wsl::provision`]), Docker is started in it, and
+/// its pipe is served. Each step is skipped when it is already done, so
+/// calling it again is cheap and safe; the answer is checked at most every
+/// 30 s.
+#[cfg(feature = "lume")]
+async fn ensure_windows() -> Result<String> {
+ use crate::progress::{Phase, Progress, report};
+ let fresh_enough = || {
+ WINDOWS_VERIFIED
+ .lock()
+ .unwrap_or_else(|e| e.into_inner())
+ .is_some_and(|t| t.elapsed() < std::time::Duration::from_secs(30))
+ };
+ if wsl::pipe_exists() && fresh_enough() {
+ return Ok(endpoint());
+ }
+ let _one = SETUP.lock().await;
+ if wsl::pipe_exists() && fresh_enough() {
+ return Ok(endpoint());
+ }
+ let w = wsl::WslExe;
+ let name = wsl::distro();
+ let step = |text: &str, f: f64| {
+ report(
+ Progress::phase(Phase::Preparing)
+ .detail(format!("{SETTING_UP}: {text}"))
+ .fraction(f),
+ )
+ };
+ step("checking WSL", 0.0);
+ let registered = match wsl::probe(&w).await {
+ wsl::Probe::Unavailable(why) => {
+ return Err(VmmError::other(format!(
+ "the built-in Linux runtime cannot run here: {why}"
+ )));
+ }
+ wsl::Probe::Available { distro } => distro,
+ };
+ if !registered || !wsl::provisioned() {
+ let started = std::time::Instant::now();
+ let pin = wsl::rootfs_pin();
+ std::fs::create_dir_all(root())?;
+ crate::disk::ensure_space(
+ &root(),
+ wsl::SETUP_DISK_BYTES,
+ "set up the built-in Linux runtime",
+ )?;
+ if registered {
+ // A setup that did not finish: start it over (this home's distribution only).
+ wsl::unregister(&w, &name).await;
+ }
+ let file = root().join("downloads").join(format!(
+ "alpine-minirootfs-{}-{}.tar.gz",
+ wsl::ALPINE_VERSION,
+ &pin.sha256[..8]
+ ));
+ std::fs::create_dir_all(file.parent().expect("has a parent"))?;
+ let mut dl = Downloads::new(pin.size);
+ download(pin, None, &file, &mut dl).await?;
+ wsl::provision(&w, &name, &wsl::install_dir(), &file, &|t, f| step(t, f)).await?;
+ let _ = std::fs::remove_file(&file);
+ tracing::info!(
+ secs = started.elapsed().as_secs_f64(),
+ "built-in Linux runtime (WSL) is set up"
+ );
+ }
+ step("starting Docker", 0.9);
+ wsl::start_engine(&w, &name).await?;
+ wsl::serve_pipe()?;
+ let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(10);
+ while !wsl::pipe_exists() {
+ if tokio::time::Instant::now() > deadline {
+ return Err(VmmError::other(
+ "the built-in Linux runtime's engine is up but its pipe did not open",
+ ));
+ }
+ tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+ }
+ let _ = std::fs::remove_file(stopped_names_file());
+ *WINDOWS_VERIFIED.lock().unwrap_or_else(|e| e.into_inner()) = Some(std::time::Instant::now());
+ Ok(endpoint())
+}
+
/// Run in the VM after every boot (as root): fails without gVisor, and on
/// arm64 boots the VM's kernel with `arm64.nopauth` from the next boot on.
///
@@ -1072,6 +1192,17 @@ async fn wait_engine() -> Result<()> {
/// Stops the VM (its Spaces stop with it). Nothing to do when it is down.
pub async fn stop(names: &[String]) -> Result<()> {
+ if cfg!(windows) {
+ let _one = SETUP.lock().await;
+ if !exists() {
+ return Ok(());
+ }
+ std::fs::write(stopped_names_file(), serde_json::to_vec(names)?)?;
+ wsl::stop_serving();
+ *WINDOWS_VERIFIED.lock().unwrap_or_else(|e| e.into_inner()) = None;
+ wsl::terminate(&wsl::WslExe, &wsl::distro()).await;
+ return Ok(());
+ }
let Some(tools) = installed_tools() else {
return Ok(());
};
@@ -1087,6 +1218,12 @@ pub async fn stop(names: &[String]) -> Result<()> {
/// A Colima, Lima or Docker of the user's is elsewhere and stays.
pub async fn remove() -> Result<()> {
let _one = SETUP.lock().await;
+ if cfg!(windows) {
+ wsl::stop_serving();
+ *WINDOWS_VERIFIED.lock().unwrap_or_else(|e| e.into_inner()) = None;
+ // This home's distribution only; the user's own are never named.
+ wsl::unregister(&wsl::WslExe, &wsl::distro()).await;
+ }
if let Some(tools) = installed_tools()
&& exists()
&& let Err(e) = run_colima(&tools, &["delete", "--force", "--data"], 180).await
@@ -1363,7 +1500,7 @@ mod engine_impl {
LinuxSource::Builtin if supported() => builtin(cfg),
LinuxSource::Builtin => Err(VmmError::missing(
"a container engine",
- "the built-in Linux runtime runs on macOS; set runtime.linux to auto or system",
+ "the built-in Linux runtime runs on macOS and Windows; set runtime.linux to auto or system",
)),
LinuxSource::System => ContainerRuntime::connect(cfg)
.await
@@ -1474,6 +1611,12 @@ mod engine_impl {
/// is not in the VM.
async fn ready_for_mounts(&self, spec: &StartSpec) -> Result<()> {
crate::types::check_mounts(crate::BackendKind::Container, &spec.mounts)?;
+ if cfg!(windows) && !spec.mounts.is_empty() {
+ return Err(VmmError::invalid(
+ "the built-in Linux runtime on Windows cannot mount Windows folders yet \
+ (its distribution has no access to the Windows drives)",
+ ));
+ }
if let Some(m) = spec.mounts.iter().find(|m| !is_shared(&m.host)) {
return Err(VmmError::invalid(format!(
"the built-in Linux runtime shares only cua's job directories, not {}",
@@ -1977,11 +2120,16 @@ mod tests {
let dir = tempfile::tempdir().unwrap();
let file = dir.path().join("trim.sh");
std::fs::write(&file, body).unwrap();
- let out = std::process::Command::new("sh")
+ let out = match std::process::Command::new("sh")
.arg("-n")
.arg(&file)
.output()
- .unwrap();
+ {
+ Ok(o) => o,
+ // No `sh` on this PC (a Windows host without Git Bash): nothing to parse it with.
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return,
+ Err(e) => panic!("{e}"),
+ };
assert!(
out.status.success(),
"{}",
@@ -2053,7 +2201,7 @@ mod tests {
assert!(!LinuxSource::System.allows_builtin());
assert_eq!(
LinuxSource::Auto.allows_builtin(),
- cfg!(target_os = "macos")
+ cfg!(any(target_os = "macos", windows))
);
}
diff --git a/libs/cua/crates/cua-vmm/src/managed_wsl.rs b/libs/cua/crates/cua-vmm/src/managed_wsl.rs
new file mode 100644
index 0000000000..185596b413
--- /dev/null
+++ b/libs/cua/crates/cua-vmm/src/managed_wsl.rs
@@ -0,0 +1,915 @@
+//! The built-in Linux runtime on Windows: a WSL2 distribution cua owns,
+//! running Docker, so Linux Spaces run on a PC with nothing installed first
+//! (no Docker Desktop), like the built-in runtime on a Mac ([`super`]).
+//!
+//! # How it works
+//!
+//! * **A distribution of cua's own.** `cua-runtime-<tag>`, imported
+//! (`wsl --import`) from a pinned, SHA-256 checked Alpine minirootfs
+//! ([`rootfs_pin`], about 4 MB) into `<cua home>/runtimes/linux/wsl`. `<tag>` is
+//! a digest of the cua home, so each home (a released Cua Spaces, Cua Spaces
+//! Local, a test home) has its own distribution, pipe and disk, and none can
+//! see another's. An existing distribution (the user's Ubuntu,
+//! `docker-desktop`) is never read, started, stopped or changed: cua only
+//! ever names its own.
+//! * **Docker inside it.** One-time setup installs Docker Engine, `socat` and
+//! `iptables` from Alpine's package repository ([`PACKAGES`]) and a
+//! `wsl.conf` that turns off the distribution's access to the user's
+//! Windows drives and Windows interop: a container engine running as root
+//! in it cannot reach the user's files. Its bridge networks use
+//! [`BRIDGE_CIDR`] and [`ADDRESS_POOL`], away from the subnets WSL and
+//! Hyper-V pick.
+//! * **Started on demand.** A hidden `wsl.exe -d <distro> --exec dockerd`
+//! keeps the engine (and the distribution, which WSL stops when nothing runs
+//! in it) alive. It outlives the process that started it, so a restarted
+//! daemon finds the engine running. The VM WSL runs all distributions in
+//! is shared with whatever else the user runs; its memory and processor
+//! limits are the user's `.wslconfig`.
+//! * **A pipe, not a TCP port.** Windows reaches the engine at the named pipe
+//! `\\.\pipe\cua-engine-<tag>` ([`pipe_name`]), served by the cua daemon:
+//! each connection runs `socat` in the distribution against Docker's
+//! socket. Only this user (the pipe's default security) and no remote
+//! client can connect; Docker is never published on a TCP port.
+//! [`crate::container::ContainerRuntime`] connects to it unchanged.
+//! * **When it cannot.** WSL2 missing, off or without virtualization is
+//! reported with what to turn on ([`classify_failure`]), never "install
+//! Docker".
+//!
+//! Differences from Docker Desktop: no GUI, no `docker` CLI on the PATH, no
+//! Windows drive mounts in Spaces, and no Kubernetes; from the macOS
+//! runtime: Spaces run under `runc` (no gVisor yet) and the engine's VM is
+//! WSL's, shared with the user's other distributions.
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use sha2::{Digest, Sha256};
+
+use super::Pin;
+use crate::error::{Result, VmmError};
+use crate::host;
+
+/// The Alpine release of the pinned rootfs.
+pub const ALPINE_VERSION: &str = "3.24.4";
+
+/// What the one-time setup installs, from Alpine's repository.
+pub const PACKAGES: &str = "docker socat iptables ca-certificates";
+
+/// Docker's default bridge, away from WSL's own `172.x` subnets.
+pub const BRIDGE_CIDR: &str = "10.230.0.1/24";
+/// Where user-defined networks get their subnets.
+pub const ADDRESS_POOL: &str = "10.231.0.0/16";
+
+/// Docker's socket inside the distribution.
+pub const GUEST_SOCKET: &str = "/run/cua/docker.sock";
+
+/// Bumped when the one-time setup changes: an older distribution is set up again.
+pub const SETUP_VERSION: u32 = 1;
+
+/// The pinned Alpine minirootfs for this PC's architecture.
+pub fn rootfs_pin() -> Pin {
+ if cfg!(target_arch = "aarch64") {
+ Pin {
+ url: "https://dl-cdn.alpinelinux.org/alpine/v3.24/releases/aarch64/alpine-minirootfs-3.24.4-aarch64.tar.gz",
+ sha256: "4b14c18f7e90a063b61462ea1462a5732c154bf6adad594974fe6487cd98a8de",
+ size: 4_029_843,
+ }
+ } else {
+ Pin {
+ url: "https://dl-cdn.alpinelinux.org/alpine/v3.24/releases/x86_64/alpine-minirootfs-3.24.4-x86_64.tar.gz",
+ sha256: "cdaa38cb8de3537967ee5b6c9b6cd00cc962da2b018e6eea48696bb274923012",
+ size: 3_704_088,
+ }
+ }
+}
+
+/// What setting up writes under the cua home: the rootfs, the distribution's
+/// disk (a sparse VHDX that grows with images and Spaces) and Docker's
+/// packages. The guard keeps `CUA_DISK_MIN_FREE` (5 GiB) free on top.
+pub const SETUP_DISK_BYTES: u64 = 2 << 30;
+
+/// What the first Linux Space downloads: the rootfs and about 90 MB of packages.
+pub fn first_use_download() -> u64 {
+ rootfs_pin().size + (90 << 20)
+}
+
+/// Eight hex digits of the cua home's digest: what tells homes apart.
+fn tag_of(home: &str) -> String {
+ let d = Sha256::digest(home.trim_end_matches(['\\', '/']).to_lowercase().as_bytes());
+ d.iter().take(4).map(|b| format!("{b:02x}")).collect()
+}
+
+/// This home's tag.
+pub fn tag() -> String {
+ tag_of(&host::cua_home().to_string_lossy())
+}
+
+/// Every distribution cua creates starts with this.
+pub const DISTRO_PREFIX: &str = "cua-runtime-";
+
+/// This home's distribution.
+pub fn distro() -> String {
+ format!("{DISTRO_PREFIX}{}", tag())
+}
+
+/// The named pipe the engine is served at.
+pub fn pipe_name() -> String {
+ format!(r"\\.\pipe\cua-engine-{}", tag())
+}
+
+/// The pipe as an engine endpoint.
+pub fn endpoint() -> String {
+ format!("npipe:////./pipe/cua-engine-{}", tag())
+}
+
+/// Where the distribution's disk lives.
+pub fn install_dir() -> PathBuf {
+ super::root().join("wsl")
+}
+
+/// Written once the distribution is set up (its [`SETUP_VERSION`]).
+pub fn marker() -> PathBuf {
+ marker_in(&install_dir())
+}
+
+fn marker_in(dir: &std::path::Path) -> PathBuf {
+ dir.join("provisioned")
+}
+
+/// Whether setup finished for this home (the distribution may be stopped).
+pub fn provisioned() -> bool {
+ std::fs::read_to_string(marker())
+ .ok()
+ .and_then(|s| s.trim().parse::<u32>().ok())
+ .is_some_and(|v| v == SETUP_VERSION)
+}
+
+// ---------------------------------------------------------------------------
+// Talking to wsl.exe
+// ---------------------------------------------------------------------------
+
+/// What a `wsl.exe` call printed.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct WslOutput {
+ pub code: i32,
+ pub stdout: String,
+ pub stderr: String,
+}
+
+impl WslOutput {
+ pub fn ok(&self) -> bool {
+ self.code == 0
+ }
+
+ /// Everything it printed, trimmed.
+ pub fn text(&self) -> String {
+ format!("{}\n{}", self.stdout.trim(), self.stderr.trim())
+ .trim()
+ .to_string()
+ }
+}
+
+/// Runs `wsl.exe` (a fake in tests).
+#[async_trait]
+pub trait Wsl: Send + Sync {
+ /// `wsl.exe <args>`, killed after `secs`.
+ async fn run(&self, args: &[String], secs: u64) -> std::io::Result<WslOutput>;
+}
+
+/// The real `wsl.exe`.
+pub struct WslExe;
+
+/// `wsl.exe` prints its own messages in UTF-16LE (or UTF-8 with
+/// `WSL_UTF8=1`); what a Linux program prints is UTF-8.
+pub fn decode(bytes: &[u8]) -> String {
+ let utf16 = bytes.len() >= 2 && (bytes[1] == 0 || bytes[..2] == [0xff, 0xfe]);
+ let s = if utf16 {
+ let units: Vec<u16> = bytes
+ .chunks_exact(2)
+ .map(|c| u16::from_le_bytes([c[0], c[1]]))
+ .collect();
+ String::from_utf16_lossy(&units)
+ } else {
+ String::from_utf8_lossy(bytes).into_owned()
+ };
+ s.trim_start_matches('\u{feff}')
+ .replace(['\r', '\0'], "")
+ .to_string()
+}
+
+#[async_trait]
+impl Wsl for WslExe {
+ async fn run(&self, args: &[String], secs: u64) -> std::io::Result<WslOutput> {
+ let mut c = tokio::process::Command::new("wsl.exe");
+ c.args(args)
+ .env("WSL_UTF8", "1")
+ .stdin(std::process::Stdio::null())
+ .stdout(std::process::Stdio::piped())
+ .stderr(std::process::Stdio::piped())
+ .kill_on_drop(true);
+ #[cfg(windows)]
+ c.creation_flags(CREATE_NO_WINDOW);
+ let child = c.spawn()?;
+ let out = tokio::time::timeout(
+ std::time::Duration::from_secs(secs),
+ child.wait_with_output(),
+ )
+ .await
+ .map_err(|_| {
+ std::io::Error::new(
+ std::io::ErrorKind::TimedOut,
+ format!("wsl.exe {} took longer than {secs} s", args.join(" ")),
+ )
+ })??;
+ Ok(WslOutput {
+ code: out.status.code().unwrap_or(-1),
+ stdout: decode(&out.stdout),
+ stderr: decode(&out.stderr),
+ })
+ }
+}
+
+#[cfg(windows)]
+const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+#[cfg(windows)]
+const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
+#[cfg(windows)]
+const CREATE_BREAKAWAY_FROM_JOB: u32 = 0x0100_0000;
+
+fn args(a: &[&str]) -> Vec<String> {
+ a.iter().map(|s| s.to_string()).collect()
+}
+
+/// `wsl.exe -d <distro> -u root --exec <program> <args...>`.
+fn exec_args(distro: &str, program: &[&str]) -> Vec<String> {
+ let mut v = args(&["-d", distro, "-u", "root", "--exec"]);
+ v.extend(program.iter().map(|s| s.to_string()));
+ v
+}
+
+// ---------------------------------------------------------------------------
+// What is there
+// ---------------------------------------------------------------------------
+
+/// What `doctor` and `ensure` find out about WSL.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Probe {
+ /// WSL is not installed or not usable: what to do about it.
+ Unavailable(String),
+ /// WSL answers.
+ Available {
+ /// This home's distribution is registered.
+ distro: bool,
+ },
+}
+
+/// Why `wsl.exe` is not usable, in the user's words.
+pub const NOT_INSTALLED: &str = "Windows Subsystem for Linux (WSL 2) is not installed. \
+Cua Spaces runs Linux Spaces in its own small WSL 2 distribution, which needs it: open \
+PowerShell as an administrator and run `wsl --install --no-distribution`, restart, and \
+try again";
+
+/// Looks at WSL and this home's distribution (starts nothing).
+pub async fn probe(wsl: &dyn Wsl) -> Probe {
+ match wsl.run(&args(&["--version"]), 20).await {
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+ return Probe::Unavailable(NOT_INSTALLED.into());
+ }
+ Err(e) => return Probe::Unavailable(format!("wsl.exe did not answer: {e}")),
+ Ok(o) if !o.ok() => return Probe::Unavailable(NOT_INSTALLED.into()),
+ Ok(_) => {}
+ }
+ match list(wsl, false).await {
+ Ok(names) => Probe::Available {
+ distro: names.iter().any(|n| n == &distro()),
+ },
+ Err(e) => Probe::Unavailable(e),
+ }
+}
+
+/// Registered (or, with `running`, running) distribution names. A PC with
+/// none registered says so with a failing exit code: that is an empty list.
+pub async fn list(wsl: &dyn Wsl, running: bool) -> std::result::Result<Vec<String>, String> {
+ let mut a = args(&["-l", "-q"]);
+ if running {
+ a.insert(1, "--running".into());
+ }
+ let o = wsl
+ .run(&a, 30)
+ .await
+ .map_err(|e| format!("wsl.exe did not answer: {e}"))?;
+ Ok(o.stdout
+ .lines()
+ .map(|l| l.trim().trim_end_matches("(Default)").trim().to_string())
+ .filter(|l| !l.is_empty())
+ .collect())
+}
+
+/// What the failure of a `wsl.exe` call means for the person, when it is one
+/// of the known ways a PC cannot run WSL 2; `None` for anything else.
+pub fn classify_failure(output: &str) -> Option<String> {
+ let o = output.to_lowercase();
+ let has = |words: &[&str]| words.iter().any(|w| o.contains(w));
+ if has(&[
+ "0x80370102",
+ "virtualization is not enabled",
+ "virtualization must be enabled",
+ "enable virtualization",
+ "bios",
+ ]) {
+ Some(
+ "Virtualization is turned off on this PC. Restart into the BIOS/UEFI setup, turn on \
+ Intel Virtualization Technology (VT-x) or AMD SVM Mode, start Windows, and try \
+ again. (If this is a virtual machine, turn on nested virtualization for it.)"
+ .into(),
+ )
+ } else if has(&["0x80370114", "virtual machine platform", "0x80370102"]) {
+ Some(
+ "The Windows feature Virtual Machine Platform is off. In PowerShell as an \
+ administrator run `wsl --install --no-distribution` (or `dism.exe /online \
+ /enable-feature /featurename:VirtualMachinePlatform /all /norestart`), restart, \
+ and try again."
+ .into(),
+ )
+ } else if has(&[
+ "0x8007019e",
+ "optional component is not enabled",
+ "subsystem for linux optional",
+ ]) {
+ Some(
+ "The Windows feature Windows Subsystem for Linux is off. In PowerShell as an \
+ administrator run `wsl --install --no-distribution`, restart, and try again."
+ .into(),
+ )
+ } else if has(&["kernel update", "wsl --update", "0x800701bc"]) {
+ Some(
+ "WSL 2 needs its kernel updated: run `wsl --update` in PowerShell, then try again."
+ .into(),
+ )
+ } else if has(&["0x80070003", "0x80070002", "0x8007023e"]) {
+ Some(format!(
+ "Windows could not create the runtime's disk under {}: check that the drive exists \
+ and has room, then try again.",
+ install_dir().display()
+ ))
+ } else {
+ None
+ }
+}
+
+/// An error for a failed `wsl.exe` step: the known cause, else its output.
+fn failed(step: &str, out: &WslOutput) -> VmmError {
+ let text = out.text();
+ match classify_failure(&text) {
+ Some(why) => VmmError::other(format!(
+ "the built-in Linux runtime cannot be set up: {why}"
+ )),
+ None => VmmError::other(format!(
+ "the built-in Linux runtime: {step} failed (exit {}): {}",
+ out.code,
+ last_lines(&text, 6)
+ )),
+ }
+}
+
+fn last_lines(s: &str, n: usize) -> String {
+ let lines: Vec<&str> = s.lines().filter(|l| !l.trim().is_empty()).collect();
+ lines[lines.len().saturating_sub(n)..].join(" | ")
+}
+
+// ---------------------------------------------------------------------------
+// The one-time setup
+// ---------------------------------------------------------------------------
+
+/// `/etc/wsl.conf`: no Windows drives, no Windows interop, no systemd.
+pub const WSL_CONF: &str = "[automount]\nenabled=false\nmountFsTab=false\n\n[interop]\nenabled=false\nappendWindowsPath=false\n\n[boot]\nsystemd=false\n\n[user]\ndefault=root\n";
+
+/// Docker's `daemon.json`.
+pub fn daemon_json() -> String {
+ format!(
+ "{{\"bip\":\"{BRIDGE_CIDR}\",\"default-address-pools\":[{{\"base\":\"{ADDRESS_POOL}\",\"size\":24}}],\"log-driver\":\"local\",\"log-opts\":{{\"max-size\":\"20m\",\"max-file\":\"3\"}}}}"
+ )
+}
+
+/// Run in the new distribution, as root: its configuration.
+pub fn configure_script() -> String {
+ format!(
+ "set -e\nprintf '%s' '{}' > /etc/wsl.conf\nmkdir -p /etc/docker\nprintf '%s' '{}' > /etc/docker/daemon.json\n",
+ WSL_CONF,
+ daemon_json()
+ )
+}
+
+/// Run in the distribution, as root, after it restarted with its configuration.
+pub fn install_script() -> String {
+ format!(
+ "set -e\napk add --no-cache {PACKAGES}\ndocker --version >/dev/null\nprintf 'cua-runtime setup {SETUP_VERSION}\\n' > /etc/cua-runtime\n"
+ )
+}
+
+/// The program that is the engine: Docker's daemon on [`GUEST_SOCKET`].
+pub const DOCKERD_SCRIPT: &str = "mkdir -p /run/cua && exec dockerd --host=unix:///run/cua/docker.sock --pidfile=/run/cua/dockerd.pid >>/var/log/dockerd.log 2>&1";
+
+/// Docker answers in the distribution.
+pub async fn engine_answers(wsl: &dyn Wsl, distro: &str) -> bool {
+ let a = exec_args(
+ distro,
+ &[
+ "docker",
+ "-H",
+ "unix:///run/cua/docker.sock",
+ "version",
+ "--format",
+ "{{.Server.Version}}",
+ ],
+ );
+ matches!(wsl.run(&a, 20).await, Ok(o) if o.ok() && !o.stdout.trim().is_empty())
+}
+
+/// Imports the distribution from the rootfs, configures and sets it up. Any
+/// failure removes what this call created.
+#[cfg(feature = "lume")]
+pub async fn provision(
+ wsl: &dyn Wsl,
+ name: &str,
+ dir: &std::path::Path,
+ rootfs: &std::path::Path,
+ report: &(dyn Fn(&str, f64) + Sync),
+) -> Result<()> {
+ std::fs::create_dir_all(dir)?;
+ let disk = dir.join("disk");
+ let _ = std::fs::remove_dir_all(&disk);
+ std::fs::create_dir_all(&disk)?;
+ report("Importing the Linux runtime", 0.05);
+ let import = wsl
+ .run(
+ &args(&[
+ "--import",
+ name,
+ &disk.to_string_lossy(),
+ &rootfs.to_string_lossy(),
+ "--version",
+ "2",
+ ]),
+ 300,
+ )
+ .await
+ .map_err(|e| VmmError::other(format!("wsl.exe --import: {e}")))?;
+ if !import.ok() {
+ let _ = std::fs::remove_dir_all(&disk);
+ return Err(failed("wsl --import", &import));
+ }
+ let built = async {
+ report("Configuring the Linux runtime", 0.25);
+ let cfg = wsl
+ .run(&exec_args(name, &["sh", "-c", &configure_script()]), 120)
+ .await
+ .map_err(|e| VmmError::other(format!("configuring the runtime: {e}")))?;
+ if !cfg.ok() {
+ return Err(failed("configuring the distribution", &cfg));
+ }
+ // wsl.conf is read when the distribution starts.
+ terminate(wsl, name).await;
+ report("Installing Docker in the Linux runtime", 0.4);
+ let inst = wsl
+ .run(&exec_args(name, &["sh", "-c", &install_script()]), 900)
+ .await
+ .map_err(|e| VmmError::other(format!("installing Docker: {e}")))?;
+ if !inst.ok() {
+ return Err(failed("installing Docker (is the network up?)", &inst));
+ }
+ std::fs::write(marker_in(dir), SETUP_VERSION.to_string())?;
+ Ok(())
+ }
+ .await;
+ if built.is_err() {
+ // Only the distribution this call imported.
+ unregister(wsl, name).await;
+ let _ = std::fs::remove_dir_all(&disk);
+ }
+ built
+}
+
+/// Stops this home's distribution (nothing else).
+pub async fn terminate(wsl: &dyn Wsl, name: &str) {
+ if name.starts_with(DISTRO_PREFIX) {
+ let _ = wsl.run(&args(&["--terminate", name]), 60).await;
+ }
+}
+
+/// Removes this home's distribution and its disk (nothing else).
+pub async fn unregister(wsl: &dyn Wsl, name: &str) {
+ if name.starts_with(DISTRO_PREFIX) {
+ let _ = wsl.run(&args(&["--unregister", name]), 120).await;
+ }
+}
+
+/// Starts Docker in the distribution when it does not answer, and waits for it.
+pub async fn start_engine(wsl: &dyn Wsl, name: &str) -> Result<()> {
+ if engine_answers(wsl, name).await {
+ return Ok(());
+ }
+ spawn_engine(name)?;
+ let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(90);
+ loop {
+ if engine_answers(wsl, name).await {
+ return Ok(());
+ }
+ if tokio::time::Instant::now() > deadline {
+ let log = wsl
+ .run(
+ &exec_args(name, &["tail", "-n", "5", "/var/log/dockerd.log"]),
+ 20,
+ )
+ .await
+ .map(|o| last_lines(&o.text(), 5))
+ .unwrap_or_default();
+ return Err(VmmError::other(format!(
+ "the built-in Linux runtime started but Docker did not answer within 90 s: {log}"
+ )));
+ }
+ tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+ }
+}
+
+/// A hidden `wsl.exe` that is Docker. It outlives this process.
+fn spawn_engine(name: &str) -> Result<()> {
+ let mut c = std::process::Command::new("wsl.exe");
+ c.args(exec_args(name, &["sh", "-c", DOCKERD_SCRIPT]))
+ .env("WSL_UTF8", "1")
+ .stdin(std::process::Stdio::null())
+ .stdout(std::process::Stdio::null())
+ .stderr(std::process::Stdio::null());
+ #[cfg(windows)]
+ {
+ use std::os::windows::process::CommandExt as _;
+ let base = CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP;
+ // Out of the parent's job (Electron's, a terminal's), when it allows it.
+ if c.creation_flags(base | CREATE_BREAKAWAY_FROM_JOB)
+ .spawn()
+ .is_ok()
+ {
+ return Ok(());
+ }
+ c.creation_flags(base);
+ }
+ c.spawn()
+ .map(drop)
+ .map_err(|e| VmmError::other(format!("starting wsl.exe: {e}")))
+}
+
+// ---------------------------------------------------------------------------
+// The pipe
+// ---------------------------------------------------------------------------
+
+/// Whether the engine's pipe is there (served by this or another process).
+pub fn pipe_exists() -> bool {
+ #[cfg(windows)]
+ {
+ match std::fs::metadata(pipe_name()) {
+ Ok(_) => true,
+ // Busy: its one listening instance is taken this instant.
+ Err(e) => e.raw_os_error() == Some(231),
+ }
+ }
+ #[cfg(not(windows))]
+ {
+ false
+ }
+}
+
+/// Stops serving the pipe from this process (the engine is stopping).
+pub fn stop_serving() {
+ #[cfg(windows)]
+ {
+ if let Some(h) = SERVING.lock().unwrap_or_else(|e| e.into_inner()).take() {
+ h.abort();
+ }
+ }
+}
+
+#[cfg(windows)]
+static SERVING: std::sync::Mutex<Option<tokio::task::JoinHandle<()>>> = std::sync::Mutex::new(None);
+
+/// A daemon that restarted finds this home's engine still running (its
+/// `wsl.exe` outlives it) and serves the pipe again, at most every 5 s.
+pub fn reattach() {
+ #[cfg(windows)]
+ {
+ static LAST: std::sync::Mutex<Option<std::time::Instant>> = std::sync::Mutex::new(None);
+ {
+ let mut last = LAST.lock().unwrap_or_else(|e| e.into_inner());
+ if last.is_some_and(|t| t.elapsed() < std::time::Duration::from_secs(5)) {
+ return;
+ }
+ *last = Some(std::time::Instant::now());
+ }
+ if !provisioned() || tokio::runtime::Handle::try_current().is_err() {
+ return;
+ }
+ use std::os::windows::process::CommandExt as _;
+ let Ok(o) = std::process::Command::new("wsl.exe")
+ .args(["-l", "--running", "-q"])
+ .env("WSL_UTF8", "1")
+ .creation_flags(CREATE_NO_WINDOW)
+ .output()
+ else {
+ return;
+ };
+ if decode(&o.stdout).lines().any(|l| l.trim() == distro()) {
+ let _ = serve_pipe();
+ }
+ }
+}
+
+/// Serves the engine's pipe from this process until it ends: every
+/// connection is a `socat` in the distribution against Docker's socket.
+/// Another process already serving it is fine.
+pub fn serve_pipe() -> Result<()> {
+ #[cfg(windows)]
+ {
+ use tokio::net::windows::named_pipe::ServerOptions;
+ let mut slot = SERVING.lock().unwrap_or_else(|e| e.into_inner());
+ if slot.as_ref().is_some_and(|h| !h.is_finished()) {
+ return Ok(());
+ }
+ let name = pipe_name();
+ let first = match ServerOptions::new()
+ .first_pipe_instance(true)
+ .reject_remote_clients(true)
+ .create(&name)
+ {
+ Ok(s) => s,
+ // Access denied or busy: another process serves it.
+ Err(e) if matches!(e.raw_os_error(), Some(5) | Some(231)) => return Ok(()),
+ Err(e) => {
+ return Err(VmmError::other(format!(
+ "the built-in Linux runtime cannot open its pipe {name}: {e}"
+ )));
+ }
+ };
+ let distro = distro();
+ *slot = Some(tokio::spawn(async move {
+ let mut server = first;
+ loop {
+ if server.connect().await.is_err() {
+ break;
+ }
+ let client = server;
+ server = match ServerOptions::new()
+ .reject_remote_clients(true)
+ .create(&name)
+ {
+ Ok(s) => s,
+ Err(e) => {
+ tracing::warn!("the built-in Linux runtime's pipe stopped: {e}");
+ break;
+ }
+ };
+ tokio::spawn(bridge(client, distro.clone()));
+ }
+ }));
+ Ok(())
+ }
+ #[cfg(not(windows))]
+ {
+ Err(VmmError::other(
+ "the Windows runtime's pipe only exists on Windows",
+ ))
+ }
+}
+
+/// One client of the pipe to Docker's socket.
+#[cfg(windows)]
+async fn bridge(client: tokio::net::windows::named_pipe::NamedPipeServer, distro: String) {
+ use tokio::io::{AsyncWriteExt as _, split};
+ let mut c = tokio::process::Command::new("wsl.exe");
+ c.args(exec_args(
+ &distro,
+ &["socat", "-", &format!("UNIX-CONNECT:{GUEST_SOCKET}")],
+ ))
+ .env("WSL_UTF8", "1")
+ .stdin(std::process::Stdio::piped())
+ .stdout(std::process::Stdio::piped())
+ .stderr(std::process::Stdio::null())
+ .creation_flags(CREATE_NO_WINDOW)
+ .kill_on_drop(true);
+ let Ok(mut child) = c.spawn() else { return };
+ let (Some(mut to_guest), Some(mut from_guest)) = (child.stdin.take(), child.stdout.take())
+ else {
+ return;
+ };
+ let (mut from_client, mut to_client) = split(client);
+ let up = async {
+ let _ = tokio::io::copy(&mut from_client, &mut to_guest).await;
+ let _ = to_guest.shutdown().await;
+ };
+ let down = async {
+ let _ = tokio::io::copy(&mut from_guest, &mut to_client).await;
+ let _ = to_client.shutdown().await;
+ };
+ // The connection is over when Docker's side ends; the client's side
+ // ending only closes the request half.
+ tokio::pin!(up);
+ tokio::pin!(down);
+ tokio::select! {
+ _ = &mut down => {}
+ _ = async { (&mut up).await; std::future::pending::<()>().await } => {}
+ }
+ let _ = child.kill().await;
+}
+
+/// Alias for callers that hold the process-wide `WslExe`.
+pub fn real() -> Arc<WslExe> {
+ Arc::new(WslExe)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::sync::Mutex;
+
+ /// A `wsl.exe` that answers from a script and records what it was asked.
+ struct Fake {
+ calls: Mutex<Vec<String>>,
+ answers: Vec<(&'static str, WslOutput)>,
+ }
+
+ impl Fake {
+ fn new(answers: Vec<(&'static str, WslOutput)>) -> Self {
+ Self {
+ calls: Mutex::new(vec![]),
+ answers,
+ }
+ }
+ }
+
+ fn out(code: i32, stdout: &str, stderr: &str) -> WslOutput {
+ WslOutput {
+ code,
+ stdout: stdout.into(),
+ stderr: stderr.into(),
+ }
+ }
+
+ #[async_trait]
+ impl Wsl for Fake {
+ async fn run(&self, args: &[String], _secs: u64) -> std::io::Result<WslOutput> {
+ let line = args.join(" ");
+ self.calls.lock().unwrap().push(line.clone());
+ Ok(self
+ .answers
+ .iter()
+ .find(|(k, _)| line.contains(k))
+ .map(|(_, o)| o.clone())
+ .unwrap_or_else(|| out(0, "", "")))
+ }
+ }
+
+ #[test]
+ fn utf16_output_of_wsl_exe_is_decoded() {
+ let bytes: Vec<u8> = "\u{feff}Ubuntu\r\ndocker-desktop\r\n"
+ .encode_utf16()
+ .flat_map(|u| u.to_le_bytes())
+ .collect();
+ assert_eq!(decode(&bytes), "Ubuntu\ndocker-desktop\n");
+ assert_eq!(decode(b"plain\r\n"), "plain\n");
+ }
+
+ #[test]
+ fn homes_get_their_own_names_and_pipes() {
+ assert_eq!(tag_of(r"C:\Users\a\.cua"), tag_of(r"c:\users\a\.cua\"));
+ assert_ne!(tag_of(r"C:\Users\a\.cua"), tag_of(r"C:\Users\a\.cua-local"));
+ assert_eq!(tag_of("x").len(), 8);
+ assert!(distro().starts_with(DISTRO_PREFIX));
+ assert!(pipe_name().starts_with(r"\\.\pipe\cua-engine-"));
+ assert!(endpoint().starts_with("npipe:////./pipe/cua-engine-"));
+ // Never one of Docker Desktop's.
+ assert!(!distro().contains("docker-desktop"));
+ assert!(!endpoint().contains("docker_engine"));
+ }
+
+ #[test]
+ fn the_pins_are_checked_downloads() {
+ let p = rootfs_pin();
+ assert_eq!(p.sha256.len(), 64);
+ assert!(p.url.starts_with("https://"));
+ assert!(p.url.contains(ALPINE_VERSION));
+ }
+
+ #[test]
+ fn known_wsl_failures_say_what_to_turn_on() {
+ let v = classify_failure("WslRegisterDistribution failed with error: 0x80370102").unwrap();
+ assert!(v.contains("BIOS"), "{v}");
+ let f =
+ classify_failure("Please enable the Virtual Machine Platform Windows feature").unwrap();
+ assert!(f.contains("Virtual Machine Platform"), "{f}");
+ let w = classify_failure("Error: 0x8007019e").unwrap();
+ assert!(w.contains("wsl --install"), "{w}");
+ assert!(classify_failure("some other failure").is_none());
+ // Never tells the user to install Docker.
+ for m in [&v, &f, &w] {
+ assert!(!m.to_lowercase().contains("install docker"));
+ }
+ }
+
+ #[tokio::test]
+ async fn probe_tells_missing_wsl_from_a_missing_distro() {
+ let none = Fake::new(vec![("--version", out(1, "", "invalid option"))]);
+ assert_eq!(probe(&none).await, Probe::Unavailable(NOT_INSTALLED.into()));
+ let other = Fake::new(vec![("-l -q", out(0, "Ubuntu\ndocker-desktop\n", ""))]);
+ assert_eq!(probe(&other).await, Probe::Available { distro: false });
+ let ours = Fake::new(vec![(
+ "-l -q",
+ out(0, &format!("Ubuntu (Default)\n{}\n", distro()), ""),
+ )]);
+ assert_eq!(probe(&ours).await, Probe::Available { distro: true });
+ }
+
+ #[tokio::test]
+ async fn only_our_distribution_is_ever_stopped_or_removed() {
+ let w = Fake::new(vec![]);
+ terminate(&w, "Ubuntu").await;
+ unregister(&w, "docker-desktop").await;
+ assert!(w.calls.lock().unwrap().is_empty());
+ terminate(&w, &distro()).await;
+ unregister(&w, &distro()).await;
+ let calls = w.calls.lock().unwrap().clone();
+ assert_eq!(calls.len(), 2);
+ assert!(calls.iter().all(|c| c.contains(DISTRO_PREFIX)));
+ }
+
+ #[tokio::test]
+ async fn a_failed_import_names_the_cause_and_cleans_up() {
+ let tmp = tempfile::tempdir().unwrap();
+ let w = Fake::new(vec![(
+ "--import",
+ out(
+ 1,
+ "",
+ "WslRegisterDistribution failed with error: 0x80370102",
+ ),
+ )]);
+ let rootfs = tmp.path().join("r.tar.gz");
+ let e = provision(&w, &distro(), tmp.path(), &rootfs, &|_, _| {})
+ .await
+ .unwrap_err()
+ .to_string();
+ assert!(e.contains("BIOS"), "{e}");
+ assert!(!tmp.path().join("disk").exists());
+ }
+
+ #[tokio::test]
+ async fn a_failed_install_unregisters_only_what_it_imported() {
+ let tmp = tempfile::tempdir().unwrap();
+ let w = Fake::new(vec![(
+ "apk add",
+ out(1, "", "fetch failed: network unreachable"),
+ )]);
+ let rootfs = tmp.path().join("r.tar.gz");
+ let e = provision(&w, &distro(), tmp.path(), &rootfs, &|_, _| {})
+ .await
+ .unwrap_err()
+ .to_string();
+ assert!(e.contains("network"), "{e}");
+ let calls = w.calls.lock().unwrap().clone();
+ assert!(
+ calls
+ .iter()
+ .any(|c| c.starts_with(&format!("--unregister {}", distro())))
+ );
+ assert!(!marker_in(tmp.path()).exists());
+ }
+
+ #[tokio::test]
+ async fn setup_configures_before_it_installs_and_marks_the_end() {
+ let tmp = tempfile::tempdir().unwrap();
+ let w = Fake::new(vec![]);
+ provision(
+ &w,
+ &distro(),
+ tmp.path(),
+ &tmp.path().join("r.tar.gz"),
+ &|_, _| {},
+ )
+ .await
+ .unwrap();
+ let calls = w.calls.lock().unwrap().clone();
+ let at = |needle: &str| calls.iter().position(|c| c.contains(needle)).unwrap();
+ assert!(at("--import") < at("wsl.conf"));
+ assert!(at("wsl.conf") < at("--terminate"));
+ assert!(at("--terminate") < at("apk add"));
+ assert!(marker_in(tmp.path()).exists());
+ }
+
+ #[test]
+ fn the_guest_configuration_isolates_the_distribution() {
+ let s = configure_script();
+ assert!(s.contains("enabled=false"));
+ assert!(s.contains("appendWindowsPath=false"));
+ let j: serde_json::Value = serde_json::from_str(&daemon_json()).unwrap();
+ assert_eq!(j["bip"], BRIDGE_CIDR);
+ assert!(!DOCKERD_SCRIPT.contains("tcp://"), "no TCP listener");
+ }
+}