vmctl remote: accessibility tree, pointer and keyboard control, and overlays

Implement vmctl remote command for programmatic guest control. Add
accessibility tree inspection, pointer control (click, drag, scroll),
keyboard input, and visual element overlays. Add host-side screenshot
via ScreenCaptureKit, Unix socket API for external tool integration,
and batch action orchestration.

Author: groundwater

Makefile

@@ -176,8 +176,8 @@ dmg: tools ghosttools-icon
 	@cp "$(GHOSTTOOLS_ICON_ICNS)" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/GhostTools.app/Contents/Resources/"
 	@# Copy README to DMG root
 	@cp "$(GHOSTTOOLS_DIR)/README.txt" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/"
-	@# Ad-hoc sign the app
-	codesign --force --deep -s "-" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/GhostTools.app"
+	@# Sign with developer identity (preserves TCC permissions across rebuilds)
+	codesign --force --deep -s "Apple Development" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/GhostTools.app"
 	@# Create the DMG
 	@rm -f "$(GHOSTTOOLS_DMG)"
 	hdiutil makehybrid -o "$(GHOSTTOOLS_DMG)" \

Website/image-loader.ts

@@ -0,0 +1,15 @@
+export default function ghostVMLoader({
+  src,
+}: {
+  src: string;
+  width: number;
+  quality?: number;
+}) {
+  // In static export with basePath, unoptimized images don't get the prefix.
+  // This loader ensures all images are served from the correct subdirectory.
+  const basePath = "/GhostVM";
+  if (src.startsWith("/") && !src.startsWith(basePath)) {
+    return `${basePath}${src}`;
+  }
+  return src;
+}

Website/next.config.ts

@@ -4,7 +4,8 @@ const nextConfig: NextConfig = {
   output: "export",
   basePath: "/GhostVM",
   images: {
-    unoptimized: true,
+    loader: "custom",
+    loaderFile: "./image-loader.ts",
   },
 };
 

Website/src/app/docs/architecture/page.tsx

@@ -64,6 +64,25 @@ export default function Architecture() {
         discovery, and health monitoring.
       </p>
 
+      <h3>Host API Service</h3>
+      <p>
+        Each running VM&apos;s Helper process exposes a Unix domain socket at{" "}
+        <code>~/Library/Application Support/GhostVM/api/</code>. The socket
+        accepts newline-delimited JSON requests and provides access to both
+        host-only operations (status, stop, suspend) and guest proxy operations
+        (clipboard, files, logs). See the{" "}
+        <a href="/docs/host-api">Host API</a> docs for details.
+      </p>
+
+      <h3>MCP Server</h3>
+      <p>
+        The <code>vmctl mcp</code> command starts a{" "}
+        <a href="https://modelcontextprotocol.io">Model Context Protocol</a>{" "}
+        server that bridges JSON-RPC on stdin/stdout to the Host API socket.
+        This allows AI assistants like Claude Desktop to control VMs
+        programmatically. See the <a href="/docs/mcp">MCP Server</a> docs.
+      </p>
+
       <h2>Services Architecture</h2>
       <p>
         All host-guest services are located in <code>GhostVM/Services/</code>{" "}

Website/src/app/docs/cli/page.tsx

@@ -37,16 +37,20 @@ Options:
 
       <h2>Common Commands</h2>
 
+      <h3>clone</h3>
+      <p>
+        Duplicate a VM using APFS copy-on-write. The clone gets a fresh machine
+        identity and MAC address. Near-zero disk overhead.
+      </p>
+      <CodeBlock language="bash">{`vmctl clone <source-bundle> <new-name>`}</CodeBlock>
+
       <h3>start</h3>
       <p>Launch a VM.</p>
       <CodeBlock language="bash">
         {`vmctl start <bundle-path> [options]
 
 Options:
-  --headless             Run without GUI window
-  --shared-folder PATH   Host folder to share
-  --writable             Writable shared folder
-  --read-only            Read-only shared folder (default)`}
+  --recovery             Boot to Recovery mode`}
       </CodeBlock>
 
       <h3>stop</h3>
@@ -59,15 +63,7 @@ Options:
 
       <h3>resume</h3>
       <p>Resume from suspended state.</p>
-      <CodeBlock language="bash">
-        {`vmctl resume <bundle-path> [options]
-
-Options:
-  --headless             Run without GUI window
-  --shared-folder PATH   Host folder to share
-  --writable             Writable shared folder
-  --read-only            Read-only shared folder (default)`}
-      </CodeBlock>
+      <CodeBlock language="bash">{`vmctl resume <bundle-path>`}</CodeBlock>
 
       <h3>discard-suspend</h3>
       <p>Discard the suspended state so the VM boots fresh.</p>
@@ -82,6 +78,14 @@ vmctl snapshot <bundle-path> revert <name>
 vmctl snapshot <bundle-path> delete <name>`}
       </CodeBlock>
 
+      <h3>mcp</h3>
+      <p>
+        Start an MCP server for the given VM. Reads JSON-RPC from stdin,
+        writes responses to stdout. See the{" "}
+        <a href="/docs/mcp">MCP Server</a> docs for full details.
+      </p>
+      <CodeBlock language="bash">{`vmctl mcp <bundle-path>`}</CodeBlock>
+
       <h2>Examples</h2>
       <CodeBlock language="bash" title="Full macOS workflow">
         {`# Create and install a macOS VM
@@ -95,6 +99,15 @@ vmctl snapshot ~/VMs/dev.GhostVM create clean-state
 # Later: revert to clean state
 vmctl snapshot ~/VMs/dev.GhostVM revert clean-state`}
       </CodeBlock>
+
+      <CodeBlock language="bash" title="Clone and automate">
+        {`# Clone an existing workspace
+vmctl clone ~/VMs/dev.GhostVM staging
+vmctl start ~/VMs/staging.GhostVM
+
+# Start an MCP server for AI agent control
+vmctl mcp ~/VMs/staging.GhostVM`}
+      </CodeBlock>
       <PrevNextNav currentHref="/docs/cli" />
     </>
   );

Website/src/app/docs/getting-started/page.tsx

@@ -91,6 +91,10 @@ vmctl start ~/VMs/sandbox.GhostVM`}
           Set up <Link href="/docs/services">host-guest services</Link> like clipboard
           sync and file transfer
         </li>
+        <li>
+          Let AI agents control VMs with the{" "}
+          <Link href="/docs/mcp">MCP Server</Link>
+        </li>
       </ul>
 
       <PrevNextNav currentHref="/docs/getting-started" />

Website/src/app/docs/gui-app/page.tsx

@@ -53,7 +53,9 @@ export default function GUIApp() {
         </li>
         <li>
           <strong>Icon Chooser</strong> &mdash; switch the workspace Dock icon
-          between Generic, App, Stack, and Custom modes, saved instantly
+          between Generic, Glass, App, and Stack modes. Glass mode renders any
+          app icon with a frosted overlay. Drag and drop icons into the icon
+          slots for quick customization
         </li>
         <li>
           <strong>Capture Inputs</strong> &mdash; toggle to send all keyboard
@@ -75,6 +77,8 @@ export default function GUIApp() {
       <ul>
         <li>Start / Boot to Recovery</li>
         <li>Stop / Terminate</li>
+        <li>Clone &mdash; duplicate the workspace with APFS copy-on-write</li>
+        <li>Rename &mdash; change the workspace name and bundle filename</li>
         <li>Edit Settings (CPU, memory, disk, shared folders, port forwards)</li>
         <li>Snapshot management (create, revert, delete)</li>
         <li>Show in Finder / Remove from List / Delete</li>

Website/src/app/layout.tsx

@@ -7,7 +7,7 @@ import "./globals.css";
 export const metadata: Metadata = {
   title: "GhostVM - Agentic Workspaces on macOS",
   description:
-    "GhostVM is a native macOS app for running multiple isolated agentic workspaces on macOS. Deep host integration, scriptable CLI, and self-contained VM bundles.",
+    "GhostVM is a native macOS app for running isolated agentic workspaces on macOS. AI agents control VMs via the built-in MCP server. Deep host integration, scriptable CLI, instant clones, and self-contained bundles.",
 };
 
 export default function RootLayout({

Website/src/app/page.tsx

@@ -1,4 +1,5 @@
 import Hero from "@/components/landing/Hero";
+import MCPSection from "@/components/landing/MCPSection";
 import ScreenshotShowcase from "@/components/landing/ScreenshotShowcase";
 import AutomationSection from "@/components/landing/AutomationSection";
 import IntegrationSection from "@/components/landing/IntegrationSection";
@@ -13,10 +14,11 @@ export default function Home() {
       <Hero />
       <IntegrationSection />
       <ScreenshotShowcase />
-      <AutomationSection />
       <FeatureGrid />
       <SecuritySection />
       <VMIconShowcase />
+      <AutomationSection />
+      <MCPSection />
       <DownloadCTA />
     </>
   );

Website/src/components/landing/AutomationSection.tsx

@@ -13,6 +13,12 @@ const terminalLines = [
   { prompt: false, text: "" },
   { prompt: true, text: "vmctl snapshot ~/VMs/dev.GhostVM create clean-state" },
   { prompt: false, text: 'Snapshot "clean-state" created.' },
+  { prompt: false, text: "" },
+  { prompt: true, text: "vmctl clone ~/VMs/dev.GhostVM staging" },
+  { prompt: false, text: "Cloned to ~/VMs/staging.GhostVM (APFS copy-on-write)" },
+  { prompt: false, text: "" },
+  { prompt: true, text: "vmctl mcp ~/VMs/staging.GhostVM" },
+  { prompt: false, text: "MCP server ready (stdin/stdout)" },
 ];
 
 const bullets = [
@@ -36,6 +42,14 @@ const bullets = [
     title: "CI/CD ready",
     description: "Provision isolated workspaces in build pipelines and testing workflows.",
   },
+  {
+    title: "Instant Clone",
+    description: "Duplicate a workspace instantly with APFS copy-on-write. Fresh identity, minimal disk usage.",
+  },
+  {
+    title: "MCP Server",
+    description: "Expose tools to AI agents via JSON-RPC. Clipboard, files, and lifecycle — all programmatic.",
+  },
 ];
 
 function TerminalBlock() {