diff --git a/dashboard/src/computer.rs b/dashboard/src/computer.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2eeb4e7d18c820cca2c54f49547833a29901cb86
--- /dev/null
+++ b/dashboard/src/computer.rs
@@ -0,0 +1,141 @@
+use crate::*;
+use rmcp::{
+ ErrorData, RoleServer, ServerHandler,
+ model::{
+ CacheScope, CallToolRequestParams, CallToolResponse, CallToolResult, ContentBlock,
+ ListToolsResult, PaginatedRequestParams, ServerCapabilities, ServerConfig, Tool,
+ ToolAnnotations,
+ },
+ service::RequestContext,
+};
+
+pub async fn resources(owner: &Value) -> Result> {
+ let domains = host::call(json!({"operation":"vm.domains"})).await?;
+ Ok(array(&domains)
+ .iter()
+ .filter(|vm| {
+ vm["owner"] == owner["id"] && array(&vm["capabilities"]).iter().any(|c| c == "computer")
+ })
+ .map(|vm| json!({"id":vm["name"],"name":vm["name"],"description":vm["description"]}))
+ .collect())
+}
+
+fn permitted(grant: &Value, vm: &str, scope: &str, owner: &Value) -> Result<()> {
+ if !array(&grant["scopes"]).iter().any(|s| s == scope)
+ || !array(&grant["resources"]).iter().any(|id| id == vm)
+ || owner["owner"].as_str().is_none()
+ || owner["owner"] != grant["user"]
+ {
+ return Err(Error::new(
+ 403,
+ "This VM is outside the connection's access. Update access in MCP settings.",
+ ));
+ }
+ Ok(())
+}
+
+#[derive(Clone)]
+struct Computer;
+impl ServerHandler for Computer {
+ fn get_info(&self) -> ServerConfig {
+ ServerConfig::new(ServerCapabilities::builder().enable_tools().build())
+ }
+ async fn list_tools(
+ &self,
+ _: Option,
+ _: RequestContext,
+ ) -> std::result::Result {
+ let tools = [
+ ("computer_list", "List granted VMs with computer-use support.", json!({}), json!([])),
+ ("computer_status", "Check a VM's desktop permissions and scripting capabilities.", json!({"vm":{"type":"string"}}), json!(["vm"])),
+ ("computer_shot", "Capture the selected VM's current desktop as an image.", json!({"vm":{"type":"string"}}), json!(["vm"])),
+ ("computer_ui", "Read a bounded macOS accessibility tree, including roles, values, bounds and available actions. Use an application PID to inspect that app, or omit it for the frontmost app. Read a fresh tree before using its child paths.", json!({"vm":{"type":"string"},"pid":{"type":"integer","minimum":1}}), json!(["vm"])),
+ ("computer_exec", "Run a zsh script inside the selected Mac VM's logged-in desktop. Returns exit status, stdout/stderr (64 KiB each), and optionally a screenshot. Batch actions into one script. Use /usr/local/bin/agent-gui tree [PID], press PID 0.1.2, click X Y, key CODE [command|shift|option|control], and type - (UTF-8 stdin). Coordinates use macOS screen points; compare screenshot dimensions with display bounds before pixel input. sudo -n is available for guest setup. Timeout kills the script process group. For long-lived apps, redirect stdin/stdout/stderr before backgrounding. Never assume a timed-out command did not run.", json!({"vm":{"type":"string"},"script":{"type":"string","maxLength":65536},"timeout_ms":{"type":"integer","minimum":1,"maximum":180000,"default":60000},"screenshot":{"type":"boolean","default":true}}), json!(["vm","script"])),
+ ].into_iter().map(|(name, description, properties, required)| {
+ Tool::new(name, description, json!({"type":"object","properties":properties,"required":required,"additionalProperties":false}).as_object().unwrap().clone())
+ .with_annotations(ToolAnnotations::new().read_only(name != "computer_exec"))
+ }).collect();
+ Ok(ListToolsResult {
+ tools,
+ ttl_ms: Some(0),
+ cache_scope: Some(CacheScope::Private),
+ ..Default::default()
+ })
+ }
+ async fn call_tool(
+ &self,
+ request: CallToolRequestParams,
+ context: RequestContext,
+ ) -> std::result::Result {
+ let result: Result = async {
+ let grant = &context.extensions.get::()
+ .and_then(|p| p.extensions.get::())
+ .ok_or_else(|| Error::new(401, "This connection expired. Connect again."))?.0;
+ let mut arguments = request.arguments.unwrap_or_default();
+ if request.name == "computer_list" {
+ if !arguments.is_empty() { return Err(Error::new(400, "This tool takes no arguments.")); }
+ return Ok(json!({"computers":resources(&json!({"id":grant["user"]})).await?.into_iter()
+ .filter(|vm| array(&grant["resources"]).iter().any(|id| id == &vm["id"])).collect::>()}));
+ }
+ let vm = arguments.remove("vm").and_then(|v| v.as_str().map(str::to_owned))
+ .filter(|s| !s.is_empty() && s.len() <= 63)
+ .ok_or_else(|| Error::new(400, "Choose a granted VM."))?;
+ if !array(&grant["resources"]).iter().any(|id| id == &vm) {
+ return Err(Error::new(403, "Choose a VM granted to this connection."));
+ }
+ let scope = if request.name == "computer_exec" { "computer:control" } else { "computer:read" };
+ let owner = host::call(json!({"operation":"vm.owner","payload":{"name":vm}})).await?;
+ permitted(grant, &vm, scope, &owner)?;
+ let operation = match request.name.as_ref() {
+ "computer_status" => json!({"action":"status"}),
+ "computer_shot" => json!({"action":"shot"}),
+ "computer_ui" => json!({"action":"ui","pid":arguments.remove("pid")}),
+ "computer_exec" => json!({"action":"exec", "script":arguments.remove("script"),
+ "timeout_ms":arguments.remove("timeout_ms").unwrap_or(json!(60000)),
+ "screenshot":arguments.remove("screenshot").unwrap_or(json!(true))}),
+ _ => return Err(Error::new(404, "No tool with that name.")),
+ };
+ if !arguments.is_empty() { return Err(Error::new(400, "Use the fields listed for this tool.")); }
+ host::call(json!({"operation":"vm.computer","payload":{"name":vm,"request":operation}})).await
+ }.await;
+ Ok(match result {
+ Ok(mut value) => {
+ let png = value.as_object_mut().and_then(|v| v.remove("png"));
+ let mut content = vec![ContentBlock::text(value.to_string())];
+ if let Some(png) = png.and_then(|v| v.as_str().map(str::to_owned)) {
+ content.push(ContentBlock::image(png, "image/png"));
+ }
+ CallToolResult::success(content)
+ }
+ Err(error) => CallToolResult::error(vec![ContentBlock::text(error.message)]),
+ }
+ .into())
+ }
+}
+
+pub fn router(app: Arc) -> Router {
+ mcp::router(app, "computer", || Ok(Computer))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ #[test]
+ fn control_requires_the_current_owner_selected_vm_and_scope() {
+ let grant = json!({"user":"clover","scopes":["computer:read"],"resources":["m3-devbox"]});
+ let owner = json!({"owner":"clover","ownerOnly":true});
+ assert!(permitted(&grant, "m3-devbox", "computer:read", &owner).is_ok());
+ assert!(permitted(&grant, "m3-devbox", "computer:control", &owner).is_err());
+ assert!(permitted(&grant, "other", "computer:read", &owner).is_err());
+ assert!(
+ permitted(
+ &grant,
+ "m3-devbox",
+ "computer:read",
+ &json!({"owner":"another-user"})
+ )
+ .is_err()
+ );
+ assert!(permitted(&grant, "m3-devbox", "computer:read", &Value::Null).is_err());
+ }
+}
diff --git a/dashboard/src/host.rs b/dashboard/src/host.rs
index 15b310924166ff3a833d46112e15b9994405f082..b1ecd8385d569ceec4a822337aa7019fb2d66336 100644
--- a/dashboard/src/host.rs
+++ b/dashboard/src/host.rs
@@ -34,7 +34,7 @@ pub async fn open(request: Value) -> Result<(Value, tokio::net::UnixStream)> {
Some("vm.create" | "vm.media" | "vm.preset")
) {
910
- } else if request["operation"] == "vm.act" {
+ } else if matches!(request["operation"].as_str(), Some("vm.act" | "vm.computer")) {
240
} else if request["operation"] == "copyparty.manage" {
310
diff --git a/dashboard/src/main.rs b/dashboard/src/main.rs
index 662cb3cf127fbed05d4d520a9d432904cf70d979..8fa2d29c28d3041b60ff81ff1fbf1afe74e6853f 100644
--- a/dashboard/src/main.rs
+++ b/dashboard/src/main.rs
@@ -4,6 +4,7 @@ mod auth;
mod atproto;
mod identity;
mod cache;
+mod computer;
mod core;
mod deploys;
mod files;
@@ -593,6 +594,7 @@ async fn main() -> std::result::Result<(), Box> {
.nest_service("/assets", ServeDir::new(format!("{dist}/assets")))
.with_state(app.clone())
.merge(observability::router(app.clone()))
+ .merge(computer::router(app.clone()))
.merge(shale::router(app.clone()))
.merge(relay::router(app.clone()))
.fallback_service(
diff --git a/dashboard/src/mcp.rs b/dashboard/src/mcp.rs
index c7e08e1d545ec9409dfbeb90de29e72e488e39ef..17665794e073f3d88d99a9baab72a3540b0b688c 100644
--- a/dashboard/src/mcp.rs
+++ b/dashboard/src/mcp.rs
@@ -8,6 +8,7 @@ use sha2::{Digest, Sha256};
use std::os::unix::fs::{DirBuilderExt, PermissionsExt};
const CATALOGS: &[(&str, &str, &[&str])] = &[
+ ("computer", "Computers", &["computer:read", "computer:control", "offline_access"]),
(
"observability",
"Logs and traces",
@@ -499,6 +500,8 @@ pub(crate) fn active_owner(app: &App, grant: &Value) -> Result {
};
Ok(profile["enabled"] == true
&& !guest::is_guest(&profile)
+ && (grant["resource"] != app.mcp.resource("computer")
+ || array(&profile["groups"]).iter().any(|role| matches!(role["name"].as_str(), Some("vm" | "infra-admin"))))
&& (grant["resource"] != app.mcp.resource("observability")
|| array(&profile["groups"])
.iter()
@@ -794,6 +797,10 @@ pub async fn manage(
}
Err(error) => return Err(error),
}
+ } else if consent_resource == app.mcp.resource("computer")
+ && array(&me["sections"]).iter().any(|s| s == "vms")
+ {
+ computer::resources(&owner).await?
} else if consent_resource == app.mcp.resource("observability")
&& array(&me["sections"]).iter().any(|s| s == "admin")
&& array(&owner["groups"])
@@ -1062,7 +1069,7 @@ mod tests {
json!({"client_name":"Codex","redirect_uris":[uri]})).unwrap()).await;
let mut request = fields(json!({"response_type":"code","client_id":client["client_id"],"state":"fixture-state",
"code_challenge":"AdJpfUsRa6XMg54f2khmgo2onMwePN3vmU9DOOoaTzo","code_challenge_method":"S256",
- "redirect_uri":uri,"scope":"observability:read offline_access sessions:read sessions:write shale:read shale:write"}));
+ "redirect_uri":uri,"scope":"observability:read offline_access sessions:read sessions:write shale:read shale:write computer:read computer:control"}));
for (catalog, _, allowed) in CATALOGS {
request.insert("resource".into(), fixture.store.resource(catalog));
let response = fixture.store.oauth("authorize", &Method::GET, &request, &HeaderMap::new(), Value::Null).unwrap();
diff --git a/dashboard/web/pages/MCP.tsx b/dashboard/web/pages/MCP.tsx
index afa905376f3ce1060f125feff143397a009e1e1c..958df2f52c675173efda68c91d9a8ca5f7cb2fbb 100644
--- a/dashboard/web/pages/MCP.tsx
+++ b/dashboard/web/pages/MCP.tsx
@@ -16,6 +16,7 @@ import type { Access, Catalog } from "../types/mcp.ts";
import "./MCP.css";
const descriptions: Record = {
+ computer: "Inspect and control selected virtual machines, run commands, and install guest software.",
shale: "Read and edit issues across your Shale repositories.",
agents: "Connect to Codex and Claude Code on your machines.",
observability: "Read logs and traces from your services.",
@@ -148,9 +149,16 @@ export function MCP(props: { me: Me }) {
Connected clients
No clients connected. Add the connector URL to your AI client to get started.
}>
- {data().catalog === "shale" ? "Grant access to Shale issues." : data().catalog === "agents" ? "Grant access to your local agents." : "Grant access to logs and traces."}
+ {data().catalog === "computer" ? "Grant access to selected virtual machines." : data().catalog === "shale" ? "Grant access to Shale issues." : data().catalog === "agents" ? "Grant access to your local agents." : "Grant access to logs and traces."}
Requested access
-
{data().catalog === "shale" ? "Read issues and comments" : data().catalog === "agents" ? "Read saved chats" : "Read logs and traces"}
+
{data().catalog === "computer" ? "Read VM status, screenshots, and application controls" : data().catalog === "shale" ? "Read issues and comments" : data().catalog === "agents" ? "Read saved chats" : "Read logs and traces"}
+
Control the desktop, run commands, and install software inside the selected VMs
Create issues, comment, and edit issue titles and status
Send messages, start chats, and interrupt turns
Stay connected without signing in again
diff --git a/dashboard/web/types/mcp.ts b/dashboard/web/types/mcp.ts
index c10206892eda47bcdbfeac54cba0c558b286cb1e..9cb101300c08af0fed73614f87ace48b4edc99cb 100644
--- a/dashboard/web/types/mcp.ts
+++ b/dashboard/web/types/mcp.ts
@@ -1,4 +1,4 @@
-export type Catalog = "shale" | "agents" | "observability";
+export type Catalog = "shale" | "agents" | "observability" | "computer";
export type Access = "all" | string[];
export type Resources = { id: string; name: string; description?: string }[];
diff --git a/tools/dashboard-host.py b/tools/dashboard-host.py
index f50919b50bb577ea871e2f555c390742cad58e76..790026b788ed8a4ed8884910fe9da1230ec7b6d6 100644
--- a/tools/dashboard-host.py
+++ b/tools/dashboard-host.py
@@ -186,9 +186,9 @@ class Host:
vms.validate(action, payload)
except ValueError as error:
raise Rejected(str(error)) from error
- if action == "clipboard":
+ if action in {"clipboard", "computer"}:
if not vms.mac_vms.CONFIG or payload["name"] != vms.mac_vms.CONFIG["name"]:
- raise Rejected("Use this VM's screen clipboard.")
+ raise Rejected("This VM does not support this guest operation.")
try:
return vms.mac_vms.handle(action, payload)
except ValueError as error:
diff --git a/tools/dashboard-stage-test.py b/tools/dashboard-stage-test.py
index 5c1ebacd02dcaf347e31d35a6aa03b93c1a7d6d2..421f055846df93eb4e63cdaca138faa8271b11b9 100644
--- a/tools/dashboard-stage-test.py
+++ b/tools/dashboard-stage-test.py
@@ -34,7 +34,7 @@ class PreviewBoundary(unittest.TestCase):
return json.loads(sent[4:]), host
def test_denies_host_mutations_and_vm_streams_before_dispatch(self):
- for operation in ["vm.create", "vm.start", "vm.console", "vm.serial", "vm.guest", "vm.upload", "storage.destroy", "deploy.start", "deploy.secret.get", "shale.write", "copyparty.manage", []]:
+ for operation in ["vm.create", "vm.start", "vm.console", "vm.serial", "vm.guest", "vm.upload", "vm.computer", "vm.owner", "storage.destroy", "deploy.start", "deploy.secret.get", "shale.write", "copyparty.manage", []]:
with self.subTest(operation=operation):
response, host = self.call({"operation": operation})
self.assertEqual(response["status"], 403)
@@ -53,6 +53,16 @@ class PreviewBoundary(unittest.TestCase):
with self.assertRaisesRegex(ValueError, "invalid dashboard stage"):
stage.metadata(identity)
+ def test_attached_computer_cannot_target_another_vm(self):
+ host = stage.PreviewHost({"clone": "globe/staging/fixture", "computer": "mac-fixture"})
+ with patch.object(boundary.Host, "handle", return_value={"ok": True}) as call:
+ for operation in ["vm.computer", "vm.owner"]:
+ with self.assertRaises(boundary.dashboard_runs.Error):
+ host.handle({"operation": operation, "payload": {"name": "personal"}})
+ call.assert_not_called()
+ self.assertEqual(host.handle({"operation": operation, "payload": {"name": "mac-fixture"}}), {"ok": True})
+ call.reset_mock()
+
def test_file_operations_cannot_name_production_or_account_dataset(self):
dataset = "globe/staging/dashboard-preview-12345678"
host = stage.PreviewHost({"clone": dataset})
diff --git a/tools/dashboard-stage.py b/tools/dashboard-stage.py
index dbf9206b346d5d3419e54e4619c43cf53ac36887..67637b573a137944a914f625f13555e25ca4d9e8 100644
--- a/tools/dashboard-stage.py
+++ b/tools/dashboard-stage.py
@@ -9,6 +9,7 @@ import secrets
import shlex
import shutil
import socket
+import sqlite3
import subprocess
import sys
import threading
@@ -35,6 +36,10 @@ class PreviewHost(boundary.Host):
def handle(self, request):
operation = request.get("operation") if isinstance(request, dict) else None
+ if operation in {"vm.computer", "vm.owner"}:
+ payload = request.get("payload")
+ if not self.stage.get("computer") or not isinstance(payload, dict) or payload.get("name") != self.stage["computer"]:
+ raise boundary.dashboard_runs.Error(403, "Choose the VM explicitly attached to this preview.")
if operation == "shale.access":
service = request.get("service", "")
if not re.fullmatch(r"shale-preview-[0-9a-f]{8}", service):
@@ -86,11 +91,12 @@ def serve(stage):
if not slots.acquire(blocking=False):
connection.close()
continue
- work = workers.submit(boundary.serve_connection, connection, host, saved["uid"], OPERATIONS)
+ operations = OPERATIONS | {"vm.computer", "vm.owner"} if saved.get("computer") else OPERATIONS
+ work = workers.submit(boundary.serve_connection, connection, host, saved["uid"], operations)
work.add_done_callback(lambda _: slots.release())
-def stage():
+def stage(computer=None):
snowglobe.token()
site = json.loads(snowglobe.command("pkl", "eval", "-f", "json", str(snowglobe.REPO / "config/site.pkl"), capture=True).stdout)
site["hostRoot"] = str(Path(site["root"]) / "prod/dashboard")
@@ -107,6 +113,16 @@ def stage():
saved = {"sourceId": "dashboard", "tasks": ["app"], "inputs": {}, "mount": str(root),
"clone": site["pool"] + "/staging/" + identity, "uid": snowglobe.identity("dashboard"),
"stageIsolation": "fresh"} if created else metadata(identity)
+ if computer:
+ saved["computer"] = computer
+ host_environment = shlex.split(snowglobe.command("systemctl", "show", "snowglobe-host", "--property=Environment", "--value", capture=True).stdout)
+ host_path = next(value for value in host_environment if value.startswith("PATH="))
+ mac = None
+ if saved.get("computer"):
+ configured = next((value.partition("=")[2] for value in host_environment if value.startswith("SNOWGLOBE_MAC_VM=")), "null")
+ mac = json.loads(configured)
+ if not mac or mac["name"] != saved["computer"]:
+ raise ValueError("Choose the configured managed Mac VM for this preview.")
nix = ["nix", "--extra-experimental-features", "nix-command flakes"]
package = "path:" + str(snowglobe.REPO) + "#dashboard-image"
image = subprocess.run([*nix, "eval", "--raw", package, "--apply", 'image: "${image.imageName}:${image.imageTag}"'],
@@ -166,13 +182,20 @@ def stage():
*["--env=" + key + "=" + value for key, value in env.items()], image, "--preview-account", capture=True)
snowglobe.write_private(root / "access.json", imported.stdout)
runtime = "/run/snowglobe-preview/" + identity
- host_environment = snowglobe.command("systemctl", "show", "snowglobe-host", "--property=Environment", "--value", capture=True).stdout
- host_path = next(value for value in shlex.split(host_environment) if value.startswith("PATH="))
+ computer_environment = []
+ if mac:
+ with sqlite3.connect(f"file:{root / 'data/accounts.sqlite'}?mode=ro", uri=True) as accounts:
+ owner = accounts.execute("SELECT id FROM users WHERE username='preview'").fetchone()
+ if not owner:
+ raise ValueError("The preview account is unavailable.")
+ mac["owner"] = owner[0]
+ computer_environment.append("--setenv=SNOWGLOBE_MAC_VM=" + json.dumps(mac))
host_python = snowglobe.command(*nix, "build", "--no-link", "--print-out-paths", "path:" + str(snowglobe.REPO) + "#host-python", capture=True).stdout.strip()
subprocess.run(["systemctl", "stop", "snowglobe-preview-" + identity], capture_output=True)
snowglobe.command("systemd-run", "--collect", "--quiet", "--unit=snowglobe-preview-" + identity,
"--property=Restart=on-failure", "--property=MemoryMax=256M", "--property=TasksMax=32",
"--setenv=" + host_path, "--setenv=SNOWGLOBE_DOMAIN=" + site["domain"],
+ *computer_environment,
host_python + "/bin/python3", str(Path(__file__).resolve()), "--serve", identity)
for _ in range(100):
if Path(runtime, "host.sock").exists():
diff --git a/tools/deploy.py b/tools/deploy.py
index 86a938988162a4e630bcc1e9ff74eb2a974cbbc1..d8f6738814ce6f1829f9c79a8d64a657198fe3c8 100644
--- a/tools/deploy.py
+++ b/tools/deploy.py
@@ -163,6 +163,7 @@ def upload(main=False):
def main():
parser = argparse.ArgumentParser(description="Preview working changes and deploy main")
parser.add_argument("mode", choices=["stage", "publish", "prod", "rollback", "history", "backups", "data-restore", "bootstrap", "allocate", "destroy", "secrets"])
+ parser.add_argument("--computer", help="Give a dashboard preview access to this managed Mac VM")
parser.add_argument("target", nargs="?")
parser.add_argument("--env", action="append", default=[])
parser.add_argument("--file", type=Path)
@@ -170,6 +171,8 @@ def main():
parser.add_argument("--backup")
parser.add_argument("--discard-writes", action="store_true")
args = parser.parse_args()
+ if args.computer and (args.mode != "stage" or args.target != "dashboard" or not NAME.fullmatch(args.computer)):
+ parser.error("--computer requires stage dashboard and a VM name")
if args.mode in {"stage", "allocate", "destroy", "secrets", "data-restore"} and (not args.target or not NAME.fullmatch(args.target)):
parser.error(f"{args.mode} requires a service or stage ID")
if args.mode == "rollback" and args.target and not RELEASE_ID.fullmatch(args.target):
@@ -202,6 +205,8 @@ def main():
if args.mode == "stage":
release = upload()
overrides = "".join(f" --env {shlex.quote(value)}" for value in args.env)
+ if args.computer:
+ overrides += " --computer " + shlex.quote(args.computer)
run_logged("stage", args.target, f"python3 {REMOTE}/releases/{release}/tools/snowglobe.py stage {args.target}{overrides}")
elif args.mode == "secrets":
release = upload()
diff --git a/tools/install-mac-computer.py b/tools/install-mac-computer.py
new file mode 100644
index 0000000000000000000000000000000000000000..b8a5f72cbe31336950f7275914fe4f257d1aac8b
--- /dev/null
+++ b/tools/install-mac-computer.py
@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Install computer-use support in the existing managed Mac guest and bridge."""
+from importlib import import_module
+import json
+import os
+from pathlib import Path
+import tempfile
+
+vm = import_module("mac-agent-vm")
+root = Path(__file__).resolve().parent
+identity = vm.tart("exec", vm.NAME, "/bin/hostname", capture_output=True, text=True, timeout=10).stdout.strip()
+print("Installing guest tools in " + identity, flush=True)
+source = {name: (root / name).read_text() for name in ["mac-computer.py", "mac-agent-gui.swift"]}
+vm.tart("exec", "-i", vm.NAME, "/usr/bin/python3", "-c", '''
+import json, pathlib, subprocess, sys, tempfile
+files = json.load(sys.stdin)
+with tempfile.TemporaryDirectory(prefix="snowglobe-computer-install-") as temporary:
+ root = pathlib.Path(temporary)
+ for name, content in files.items():
+ (root / name).write_text(content)
+ subprocess.run(["/usr/bin/swiftc", "-O", str(root / "mac-agent-gui.swift"), "-o", str(root / "agent-gui")], check=True)
+ subprocess.run(["sudo", "-n", "mkdir", "-p", "/usr/local/libexec"], check=True)
+ for source, destination in [("mac-computer.py", "/usr/local/libexec/snowglobe-computer.py"), ("agent-gui", "/usr/local/bin/agent-gui")]:
+ subprocess.run(["sudo", "-n", "install", "-m", "755", str(root / source), destination], check=True)
+''', input=json.dumps(source).encode(), timeout=180)
+for name in ["mac-agent-vm.py", "mac-vm-bridge.py"]:
+ target = vm.ROOT / "runtime/control" / name
+ with tempfile.NamedTemporaryFile(dir=target.parent, delete=False) as outgoing:
+ pending = Path(outgoing.name)
+ outgoing.write((root / name).read_bytes())
+ try:
+ pending.chmod(target.stat().st_mode & 0o777)
+ os.replace(pending, target)
+ finally:
+ pending.unlink(missing_ok=True)
+result = vm.tart("exec", "-i", vm.NAME, "/usr/bin/python3", "/usr/local/libexec/snowglobe-computer.py",
+ input=b'{"action":"status"}', capture_output=True, timeout=15)
+value = json.loads(result.stdout)
+if not all(value.get("permissions", {}).get(name) for name in ["accessibility", "screenCapture", "postEvent"]):
+ raise SystemExit("The guest needs computer-use permissions; check its System Settings.")
+print(json.dumps(value))
diff --git a/tools/mac-agent-gui.swift b/tools/mac-agent-gui.swift
index 9744c8b0859c85c76de4df12b28c1c7c83ced4bf..0cbff14783e64236745de2708619c55c23140dc9 100644
--- a/tools/mac-agent-gui.swift
+++ b/tools/mac-agent-gui.swift
@@ -81,7 +81,10 @@ case "screenshot":
else { fail("Could not create the output PNG.") }
CGImageDestinationAddImage(destination, image, nil)
guard CGImageDestinationFinalize(destination) else { fail("Could not write the output PNG.") }
- output(["width": image.width, "height": image.height, "path": arguments[1]])
+ let bounds = CGDisplayBounds(CGMainDisplayID())
+ output(["width": image.width, "height": image.height, "path": arguments[1],
+ "bounds": [bounds.origin.x, bounds.origin.y, bounds.width, bounds.height],
+ "scale": [Double(image.width) / bounds.width, Double(image.height) / bounds.height]])
case "tree", "press":
guard AXIsProcessTrusted() else { fail("Accessibility permission is required.") }
let app: AXUIElement
diff --git a/tools/mac-agent-vm.md b/tools/mac-agent-vm.md
index 022b4dbe743eae19b3bddb5dd10bf1a40ebe4553..1a56fecbf59dc2a5384a8d31b74bf2476aeb06a7 100644
--- a/tools/mac-agent-vm.md
+++ b/tools/mac-agent-vm.md
@@ -78,9 +78,10 @@ Snow Globe connects to the Mac's existing SSH service with a dedicated key at
`/var/lib/snowglobe/mac-vm/ssh_key` and a pinned host key in the adjacent
`known_hosts`. Both are root-only. The corresponding Mac `authorized_keys`
entry uses `restrict,command=` to invoke `mac-vm-bridge.py`; it grants no shell,
-forwarding, PTY, arbitrary VM selection, or arbitrary guest command. Deploy the
-bridge and `mac-agent-vm.py` together under the VM home's `runtime/control` and
-keep that forced command pointed there, independent of an agent session.
+forwarding, PTY, or arbitrary VM selection. Its computer operation runs commands
+inside the fixed guest. Deploy the bridge and `mac-agent-vm.py` together under
+the VM home's `runtime/control` and keep that forced command pointed there,
+independent of an agent session.
The existing host sshd provides supervision. Each console connection creates
a fresh, pinned guest SSH tunnel, authenticates Screen Sharing on the Mac,
@@ -102,6 +103,36 @@ video stream without reconnecting. A deliberately closed viewer connection
also recovered without restarting the guest. The idle legacy tailnet relay
was retired; the actively used loopback recovery console was preserved.
+## Computer MCP
+
+The `computer` MCP catalog uses the dashboard's OAuth flow. Grants select VMs
+owned by the account; every call rechecks the current owner, selected VM, and
+`computer:read` or `computer:control` scope. Infrastructure administrators do
+not bypass ownership. Read access provides status, screenshots, and AX trees;
+control also runs bounded zsh scripts with `agent-gui` input primitives and
+optional screenshots. The guest's passwordless sudo permits software setup.
+This managed devbox remains persistent.
+
+Install from this Mac while the guest is running:
+
+```sh
+python3 tools/install-mac-computer.py
+python3 tools/deploy.py stage dashboard --computer m3-devbox
+```
+
+The installer compiles the GUI helper in the guest, installs the stdin/stdout
+worker, refreshes the restricted host bridge, and checks permissions. The
+worker serializes operations, caps command output, and kills the command's
+process group on timeout. Commands deliberately detached into another session
+can outlive a call; this is a development shell, not a process sandbox.
+Screenshot pixels include display bounds and scale for point-based input.
+
+Dashboard previews have no computer access by default. `--computer` explicitly
+attaches the real managed guest to the preview account; subsequent staging
+updates retain that attachment. Only the preview host's configuration remaps
+ownership. Its credentials grant access to the live guest, so keep them private.
+Destroying the preview removes its access. Production ownership is unchanged.
+
## Guest access
`~/.local/bin/code-vm` links to the installed `runtime/control/code-vm` under
diff --git a/tools/mac-computer-test.py b/tools/mac-computer-test.py
new file mode 100644
index 0000000000000000000000000000000000000000..565633939c6a9e027d2e151ef7f828cbef68ef3b
--- /dev/null
+++ b/tools/mac-computer-test.py
@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Disposable command, timeout, output-bound and protocol tests."""
+from importlib import import_module
+import os
+import signal
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+worker = import_module("mac-computer")
+bridge = import_module("mac-vm-bridge")
+
+
+class ComputerTests(unittest.TestCase):
+ def run_script(self, script, timeout=3000):
+ return worker.execute({"action": "exec", "script": script, "timeout_ms": timeout, "screenshot": False})
+
+ def test_commands_preserve_unicode_exit_status_and_limit_output(self):
+ result = self.run_script("printf 'Clover 🦊 日本語'; printf 'diagnostic' >&2; exit 7")
+ self.assertEqual(result, {"exit": 7, "stdout": "Clover 🦊 日本語", "stderr": "diagnostic"})
+ result = self.run_script("/usr/bin/python3 -c 'print(\"x\" * 200000)'")
+ self.assertEqual(len(result["stdout"]), 65536)
+ self.assertEqual(result["truncated"], ["stdout"])
+ self.assertEqual(result["exit"], 0)
+
+ def test_timeout_kills_the_script_group(self):
+ killpg = os.killpg
+ def cleanup(args, **kwargs):
+ self.assertEqual(args[:5], ["/usr/bin/sudo", "-n", "/bin/kill", "-KILL", "--"])
+ killpg(-int(args[-1]), signal.SIGKILL)
+ return subprocess.CompletedProcess(args, 0)
+ with patch.object(worker.subprocess, "run", side_effect=cleanup), \
+ patch.object(worker.os, "killpg", side_effect=PermissionError):
+ result = self.run_script("sleep 30 &\nprintf '%s' $!\nwait", 250)
+ self.assertTrue(result["timed_out"])
+ self.assertEqual(result["exit"], -signal.SIGKILL)
+ pid = int(result["stdout"])
+ state = subprocess.run(["ps", "-p", str(pid), "-o", "stat="], capture_output=True, text=True).stdout.strip()
+ self.assertTrue(not state or state.startswith("Z"), state)
+
+ def test_delayed_child_output_is_collected(self):
+ result = self.run_script("(sleep .3; printf 'late child') &")
+ self.assertEqual(result, {"exit": 0, "stdout": "late child", "stderr": ""})
+
+ def test_capture_failure_preserves_command_result(self):
+ for failure in [subprocess.TimeoutExpired("capture", 15), OSError("capture failed")]:
+ with patch.object(worker.subprocess, "run", side_effect=failure):
+ result = worker.execute({"action": "exec", "script": "printf completed; exit 7", "timeout_ms": 3000, "screenshot": True})
+ self.assertEqual(result["exit"], 7)
+ self.assertEqual(result["stdout"], "completed")
+ self.assertIn("capture_error", result)
+
+ def test_invalid_requests_never_run_commands(self):
+ requests = [[], {"action": []}, {"action": "status", "command": "id"},
+ {"action": "ui", "pid": True}, {"action": "ui", "pid": -1}]
+ for field, value in [("script", ""), ("script", "a" * 65537), ("timeout_ms", True),
+ ("timeout_ms", 180001), ("screenshot", "yes")]:
+ requests.append({"action": "exec", "script": "id", "timeout_ms": 1000, "screenshot": False, field: value})
+ with patch.object(worker.subprocess, "Popen") as start:
+ for request in requests:
+ with self.subTest(request=str(request)[:100]), self.assertRaises(ValueError):
+ worker.execute(request)
+ start.assert_not_called()
+
+ def test_bridge_bounds_guest_output_and_rejects_nonobjects(self):
+ with tempfile.TemporaryDirectory() as directory:
+ tart = Path(directory) / "tart"
+ for output, message in [("print('x' * (17 * 1024 * 1024))", "too large"), ("print('[]')", "incomplete")]:
+ tart.write_text("#!/usr/bin/python3\n" + output + "\n")
+ tart.chmod(0o700)
+ with patch.object(bridge.vm, "TART", tart), self.assertRaisesRegex(ValueError, message):
+ bridge.computer({"action": "status"})
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tools/mac-computer.py b/tools/mac-computer.py
new file mode 100644
index 0000000000000000000000000000000000000000..2bc8e0d3aed4af777d452f36a3921f28023a0376
--- /dev/null
+++ b/tools/mac-computer.py
@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Computer operations in the logged-in Mac guest, over stdin/stdout."""
+import base64
+import fcntl
+import json
+import os
+from pathlib import Path
+import selectors
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+
+GUI = "/usr/local/bin/agent-gui"
+
+
+def execute(request):
+ if not isinstance(request, dict):
+ raise ValueError("Send a computer operation.")
+ action = request.get("action")
+ fields = {"status": {"action"}, "shot": {"action"}, "ui": {"action", "pid"},
+ "exec": {"action", "script", "timeout_ms", "screenshot"}}
+ if not isinstance(action, str) or action not in fields or set(request) != fields[action]:
+ raise ValueError("Use the fields listed for this computer operation.")
+ if action == "ui" and (request["pid"] is not None and (type(request["pid"]) is not int or request["pid"] <= 0)):
+ raise ValueError("Choose a positive application PID, or omit it for the active app.")
+ if action == "exec":
+ if not isinstance(request["script"], str) or not 1 <= len(request["script"].encode()) <= 65536:
+ raise ValueError("Provide a script of at most 64 KiB.")
+ if type(request["timeout_ms"]) is not int or not 1 <= request["timeout_ms"] <= 180000:
+ raise ValueError("Choose a timeout between 1 and 180000 milliseconds.")
+ if type(request["screenshot"]) is not bool:
+ raise ValueError("Choose whether to return a screenshot.")
+ if action == "status":
+ result = subprocess.run([GUI, "status"], capture_output=True, timeout=10, check=True)
+ return {"permissions": json.loads(result.stdout), "hostname": os.uname().nodename,
+ "platform": "macos", "script": "zsh", "max_timeout_ms": 180000}
+ if action == "ui":
+ args = [GUI, "tree"] + ([] if request["pid"] is None else [str(request["pid"])])
+ result = subprocess.run(args, capture_output=True, timeout=15, check=True)
+ if len(result.stdout) > 2 * 1024 * 1024:
+ raise ValueError("The UI tree is too large. Select an application PID.")
+ return {"tree": json.loads(result.stdout)}
+ with tempfile.TemporaryDirectory(prefix="snowglobe-computer-") as directory:
+ reply = {}
+ if action == "exec":
+ script = Path(directory) / "script"
+ script.write_text(request["script"])
+ with script.open("rb") as source, selectors.DefaultSelector() as selector:
+ process = subprocess.Popen(["/bin/zsh", "-s"], stdin=source,
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, start_new_session=True)
+ streams = {"stdout": bytearray(), "stderr": bytearray()}
+ truncated = []
+ for name in streams:
+ stream = getattr(process, name)
+ os.set_blocking(stream.fileno(), False)
+ selector.register(stream, selectors.EVENT_READ, name)
+ deadline = time.monotonic() + request["timeout_ms"] / 1000
+ try:
+ while True:
+ if time.monotonic() >= deadline:
+ reply["timed_out"] = True
+ break
+ events = selector.select(min(.1, max(0, deadline - time.monotonic())))
+ for key, _ in events:
+ data = os.read(key.fd, 65536)
+ if not data:
+ selector.unregister(key.fileobj)
+ continue
+ output = streams[key.data]
+ remaining = 65536 - len(output)
+ output.extend(data[:remaining])
+ if len(data) > remaining and key.data not in truncated:
+ truncated.append(key.data)
+ if process.poll() is not None and not selector.get_map():
+ break
+ finally:
+ if process.poll() is None or reply.get("timed_out"):
+ try:
+ cleanup = subprocess.run(["/usr/bin/sudo", "-n", "/bin/kill", "-KILL", "--", "-" + str(process.pid)],
+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=5)
+ if cleanup.returncode:
+ reply["cleanup_error"] = "Privileged cleanup failed. Check for remaining child processes."
+ except (OSError, subprocess.SubprocessError):
+ reply["cleanup_error"] = "Privileged cleanup failed. Check for remaining child processes."
+ try:
+ os.killpg(process.pid, signal.SIGKILL)
+ except (ProcessLookupError, PermissionError):
+ pass
+ process.wait()
+ process.stdout.close()
+ process.stderr.close()
+ reply.update(exit=process.returncode, **{k: bytes(v).decode("utf-8", "replace") for k, v in streams.items()})
+ if truncated:
+ reply["truncated"] = truncated
+ if action == "shot" or request.get("screenshot"):
+ shot = Path(directory) / "screen.png"
+ try:
+ result = subprocess.run([GUI, "screenshot", str(shot)], capture_output=True, timeout=15, check=True)
+ if shot.stat().st_size > 8 * 1024 * 1024:
+ reply["capture_error"] = "The screenshot exceeds 8 MiB. Reduce the guest display resolution."
+ else:
+ reply.update(json.loads(result.stdout))
+ reply.pop("path", None)
+ reply["png"] = base64.b64encode(shot.read_bytes()).decode("ascii")
+ except subprocess.TimeoutExpired:
+ reply["capture_error"] = "Screen capture timed out. Check the guest's screen recording permission."
+ except (OSError, ValueError, subprocess.SubprocessError):
+ reply["capture_error"] = "Screen capture failed. Check the guest's screen recording permission."
+ return reply
+
+
+def main():
+ raw = sys.stdin.buffer.read(524289)
+ if len(raw) > 524288:
+ raise ValueError("The computer request is too large.")
+ request = json.loads(raw)
+ lock_path = Path.home() / "Library/Caches/net.paperclover.computer.lock"
+ descriptor = os.open(lock_path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+ with os.fdopen(descriptor, "w") as lock:
+ try:
+ fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ except BlockingIOError:
+ raise ValueError("Another computer operation is running. Wait for it to finish.")
+ return execute(request)
+
+
+if __name__ == "__main__":
+ try:
+ print(json.dumps(main(), ensure_ascii=True))
+ except ValueError as error:
+ print(json.dumps({"error": str(error)}))
+ except (OSError, subprocess.SubprocessError):
+ print(json.dumps({"error": "The guest operation failed. Check its arguments, permissions, and connection."}))
diff --git a/tools/mac-vm-bridge.py b/tools/mac-vm-bridge.py
index 8cecfb19245958b5edcd8b67bc71a09fdc994fef..fc6bcf6d95e5120795cf48709145445e2940cde3 100644
--- a/tools/mac-vm-bridge.py
+++ b/tools/mac-vm-bridge.py
@@ -4,10 +4,13 @@ import fcntl
from importlib import import_module
import json
import os
+import selectors
import signal
import struct
import subprocess
import sys
+import tempfile
+import time
vm = import_module("mac-agent-vm")
@@ -41,6 +44,52 @@ def respond(value):
sys.stdout.buffer.flush()
+def computer(request):
+ with tempfile.TemporaryFile() as source, selectors.DefaultSelector() as selector:
+ source.write(json.dumps(request).encode())
+ source.seek(0)
+ process = subprocess.Popen([str(vm.TART), "exec", "-i", vm.NAME, "/usr/bin/python3",
+ "/usr/local/libexec/snowglobe-computer.py"], stdin=source, stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE, start_new_session=True, env={**os.environ, "TART_HOME": str(vm.ROOT / "state")})
+ output = bytearray()
+ errors = 0
+ selector.register(process.stdout, selectors.EVENT_READ, True)
+ selector.register(process.stderr, selectors.EVENT_READ, False)
+ deadline = time.monotonic() + 205
+ try:
+ while selector.get_map():
+ remaining = deadline - time.monotonic()
+ if remaining <= 0:
+ raise ValueError("The guest command timed out. Check its status before retrying.")
+ for key, _ in selector.select(remaining):
+ data = os.read(key.fd, 65536)
+ if not data:
+ selector.unregister(key.fileobj)
+ elif key.data:
+ output.extend(data)
+ else:
+ errors += len(data)
+ if len(output) > 16 * 1024 * 1024 or errors > 65536:
+ raise ValueError("The computer response is too large.")
+ if process.wait(timeout=max(.001, deadline - time.monotonic())):
+ raise ValueError("The Mac guest did not answer. Check its agent and retry.")
+ value = json.loads(output)
+ if not isinstance(value, dict):
+ raise ValueError("The Mac guest returned an incomplete response.")
+ if "error" in value:
+ raise ValueError(str(value["error"]))
+ return value
+ finally:
+ if process.poll() is None:
+ try:
+ os.killpg(process.pid, signal.SIGKILL)
+ except ProcessLookupError:
+ pass
+ process.wait()
+ process.stdout.close()
+ process.stderr.close()
+
+
def lifecycle(action):
process = subprocess.Popen([sys.executable, vm.__file__, action], stdout=subprocess.DEVNULL,
start_new_session=True)
@@ -77,6 +126,10 @@ def main():
vm.tart("exec", "-i", vm.NAME, "/usr/bin/env", "LC_CTYPE=en_US.UTF-8", "/usr/bin/pbcopy",
input=value.encode(), capture_output=True, timeout=15)
respond({"value": None})
+ elif action == "computer" and set(request) == {"action", "request"}:
+ if not isinstance(request["request"], dict):
+ raise ValueError("Send a computer operation.")
+ respond({"value": computer(request["request"])})
elif action == "console" and set(request) == {"action"}:
with vm.guest_screen() as upstream:
respond({"value": None})
diff --git a/tools/mac-vms.py b/tools/mac-vms.py
index 076b9897bbcb89f9ba41f40083441481c57f2a56..3dde6b9e8d8ce6941efa850f46769a13389389d0 100644
--- a/tools/mac-vms.py
+++ b/tools/mac-vms.py
@@ -9,7 +9,7 @@ import tempfile
CONFIG = json.loads(os.environ.get("SNOWGLOBE_MAC_VM", "null"))
-CAPABILITIES = ["start", "shutdown", "reboot", "suspend", "resume", "clipboard"]
+CAPABILITIES = ["start", "shutdown", "reboot", "suspend", "resume", "clipboard", "computer"]
CACHE = Path(os.environ.get("SNOWGLOBE_MAC_VM_CACHE", "/var/lib/snowglobe/host/mac-vm.json"))
@@ -42,7 +42,7 @@ def connect(request, timeout=10):
return data
size, = struct.unpack("!I", read(4))
- if size > 65536:
+ if size > (16 * 1024 * 1024 if request["action"] == "computer" else 65536):
raise ValueError("The Mac response is too large.")
reply = json.loads(read(size))
if "error" in reply:
@@ -113,10 +113,12 @@ def handle(action, payload):
return None
if action == "console":
return {"remote": True}
- if action == "act" and payload["action"] in CAPABILITIES:
+ if action == "act" and payload["action"] in {"start", "shutdown", "reboot", "suspend", "resume"}:
request = {"action": payload["action"]}
elif action == "clipboard":
request = {"action": "clipboard", "text": payload["text"]}
+ elif action == "computer":
+ request = {"action": "computer", "request": payload["request"]}
else:
raise ValueError("This operation is unavailable for this Mac VM.")
with connect(request, timeout=220) as (value, _):
diff --git a/tools/snowglobe.py b/tools/snowglobe.py
index e23f9bb2329ce8b4294547196a85c14edd0fa32d..1224a8a5e431c0159303848694e417d10dc6b3d3 100644
--- a/tools/snowglobe.py
+++ b/tools/snowglobe.py
@@ -950,6 +950,7 @@ def main():
],
)
parser.add_argument("name", nargs="?")
+ parser.add_argument("--computer")
parser.add_argument("--base-domain")
parser.add_argument("--root")
parser.add_argument("--pool")
@@ -957,10 +958,12 @@ def main():
parser.add_argument("--env", action="append", default=[])
parser.add_argument("--key", action="append", default=[])
args = parser.parse_args()
+ if args.computer and (args.mode != "stage" or args.name != "dashboard"):
+ parser.error("--computer requires stage dashboard")
if args.mode == "stage" and args.name == "dashboard":
if args.env or args.base_domain or args.root or args.pool or args.media_root:
parser.error("dashboard staging uses the host configuration")
- __import__("dashboard-stage").stage()
+ __import__("dashboard-stage").stage(args.computer)
return
if args.mode == "destroy" and args.name and NAME.fullmatch(args.name):
saved = STATE / "stages" / f"{args.name}.json"
diff --git a/tools/vms.py b/tools/vms.py
index 33b1979277c82d8ec21f276cdfe1d93406b0d13c..31d9d3623f866c18e34a307dc34d00b488c1bbec 100644
--- a/tools/vms.py
+++ b/tools/vms.py
@@ -77,6 +77,7 @@ ACTION_FIELDS = {
"library": None, "media": {"name", "image"},
"preset": {"name", "id", "os", "description"},
"clipboard": {"name", "text"},
+ "computer": {"name", "request"},
"console": {"name"}, "serial": {"name"}, "guest": {"name"}, "owner": {"name"}, "access": {"name"}, "upload": {"volume", "size"},
}
@@ -164,6 +165,8 @@ def validate(action, payload):
if "name" not in payload:
raise ValueError("Enter a VM name.")
ensure_name(payload["name"])
+ if action == "computer" and not isinstance(payload["request"], dict):
+ raise ValueError("Send a computer operation.")
if "description" in payload and (not isinstance(payload["description"], str) or len(payload["description"]) > 200):
raise ValueError("Keep the description under 200 characters.")
for field in ("autostart", "start", "disks"):