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.

fix(spaces): a macOS create on a Mac nobody is at fails fast with the no-screen fix (CUA-2090) (#5756)

Francesco Bonacci788a575dc992
diff --git a/docs/content/docs/spaces/guides/add-a-computer.mdx b/docs/content/docs/spaces/guides/add-a-computer.mdx
index a4a3cbb77b..fc152480d2 100644
--- a/docs/content/docs/spaces/guides/add-a-computer.mdx
+++ b/docs/content/docs/spaces/guides/add-a-computer.mdx
@@ -273,6 +273,21 @@ setup. An existing account session is reused.
Privacy & Security. Setup can't grant these for you.
</Callout>
+<Callout type="warn">
+ A macOS Space also needs **Local Network** access, and macOS asks for it only
+ on the mini's own screen. With nobody at the screen, the create stops within
+ seconds and says so. Allow it once from the SSH session instead (Apple
+ documents this in [TN3179](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy),
+ macOS 15.5 and later). It lets every app on that Mac reach its virtual
+ computers, and it needs a restart:
+
+ ```sh skip="no-runner"
+ sudo defaults write com.apple.network.local-network AllowedEthernetLocalNetworkAddresses -array 192.168.64.0/24
+ sudo defaults write com.apple.network.local-network AllowedWiFiLocalNetworkAddresses -array 192.168.64.0/24
+ sudo shutdown -r now
+ ```
+</Callout>
+
### Create Spaces on it from your laptop
Your laptop must be [enrolled](#reach-it-from-your-other-devices) for your
diff --git a/docs/content/docs/spaces/guides/troubleshoot.mdx b/docs/content/docs/spaces/guides/troubleshoot.mdx
index fb9701844f..fda878f5c9 100644
--- a/docs/content/docs/spaces/guides/troubleshoot.mdx
+++ b/docs/content/docs/spaces/guides/troubleshoot.mdx
@@ -64,7 +64,7 @@ for the full list.
| This computer can't run virtual machines (`virtualization_unavailable`) | macOS Spaces need an Apple silicon Mac. On Linux and Windows, turn on hardware virtualization in the firmware settings. Or create a Linux container Space instead. |
| Two macOS VMs already run (`vm_limit`) | Apple allows two macOS VMs at a time on one Mac. Stop or delete one, then try again. |
| The VM started but never answered (`vm_boot_timeout`, `services_unreachable`) | The first macOS Space unpacks a large image and can run out of time. Try again: the image is already downloaded, so it is much faster. |
-| macOS blocked the connection to the new VM (`local_network`) | Open **System Settings, Privacy & Security, Local Network**, turn on Cua Spaces, then try again. |
+| macOS blocked the connection to the new VM (`local_network`) | Open **System Settings, Privacy & Security, Local Network**, turn on Cua Spaces, then try again. If nobody sits at the Mac (you use it over SSH or from another computer), macOS can't ask: run the three commands in [Add a computer](/spaces/guides/add-a-computer#over-ssh-or-tailscale) once on it. |
| "The Cua daemon isn't running. Start Cua, or run `cua daemon start`." | Open Cua Spaces, or run `cua daemon start`. |
### Creating on another computer
diff --git a/libs/cua/crates/cua-host/src/host.rs b/libs/cua/crates/cua-host/src/host.rs
index a8fd7d7f67..25ae6d5f13 100644
--- a/libs/cua/crates/cua-host/src/host.rs
+++ b/libs/cua/crates/cua-host/src/host.rs
@@ -490,9 +490,13 @@ pub fn local_network_hint(os: &str, provide_spaces: bool, driver: &Path) -> Opti
macOS asks \"Allow {short} to find devices on local networks?\" on this Mac's \
screen, click Allow; or turn on {short} in System Settings → Privacy & \
Security → Local Network. If the {cli} daemon was started from Terminal or over SSH, \
- run `{cli} daemon stop` so the host service starts it at the next create (over SSH \
- nothing can grant it). Without it, macOS Space creates fail with \"No route to \
- host\"; Linux Spaces don't need it.",
+ run `{cli} daemon stop` so the host service starts it at the next create. If nobody sits \
+ at this Mac (it is used over SSH), nothing can click Allow: run `sudo defaults write \
+ com.apple.network.local-network AllowedEthernetLocalNetworkAddresses -array \
+ 192.168.64.0/24`, the same with `AllowedWiFiLocalNetworkAddresses`, then `sudo \
+ shutdown -r now` (every app on this Mac can then reach its virtual computers). \
+ Without it, macOS Space creates fail with \"No route to host\"; Linux Spaces don't \
+ need it.",
cli = crate::cli()
),
})
diff --git a/libs/cua/crates/cua-mesh/tests/mesh.rs b/libs/cua/crates/cua-mesh/tests/mesh.rs
index 85bf1e9ddd..7bdecbab2a 100644
--- a/libs/cua/crates/cua-mesh/tests/mesh.rs
+++ b/libs/cua/crates/cua-mesh/tests/mesh.rs
@@ -13,6 +13,10 @@ use cua_mesh::{Error, Mesh, MeshConfig, Mode, NodeKind, Path, PublicKey, static_
use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
const READY: Duration = Duration::from_secs(10);
+/// Tests that restart the coordinator must not wait out the production
+/// reconnect pacing (a jittered 1s plus up to 10s of spread after a relay
+/// drop), which can exceed `READY` on a slow runner.
+const FAST_RECONNECT: u32 = 20;
async fn node(
coord: &FakeCoordinator,
@@ -46,6 +50,7 @@ async fn node_on_media_port(
cfg.stun = vec![coord.stun.to_string()];
cfg.relay_only = relay_only;
cfg.media_udp_port = media_udp_port;
+ cfg.reconnect_speedup = FAST_RECONNECT;
cfg.approved_path = Some(dir.join(format!("{name}-approved.json")));
let m = Mesh::start(cfg).await.expect("start");
m.wait_ready(READY).await.expect("ready");
@@ -456,6 +461,7 @@ async fn removed_peers_are_cut() {
);
cfg.approved_path = Some(dir.path().join("approved.json"));
cfg.pair_verifier = Some(Arc::new(|_, _, _| true));
+ cfg.reconnect_speedup = FAST_RECONNECT;
let machine = Mesh::start(cfg).await.unwrap();
machine.wait_ready(READY).await.unwrap();
serve_echo(&machine);
diff --git a/libs/cua/crates/cua-vmm/src/lib.rs b/libs/cua/crates/cua-vmm/src/lib.rs
index 213c013013..d0499c7ce7 100644
--- a/libs/cua/crates/cua-vmm/src/lib.rs
+++ b/libs/cua/crates/cua-vmm/src/lib.rs
@@ -54,6 +54,7 @@ pub mod progress;
#[cfg(feature = "qemu")]
pub mod qemu;
pub mod runtime;
+pub mod screen;
pub mod storage;
pub mod types;
#[cfg(feature = "vnc")]
diff --git a/libs/cua/crates/cua-vmm/src/probe.rs b/libs/cua/crates/cua-vmm/src/probe.rs
index e9f29edab4..e3974f2cd2 100644
--- a/libs/cua/crates/cua-vmm/src/probe.rs
+++ b/libs/cua/crates/cua-vmm/src/probe.rs
@@ -62,11 +62,23 @@ pub const APP_UNREACHABLE_GRACE: Duration = Duration::from_secs(120);
/// The grace this process gets ([`UNREACHABLE_GRACE`],
/// [`APP_UNREACHABLE_GRACE`]).
pub fn unreachable_grace() -> Duration {
- grace_for(std::env::current_exe().ok().as_deref())
+ grace_for(
+ std::env::current_exe().ok().as_deref(),
+ crate::screen::unattended(),
+ )
}
-fn grace_for(exe: Option<&std::path::Path>) -> Duration {
- if cfg!(target_os = "macos") && exe.and_then(app_bundle).is_some() {
+/// The grace on a Mac nobody is at: no prompt can be answered, so waiting
+/// longer only delays the message that says what to do.
+pub const UNATTENDED_GRACE: Duration = Duration::from_secs(5);
+
+fn grace_for(
+ exe: Option<&std::path::Path>,
+ unattended: Option<crate::screen::Unattended>,
+) -> Duration {
+ if cfg!(target_os = "macos") && unattended.is_some() {
+ UNATTENDED_GRACE
+ } else if cfg!(target_os = "macos") && exe.and_then(app_bundle).is_some() {
APP_UNREACHABLE_GRACE
} else {
UNREACHABLE_GRACE
@@ -300,7 +312,7 @@ pub fn local_network_error(kind: IssueKind, addr: &str, error: &dyn std::fmt::Di
.filter(|a| a.bundle)
.map(|a| (a.name, a.path))
});
- unreachable_error_named(addr, error, bundle)
+ unreachable_error_named(addr, error, bundle, crate::screen::unattended())
}
#[cfg(test)]
@@ -309,15 +321,22 @@ fn unreachable_error_for(
error: &dyn std::fmt::Display,
exe: Option<&std::path::Path>,
) -> VmmError {
- unreachable_error_named(addr, error, exe.and_then(app_bundle))
+ unreachable_error_named(addr, error, exe.and_then(app_bundle), None)
}
fn unreachable_error_named(
addr: &str,
error: &dyn std::fmt::Display,
bundle: Option<(String, std::path::PathBuf)>,
+ unattended: Option<crate::screen::Unattended>,
) -> VmmError {
if cfg!(target_os = "macos") {
+ if let Some(why) = unattended {
+ return VmmError::Missing {
+ what: "Local Network access".into(),
+ hint: unattended_hint(addr, error, why),
+ };
+ }
// macOS asks once per boot, on this Mac's own screen, the first time
// the app reaches the local network, and lists the app under Local
// Network only after it has asked. Someone using this Mac from
@@ -339,6 +358,7 @@ fn unreachable_error_named(
listed, quit and reopen it on this Mac (macOS asks again). Then try again"
),
};
+ let hint = format!("{hint}. {NO_SCREEN_FIX}");
VmmError::Missing {
what: "Local Network access".into(),
hint,
@@ -354,6 +374,34 @@ fn unreachable_error_named(
}
}
+/// What to do on a Mac nobody sits at (a Mac used over SSH or from another
+/// computer): Apple's documented setting (TN3179) lets the VM network
+/// through with no prompt. It applies to every app on the Mac and needs a
+/// restart.
+pub const NO_SCREEN_FIX: &str = "If nobody sits at this Mac, run these three commands on it \
+ instead (they let every app on this Mac reach its virtual computers, and the Mac restarts): \
+ sudo defaults write com.apple.network.local-network AllowedEthernetLocalNetworkAddresses \
+ -array 192.168.64.0/24 ; sudo defaults write com.apple.network.local-network \
+ AllowedWiFiLocalNetworkAddresses -array 192.168.64.0/24 ; sudo shutdown -r now";
+
+fn unattended_hint(
+ addr: &str,
+ error: &dyn std::fmt::Display,
+ why: crate::screen::Unattended,
+) -> String {
+ format!(
+ "cua cannot reach the VM at {addr} ({error}). macOS only asks to allow this on the \
+ Mac's own screen, and {}, so nobody can click Allow. Either unlock or sign in at this \
+ Mac and try again, or set it up once with no screen: run these three commands on this \
+ Mac (they let every app on it reach its virtual computers, and the Mac restarts): \
+ sudo defaults write com.apple.network.local-network AllowedEthernetLocalNetworkAddresses \
+ -array 192.168.64.0/24 ; sudo defaults write com.apple.network.local-network \
+ AllowedWiFiLocalNetworkAddresses -array 192.168.64.0/24 ; sudo shutdown -r now. Then \
+ try again",
+ why.reason()
+ )
+}
+
/// The `.app` bundle `exe` runs from: its name (without `.app`) and path.
fn app_bundle(exe: &std::path::Path) -> Option<(String, std::path::PathBuf)> {
exe.ancestors().find_map(|dir| {
@@ -608,12 +656,60 @@ mod tests {
} else {
UNREACHABLE_GRACE
};
- assert_eq!(grace_for(Some(app)), want);
+ assert_eq!(grace_for(Some(app), None), want);
assert_eq!(
- grace_for(Some(std::path::Path::new("/usr/local/bin/cua"))),
+ grace_for(Some(std::path::Path::new("/usr/local/bin/cua")), None),
UNREACHABLE_GRACE
);
- assert_eq!(grace_for(None), UNREACHABLE_GRACE);
+ assert_eq!(grace_for(None, None), UNREACHABLE_GRACE);
+ }
+
+ #[test]
+ fn a_mac_nobody_is_at_gives_up_fast_and_names_the_no_screen_fix() {
+ use crate::screen::Unattended;
+ let app = std::path::Path::new("/Applications/Cua Spaces.app/Contents/MacOS/cua");
+ let e = std::io::Error::from(std::io::ErrorKind::HostUnreachable);
+ if cfg!(target_os = "macos") {
+ assert_eq!(
+ grace_for(Some(app), Some(Unattended::Locked)),
+ UNATTENDED_GRACE
+ );
+ let err = unreachable_error_named(
+ "192.168.64.2:3211",
+ &e,
+ None,
+ Some(Unattended::NobodySignedIn),
+ );
+ let text = err.to_string();
+ assert!(
+ text.starts_with("Local Network access is not available: cua cannot reach"),
+ "{text}"
+ );
+ assert!(
+ text.contains("nobody is signed in at this Mac's screen"),
+ "{text}"
+ );
+ assert!(
+ text.contains("AllowedEthernetLocalNetworkAddresses"),
+ "{text}"
+ );
+ assert!(text.contains("192.168.64.0/24") && text.contains("shutdown -r now"));
+ assert!(!text.contains('\u{2014}'), "{text}");
+ // With someone at the screen the on-screen steps lead, and the
+ // no-screen fix follows for a Mac used from elsewhere.
+ let at_screen =
+ unreachable_error_named("192.168.64.2:3211", &e, None, None).to_string();
+ assert!(at_screen.contains("click Allow"), "{at_screen}");
+ assert!(
+ at_screen.contains("If nobody sits at this Mac"),
+ "{at_screen}"
+ );
+ } else {
+ assert_eq!(
+ grace_for(Some(app), Some(Unattended::Locked)),
+ UNREACHABLE_GRACE
+ );
+ }
}
#[test]
diff --git a/libs/cua/crates/cua-vmm/src/screen.rs b/libs/cua/crates/cua-vmm/src/screen.rs
new file mode 100644
index 0000000000..d1784093d8
--- /dev/null
+++ b/libs/cua/crates/cua-vmm/src/screen.rs
@@ -0,0 +1,100 @@
+//! Whether anyone is at this Mac's screen.
+//!
+//! macOS asks "Allow ... to find devices on local networks?" on the Mac's
+//! own screen only. On a Mac nobody is signed in at, or whose screen is
+//! locked (a Mac used over SSH or from another computer), the question
+//! can never be answered, so a macOS VM there stays unreachable for ever.
+//! Read-only: one `ioreg` call.
+
+use serde::{Deserialize, Serialize};
+
+/// Why nobody can answer a prompt on this Mac's screen.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Unattended {
+ /// Nobody is signed in at the screen (the login window, or no screen).
+ NobodySignedIn,
+ /// Someone is signed in, but the screen is locked.
+ Locked,
+}
+
+impl Unattended {
+ /// How the person would put it, to finish "so nobody can click Allow
+ /// because ...".
+ pub fn reason(self) -> &'static str {
+ match self {
+ Self::NobodySignedIn => "nobody is signed in at this Mac's screen",
+ Self::Locked => "this Mac's screen is locked",
+ }
+ }
+}
+
+/// What `ioreg -n Root -d1` says about the console (pure).
+pub fn parse_console(ioreg: &str) -> Option<Unattended> {
+ if !ioreg.contains("IOConsoleLocked") && !ioreg.contains("IOConsoleUsers") {
+ // Not the answer we expected: do not guess.
+ return None;
+ }
+ let signed_in = ioreg.contains("\"kCGSSessionOnConsoleKey\"=Yes");
+ let locked = ioreg
+ .lines()
+ .any(|l| l.contains("\"IOConsoleLocked\"") && l.contains("= Yes"));
+ if !signed_in {
+ Some(Unattended::NobodySignedIn)
+ } else if locked {
+ Some(Unattended::Locked)
+ } else {
+ None
+ }
+}
+
+/// `Some(why)` when this is a Mac nobody can answer an on-screen prompt
+/// on; `None` when someone can, on other systems, or when it cannot be
+/// told.
+pub fn unattended() -> Option<Unattended> {
+ if !cfg!(target_os = "macos") {
+ return None;
+ }
+ let out = std::process::Command::new("/usr/sbin/ioreg")
+ .args(["-n", "Root", "-d1"])
+ .output()
+ .ok()?;
+ if !out.status.success() {
+ return None;
+ }
+ parse_console(&String::from_utf8_lossy(&out.stdout))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const SIGNED_IN: &str = r#" "IOConsoleLocked" = No
+ "IOConsoleUsers" = ({"kCGSSessionOnConsoleKey"=Yes,"kCGSSessionUserNameKey"="me"})"#;
+
+ #[test]
+ fn someone_signed_in_and_unlocked_can_answer() {
+ assert_eq!(parse_console(SIGNED_IN), None);
+ }
+
+ #[test]
+ fn a_locked_screen_cannot_be_answered() {
+ let locked = SIGNED_IN.replace("\"IOConsoleLocked\" = No", "\"IOConsoleLocked\" = Yes");
+ assert_eq!(parse_console(&locked), Some(Unattended::Locked));
+ }
+
+ #[test]
+ fn no_console_user_cannot_answer() {
+ let nobody = " \"IOConsoleLocked\" = No\n \"IOConsoleUsers\" = ()";
+ assert_eq!(parse_console(nobody), Some(Unattended::NobodySignedIn));
+ // At the login window the session is not on the console.
+ let login = r#""IOConsoleUsers" = ({"kCGSSessionOnConsoleKey"=No})"#;
+ assert_eq!(parse_console(login), Some(Unattended::NobodySignedIn));
+ }
+
+ #[test]
+ fn an_unexpected_answer_is_not_guessed() {
+ assert_eq!(parse_console(""), None);
+ assert_eq!(parse_console("ioreg: command not found"), None);
+ }
+}
diff --git a/libs/cua/crates/cua-volume/src/fs.rs b/libs/cua/crates/cua-volume/src/fs.rs
index bbad0ab24a..ea42c84796 100644
--- a/libs/cua/crates/cua-volume/src/fs.rs
+++ b/libs/cua/crates/cua-volume/src/fs.rs
@@ -149,7 +149,19 @@ impl FsBackend {
}
fn new_version() -> String {
- format!("{:013}-{:08x}", now_ms(), rand::random::<u32>())
+ // Strictly increasing within the process: two writes in the same
+ // millisecond must still sort in write order, so the random suffix
+ // only keeps ids apart across processes.
+ static LAST_MS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
+ let now = now_ms();
+ let ms = LAST_MS
+ .fetch_update(
+ std::sync::atomic::Ordering::SeqCst,
+ std::sync::atomic::Ordering::SeqCst,
+ |last| Some(now.max(last + 1)),
+ )
+ .map_or(now, |last| now.max(last + 1));
+ format!("{:013}-{:08x}", ms, rand::random::<u32>())
}
fn check(cond: &Condition, current: Option<&ObjectMeta>, key: &str) -> Result<()> {