@rmbk/compeek 0.2.4 → 0.2.6

package/README.md

@@ -24,7 +24,7 @@
 ### Option 1: One command (recommended)
 
 ```bash
-npx @rmbk/compeek start --open
+npx @rmbk/compeek@latest start --open
 ```
 
 This downloads a virtual desktop, starts it, and opens the dashboard in your browser.
@@ -58,7 +58,7 @@ The agent loop runs in the browser via `@anthropic-ai/sdk` with `dangerouslyAllo
 It uses `computer_20250124`, `bash_20250124`, and `text_editor_20250728` tools.
 Extended thinking is enabled with a 10240 token budget.
 
-Each container runs Ubuntu 24.04 with Xvfb (1280x720), XFWM4, x11vnc, noVNC, and Firefox (with uBlock Origin).
+Each container runs Ubuntu 24.04 with Xvfb (1280x768), XFWM4, x11vnc, noVNC, and Firefox (with uBlock Origin).
 The container exposes a minimal Express tool server with endpoints:
 `GET /api/health`, `GET /api/info`, `POST /api/tool`, `POST /api/bash`.
 
@@ -78,7 +78,7 @@ Set `DESKTOP_MODE` when starting a container:
 | `headless` | No visual — commands only | Automated scripts |
 
 ```bash
-npx @rmbk/compeek start --mode browser
+npx @rmbk/compeek@latest start --mode browser
 # or
 docker run -d -e DESKTOP_MODE=browser -p 3001:3000 -p 6081:6080 --shm-size=512m ghcr.io/uburuntu/compeek
 ```
@@ -100,13 +100,13 @@ Three ways to connect:
 ## CLI
 
 ```bash
-npx @rmbk/compeek start          # Pull image, start container, print connection info
-npx @rmbk/compeek start --open   # Same + open dashboard in browser
-npx @rmbk/compeek stop           # Stop all compeek containers
-npx @rmbk/compeek stop 1         # Stop compeek-1
-npx @rmbk/compeek status         # List running containers
-npx @rmbk/compeek logs           # Follow container logs
-npx @rmbk/compeek open           # Open dashboard with auto-connect URL
+npx @rmbk/compeek@latest start          # Pull image, start container, print connection info
+npx @rmbk/compeek@latest start --open   # Same + open dashboard in browser
+npx @rmbk/compeek@latest stop           # Stop all compeek containers
+npx @rmbk/compeek@latest stop 1         # Stop compeek-1
+npx @rmbk/compeek@latest status         # List running containers
+npx @rmbk/compeek@latest logs           # Follow container logs
+npx @rmbk/compeek@latest open           # Open dashboard with auto-connect URL
 ```
 
 Flags for `start`: `--name`, `--api-port`, `--vnc-port`, `--mode`, `--persist`, `--password`, `--tunnel`, `--no-pull`, `--open`.
@@ -126,7 +126,7 @@ Each container auto-generates a **VNC password** on startup. The password is inc
 You can set your own password with `--password`:
 
 ```bash
-npx @rmbk/compeek start --password mysecret
+npx @rmbk/compeek@latest start --password mysecret
 ```
 
 ### Remote access
@@ -136,7 +136,7 @@ If you're running compeek on the same machine as your browser, everything works
 To access a container from another machine (e.g. a remote server), use `--tunnel` to create public URLs:
 
 ```bash
-npx @rmbk/compeek start --tunnel
+npx @rmbk/compeek@latest start --tunnel
 ```
 
 This uses [localtunnel](https://theboroer.github.io/localtunnel-www/) to make the container reachable over the internet. The VNC desktop is password-protected, but the tool API currently has no authentication — use a VPN or firewall for sensitive environments.

package/bin/compeek.mjs

@@ -1,16 +1,24 @@
 #!/usr/bin/env node
 
 // compeek CLI — zero dependencies, Node.js built-ins only
-// Usage: npx compeek [start|stop|status|logs|open]
+// Usage: npx compeek [start|stop|status|logs|open|mcp]
 
 import { execSync, spawn } from 'node:child_process';
 import http from 'node:http';
 import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 
 const IMAGE = 'ghcr.io/uburuntu/compeek:latest';
+const VM_IMAGES = {
+  windows: 'dockurr/windows:latest',
+  macos: 'dockurr/macos:latest',
+};
+const SIDECAR_IMAGE = IMAGE;
 const CONTAINER_PREFIX = 'compeek-';
 const DASHBOARD_URL = 'https://compeek.rmbk.me';
 const HEALTH_TIMEOUT = 30_000;
+const VM_HEALTH_TIMEOUT = 180_000; // VMs take longer to boot
 const HEALTH_INTERVAL = 1_000;
 
 // ── ANSI Colors ──────────────────────────────────────────
@@ -49,6 +57,38 @@ function hasDocker() {
   }
 }
 
+function hasKvm() {
+  try {
+    run('ls /dev/kvm', { allowFail: false });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function validateOsRequirements(os) {
+  if (os === 'linux') return;
+  const platform = process.platform;
+  const osLabel = os === 'windows' ? 'Windows' : 'macOS';
+
+  if (platform === 'darwin') {
+    console.error(`\n  ${c.red}${osLabel} containers require a Linux host with KVM.${c.reset}`);
+    console.error(`  They do not work on macOS Docker Desktop.\n`);
+    process.exit(1);
+  }
+  if (platform === 'win32' && os === 'macos') {
+    console.error(`\n  ${c.red}macOS containers require a Linux host with KVM.${c.reset}`);
+    console.error(`  They do not work on Windows Docker Desktop.\n`);
+    process.exit(1);
+  }
+  if (platform === 'linux' && !hasKvm()) {
+    console.error(`\n  ${c.red}KVM is not available (/dev/kvm not found).${c.reset}`);
+    console.error(`  ${osLabel} containers require hardware virtualization.`);
+    console.error(`  Enable virtualization in BIOS and ensure the kvm kernel module is loaded.\n`);
+    process.exit(1);
+  }
+}
+
 function listContainers() {
   const out = run(
     `docker ps -a --filter "name=^${CONTAINER_PREFIX}" --format "{{.Names}}\\t{{.Status}}\\t{{.Ports}}"`,
@@ -188,9 +228,10 @@ function waitForTunnelUrls(host, port, timeout) {
   });
 }
 
-function buildConnectionString(name, apiHost, apiPort, vncHost, vncPort, vncPassword) {
+function buildConnectionString(name, apiHost, apiPort, vncHost, vncPort, vncPassword, osType) {
   const config = { name, type: 'compeek', apiHost, apiPort, vncHost, vncPort };
   if (vncPassword) config.vncPassword = vncPassword;
+  if (osType && osType !== 'linux') config.osType = osType;
   return Buffer.from(JSON.stringify(config)).toString('base64');
 }
 
@@ -207,6 +248,33 @@ function openUrl(url) {
 
 // ── Commands ─────────────────────────────────────────────
 
+function detectRunningContainer() {
+  const containers = listContainers().filter(c => c.status.startsWith('Up'));
+  if (containers.length === 0) return null;
+
+  const name = containers[0].name;
+  const inspect = run(`docker inspect --format '{{json .NetworkSettings.Ports}}' ${name}`, { allowFail: true });
+  if (!inspect) return null;
+
+  try {
+    const ports = JSON.parse(inspect);
+    const apiBinding = ports['3000/tcp']?.[0];
+    const apiPort = apiBinding ? parseInt(apiBinding.HostPort) : 3001;
+
+    // Extract VNC_PASSWORD from container env
+    const envStr = run(`docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' ${name}`, { allowFail: true });
+    let apiToken;
+    if (envStr) {
+      const match = envStr.match(/^VNC_PASSWORD=(.+)$/m);
+      if (match) apiToken = match[1];
+    }
+
+    return { name, apiPort, apiToken, containerUrl: `http://localhost:${apiPort}` };
+  } catch {
+    return null;
+  }
+}
+
 async function cmdStart(args) {
   if (!hasDocker()) {
     console.error(`${c.red}Docker is not available.${c.reset} Install Docker first: https://docs.docker.com/get-docker/`);
@@ -214,16 +282,31 @@ async function cmdStart(args) {
   }
 
   const flags = parseFlags(args);
+  const os = flags.os || 'linux';
+  if (!['linux', 'windows', 'macos'].includes(os)) {
+    console.error(`${c.red}Invalid --os value: ${os}${c.reset}. Use: linux, windows, or macos`);
+    process.exit(1);
+  }
+
+  // Validate KVM requirements for Windows/macOS
+  if (os !== 'linux') {
+    validateOsRequirements(os);
+  }
+
   const name = flags.name || findNextName();
   const { apiPort: defaultApi, vncPort: defaultVnc } = findNextPorts();
   const apiPort = parseInt(flags['api-port']) || defaultApi;
   const vncPort = parseInt(flags['vnc-port']) || defaultVnc;
-  const mode = flags.mode || 'full';
+  const mode = os === 'linux' ? (flags.mode || 'full') : 'sidecar';
   const vncPassword = flags.password || crypto.randomBytes(24).toString('base64url').slice(0, 24);
-  const sessionName = name.replace(CONTAINER_PREFIX, '').replace(/^(\d+)$/, 'Desktop $1');
-
-  // Tunnel provider: cloudflare by default, --no-tunnel to disable, --tunnel <provider> to override
-  const tunnelProvider = flags['no-tunnel'] ? 'none'
+  const osLabel = os === 'windows' ? 'Windows' : os === 'macos' ? 'macOS' : 'Linux';
+  const sessionName = flags.name
+    ? name.replace(CONTAINER_PREFIX, '')
+    : name.replace(CONTAINER_PREFIX, '').replace(/^(\d+)$/, `${osLabel} $1`);
+
+  // Tunnel provider: cloudflare by default for Linux, disabled for VMs in v1
+  const tunnelProvider = os !== 'linux' ? 'none'
+    : flags['no-tunnel'] ? 'none'
     : typeof flags.tunnel === 'string' ? flags.tunnel
     : flags.tunnel === true ? 'cloudflare'
     : 'cloudflare';
@@ -232,60 +315,141 @@ async function cmdStart(args) {
   console.log(`  ${c.bold}${c.cyan}compeek${c.reset}`);
   console.log('');
 
-  if (!flags['no-pull']) {
-    console.log(`  ${c.dim}Pulling image...${c.reset}`);
-    try {
-      run(`docker pull ${IMAGE}`, { stdio: 'inherit' });
-    } catch {
-      console.log(`  ${c.yellow}Pull failed, using cached image.${c.reset}`);
+  if (os === 'linux') {
+    // ── Linux: single container (existing behavior) ──
+    if (!flags['no-pull']) {
+      console.log(`  ${c.dim}Pulling image...${c.reset}`);
+      try {
+        run(`docker pull ${IMAGE}`, { stdio: 'inherit' });
+      } catch {
+        console.log(`  ${c.yellow}Pull failed, using cached image.${c.reset}`);
+      }
+      console.log('');
+    }
+
+    const info = [
+      `mode:${c.white}${mode}${c.reset}`,
+      `api:${c.white}${apiPort}${c.reset}`,
+      `vnc:${c.white}${vncPort}${c.reset}`,
+    ];
+    if (flags.persist) info.push(`${c.green}persist${c.reset}`);
+    if (tunnelProvider !== 'none') info.push(`${c.yellow}${tunnelProvider}${c.reset}`);
+
+    console.log(`  ${c.cyan}▸${c.reset} Starting ${c.bold}${name}${c.reset}  ${c.dim}${info.join(' · ')}${c.reset}`);
+
+    run(`docker rm -f ${name}`, { allowFail: true });
+
+    run([
+      'docker run -d',
+      `--name ${name}`,
+      `-p ${apiPort}:3000`,
+      `-p ${vncPort}:6080`,
+      `--shm-size=512m`,
+      `-e DISPLAY=:1`,
+      `-e DESKTOP_MODE=${mode}`,
+      `-e COMPEEK_SESSION_NAME="${sessionName}"`,
+      `-e VNC_PASSWORD="${vncPassword}"`,
+      `-e TUNNEL_PROVIDER=${tunnelProvider}`,
+      flags.persist ? `-v ${name}-data:/home/compeek/data` : '',
+      `--security-opt seccomp=unconfined`,
+      IMAGE,
+    ].filter(Boolean).join(' '));
+  } else {
+    // ── Windows/macOS: VM + sidecar containers ──
+    const vmImage = VM_IMAGES[os];
+    const vmName = `${name}-vm`;
+    const netName = `${name}-net`;
+
+    if (!flags['no-pull']) {
+      console.log(`  ${c.dim}Pulling images...${c.reset}`);
+      try {
+        run(`docker pull ${vmImage}`, { stdio: 'inherit' });
+      } catch {
+        console.log(`  ${c.yellow}VM image pull failed, using cached.${c.reset}`);
+      }
+      try {
+        run(`docker pull ${SIDECAR_IMAGE}`, { stdio: 'inherit' });
+      } catch {
+        console.log(`  ${c.yellow}Sidecar image pull failed, using cached.${c.reset}`);
+      }
+      console.log('');
     }
-    console.log('');
-  }
 
-  const info = [
-    `mode:${c.white}${mode}${c.reset}`,
-    `api:${c.white}${apiPort}${c.reset}`,
-    `vnc:${c.white}${vncPort}${c.reset}`,
-  ];
-  if (flags.persist) info.push(`${c.green}persist${c.reset}`);
-  if (tunnelProvider !== 'none') info.push(`${c.yellow}${tunnelProvider}${c.reset}`);
-
-  console.log(`  ${c.cyan}▸${c.reset} Starting ${c.bold}${name}${c.reset}  ${c.dim}${info.join(' · ')}${c.reset}`);
-
-  // Remove existing container with same name if stopped
-  run(`docker rm -f ${name}`, { allowFail: true });
-
-  run([
-    'docker run -d',
-    `--name ${name}`,
-    `-p ${apiPort}:3000`,
-    `-p ${vncPort}:6080`,
-    `--shm-size=512m`,
-    `-e DISPLAY=:1`,
-    `-e DESKTOP_MODE=${mode}`,
-    `-e COMPEEK_SESSION_NAME="${sessionName}"`,
-    `-e VNC_PASSWORD="${vncPassword}"`,
-    `-e TUNNEL_PROVIDER=${tunnelProvider}`,
-    flags.persist ? `-v ${name}-data:/home/compeek/data` : '',
-    `--security-opt seccomp=unconfined`,
-    IMAGE,
-  ].filter(Boolean).join(' '));
+    const vmVersion = flags.version || (os === 'windows' ? '11' : '15');
+    const vmRam = flags.ram || '4G';
+    const vmCpus = flags.cpus || '2';
+    const vmDisk = flags.disk || '64G';
+
+    const info = [
+      `os:${c.white}${osLabel}${c.reset}`,
+      `ver:${c.white}${vmVersion}${c.reset}`,
+      `ram:${c.white}${vmRam}${c.reset}`,
+      `api:${c.white}${apiPort}${c.reset}`,
+      `vnc:${c.white}${vncPort}${c.reset}`,
+    ];
+    if (flags.persist) info.push(`${c.green}persist${c.reset}`);
+
+    console.log(`  ${c.cyan}▸${c.reset} Starting ${c.bold}${name}${c.reset}  ${c.dim}${info.join(' · ')}${c.reset}`);
+    console.log(`  ${c.yellow}Note:${c.reset} ${osLabel} VM boot is slow. Tunneling not available for VMs.`);
+
+    // Clean up any existing containers/network
+    run(`docker rm -f ${name}`, { allowFail: true });
+    run(`docker rm -f ${vmName}`, { allowFail: true });
+    run(`docker network rm ${netName}`, { allowFail: true });
+
+    // Create dedicated network
+    run(`docker network create ${netName}`);
+
+    // Start dockur VM container
+    run([
+      'docker run -d',
+      `--name ${vmName}`,
+      `--network ${netName}`,
+      `--device /dev/kvm`,
+      `-e VERSION=${vmVersion}`,
+      `-e RAM_SIZE=${vmRam}`,
+      `-e CPU_CORES=${vmCpus}`,
+      `-e DISK_SIZE=${vmDisk}`,
+      os === 'windows' ? '-e USERNAME=User -e PASSWORD=password' : '',
+      flags.persist ? `-v ${name}-data:/storage` : '',
+      `--cap-add NET_ADMIN`,
+      vmImage,
+    ].filter(Boolean).join(' '));
+
+    // Start compeek sidecar container
+    run([
+      'docker run -d',
+      `--name ${name}`,
+      `--network ${netName}`,
+      `-p ${apiPort}:3000`,
+      `-p ${vncPort}:6080`,
+      `-e DESKTOP_MODE=sidecar`,
+      `-e SIDECAR_TARGET=${vmName}`,
+      `-e SIDECAR_VNC_PORT=5900`,
+      `-e SIDECAR_VIEWER_PORT=8006`,
+      `-e SIDECAR_OS=${os}`,
+      `-e COMPEEK_SESSION_NAME="${sessionName}"`,
+      `-e VNC_PASSWORD="${vncPassword}"`,
+      SIDECAR_IMAGE,
+    ].filter(Boolean).join(' '));
+  }
 
+  const healthTimeout = os === 'linux' ? HEALTH_TIMEOUT : VM_HEALTH_TIMEOUT;
   try {
-    await waitForHealth('localhost', apiPort, HEALTH_TIMEOUT);
+    await waitForHealth('localhost', apiPort, healthTimeout);
   } catch {
     console.error(`\n  ${c.red}Container did not start.${c.reset} Check logs: npx compeek logs`);
     process.exit(1);
   }
 
-  // Wait for tunnel URLs if tunneling is enabled
+  // Wait for tunnel URLs if tunneling is enabled (Linux only)
   let tunnel = null;
   if (tunnelProvider !== 'none' && mode !== 'headless') {
     tunnel = await waitForTunnelUrls('localhost', apiPort, 30_000);
   }
 
   // Build connection strings
-  const localConnStr = buildConnectionString(sessionName, 'localhost', apiPort, 'localhost', vncPort, vncPassword);
+  const localConnStr = buildConnectionString(sessionName, 'localhost', apiPort, 'localhost', vncPort, vncPassword, os);
   let tunnelConnStr = null;
   let dashboardLink;
 
@@ -297,6 +461,7 @@ async function cmdStart(args) {
       apiUrl.hostname, 443,
       vncUrl.hostname, 443,
       vncPassword,
+      os,
     );
     dashboardLink = `${DASHBOARD_URL}/#config=${tunnelConnStr}`;
   } else {
@@ -316,10 +481,26 @@ async function cmdStart(args) {
     console.log(`  ${c.dim}Local VNC${c.reset}   http://localhost:${vncPort}`);
     console.log(`  ${c.dim}Password${c.reset}    ${vncPassword}`);
   }
+  if (os !== 'linux') {
+    console.log('');
+    console.log(`  ${c.yellow}Limitations:${c.reset} No bash/shell access in ${osLabel} VMs.`);
+    console.log(`  ${c.dim}The agent uses mouse, keyboard, and screenshots only.${c.reset}`);
+  }
   console.log('');
   console.log(`  ${c.dim}──── Connection string ──────────────────────────${c.reset}`);
   console.log(`  ${c.dim}${tunnelConnStr || localConnStr}${c.reset}`);
   console.log('');
+  console.log(`  ${c.dim}──── MCP ───────────────────────────────────────${c.reset}`);
+  console.log('');
+  if (tunnel) {
+    console.log(`  ${c.dim}Streamable HTTP${c.reset}  ${tunnel.apiUrl}/mcp`);
+  }
+  console.log(`  ${c.dim}Local MCP${c.reset}        http://localhost:${apiPort}/mcp`);
+  console.log(`  ${c.dim}stdio proxy${c.reset}      npx @rmbk/compeek@latest mcp`);
+  console.log('');
+  console.log(`  ${c.dim}Claude Code config (~/.claude/settings.json):${c.reset}`);
+  console.log(`  ${c.dim}{ "mcpServers": { "compeek": { "command": "npx", "args": ["-y", "@rmbk/compeek@latest", "mcp"] } } }${c.reset}`);
+  console.log('');
 
   if (flags.open) {
     openUrl(dashboardLink);
@@ -332,6 +513,9 @@ function cmdStop(args) {
     const name = target.startsWith(CONTAINER_PREFIX) ? target : `${CONTAINER_PREFIX}${target}`;
     console.log(`  ${c.cyan}▸${c.reset} Stopping ${c.bold}${name}${c.reset}...`);
     run(`docker rm -f ${name}`, { allowFail: true, stdio: 'inherit' });
+    // Clean up companion VM container and network if they exist
+    run(`docker rm -f ${name}-vm`, { allowFail: true });
+    run(`docker network rm ${name}-net`, { allowFail: true });
     console.log(`  ${c.green}✓${c.reset} Stopped`);
   } else {
     const containers = listContainers();
@@ -342,6 +526,9 @@ function cmdStop(args) {
     for (const ctr of containers) {
       console.log(`  ${c.cyan}▸${c.reset} Stopping ${c.bold}${ctr.name}${c.reset}...`);
       run(`docker rm -f ${ctr.name}`, { allowFail: true });
+      // Clean up companion VM container and network
+      run(`docker rm -f ${ctr.name}-vm`, { allowFail: true });
+      run(`docker network rm ${ctr.name}-net`, { allowFail: true });
     }
     console.log(`  ${c.green}✓${c.reset} Stopped ${containers.length} container(s)`);
   }
@@ -384,6 +571,94 @@ function cmdLogs(args) {
   child.on('exit', code => process.exit(code || 0));
 }
 
+async function cmdMcp(args) {
+  const flags = parseFlags(args);
+  let containerUrl = flags['container-url'];
+  let apiToken = flags['api-token'];
+  let startedContainerName = null;
+
+  if (!containerUrl) {
+    // Auto-detect running container
+    const detected = detectRunningContainer();
+    if (detected) {
+      containerUrl = detected.containerUrl;
+      apiToken = apiToken || detected.apiToken;
+      process.stderr.write(`Using container ${detected.name} at ${containerUrl}\n`);
+    } else if (flags.start) {
+      // Auto-start a container
+      if (!hasDocker()) {
+        process.stderr.write('Docker is not available. Specify --container-url or install Docker.\n');
+        process.exit(1);
+      }
+
+      const name = flags.name || findNextName();
+      const { apiPort } = findNextPorts();
+      const vncPassword = flags.password || crypto.randomBytes(24).toString('base64url').slice(0, 24);
+      const mode = flags.mode || 'full';
+
+      run(`docker rm -f ${name}`, { allowFail: true });
+      run([
+        'docker run -d',
+        `--name ${name}`,
+        `-p ${apiPort}:3000`,
+        `--shm-size=512m`,
+        `-e DISPLAY=:1`,
+        `-e DESKTOP_MODE=${mode}`,
+        `-e COMPEEK_SESSION_NAME="${name}"`,
+        `-e VNC_PASSWORD="${vncPassword}"`,
+        `-e TUNNEL_PROVIDER=none`,
+        flags.persist ? `-v ${name}-data:/home/compeek/data` : '',
+        `--security-opt seccomp=unconfined`,
+        IMAGE,
+      ].filter(Boolean).join(' '));
+
+      process.stderr.write(`Starting container ${name}...\n`);
+      try {
+        await waitForHealth('localhost', apiPort, HEALTH_TIMEOUT);
+      } catch {
+        process.stderr.write('Container did not start. Check logs: npx compeek logs\n');
+        process.exit(1);
+      }
+
+      containerUrl = `http://localhost:${apiPort}`;
+      apiToken = vncPassword;
+      startedContainerName = name;
+      process.stderr.write(`Container ${name} ready at ${containerUrl}\n`);
+    } else {
+      process.stderr.write('No running compeek container found.\n');
+      process.stderr.write('Start one with: npx @rmbk/compeek@latest start\n');
+      process.stderr.write('Or use: npx @rmbk/compeek@latest mcp --start\n');
+      process.exit(1);
+    }
+  }
+
+  // Resolve path to the compiled stdio entrypoint
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const stdioPath = join(__dirname, '..', 'dist', 'mcp', 'stdio.js');
+
+  const mcpArgs = ['--container-url', containerUrl];
+  if (apiToken) mcpArgs.push('--api-token', apiToken);
+
+  const child = spawn('node', [stdioPath, ...mcpArgs], {
+    stdio: ['inherit', 'inherit', 'inherit'],
+  });
+
+  // Clean up auto-started container on exit
+  if (startedContainerName && !flags.persist) {
+    const cleanup = () => {
+      try {
+        run(`docker rm -f ${startedContainerName}`, { allowFail: true });
+        process.stderr.write(`Container ${startedContainerName} removed.\n`);
+      } catch { /* ignore */ }
+    };
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => { child.kill('SIGINT'); });
+    process.on('SIGTERM', () => { child.kill('SIGTERM'); });
+  }
+
+  child.on('exit', code => process.exit(code || 0));
+}
+
 function cmdOpen(args) {
   const target = args[0];
   let name;
@@ -431,7 +706,7 @@ function parseFlags(args) {
     const arg = args[i];
     if (arg.startsWith('--')) {
       const key = arg.slice(2);
-      if (key === 'open' || key === 'no-pull' || key === 'persist' || key === 'no-tunnel') {
+      if (key === 'open' || key === 'no-pull' || key === 'persist' || key === 'no-tunnel' || key === 'start') {
         flags[key] = true;
       } else if (key === 'tunnel') {
         // --tunnel (default provider) or --tunnel cloudflare / --tunnel localtunnel
@@ -468,13 +743,16 @@ switch (command) {
   case 'open':
     cmdOpen(rest);
     break;
+  case 'mcp':
+    cmdMcp(rest);
+    break;
   case '--help':
   case '-h':
   case 'help':
     console.log(`
   ${c.bold}${c.cyan}compeek${c.reset} ${c.dim}— AI eyes & hands for any desktop${c.reset}
 
-  ${c.bold}Usage${c.reset}   npx @rmbk/compeek ${c.dim}[command] [options]${c.reset}
+  ${c.bold}Usage${c.reset}   npx @rmbk/compeek@latest ${c.dim}[command] [options]${c.reset}
 
   ${c.bold}Commands${c.reset}
     start ${c.dim}............${c.reset} Start a new virtual desktop ${c.dim}(default)${c.reset}
@@ -482,9 +760,11 @@ switch (command) {
     status ${c.dim}...........${c.reset} List running containers
     logs  ${c.dim}[name]${c.reset} ${c.dim}....${c.reset} Follow container logs
     open  ${c.dim}[name]${c.reset} ${c.dim}....${c.reset} Open dashboard in browser
+    mcp ${c.dim}..............${c.reset} Start MCP stdio server ${c.dim}(for Claude Code, Cursor, etc.)${c.reset}
 
   ${c.bold}Options${c.reset}
     --open ${c.dim}..........${c.reset} Open dashboard after start
+    --os ${c.dim}<os>${c.reset} ${c.dim}........${c.reset} linux ${c.dim}(default)${c.reset} ${c.dim}|${c.reset} windows ${c.dim}|${c.reset} macos
     --mode ${c.dim}<m>${c.reset} ${c.dim}......${c.reset} full ${c.dim}|${c.reset} browser ${c.dim}|${c.reset} minimal ${c.dim}|${c.reset} headless
     --persist ${c.dim}.......${c.reset} Mount volume for persistent data
     --password ${c.dim}<pw>${c.reset} ${c.dim}.${c.reset} Custom VNC password ${c.dim}(auto-generated if omitted)${c.reset}
@@ -494,6 +774,17 @@ switch (command) {
     --name ${c.dim}<n>${c.reset} ${c.dim}......${c.reset} Custom container name
     --api-port ${c.dim}<p>${c.reset} ${c.dim}.${c.reset} Host port for tool API
     --vnc-port ${c.dim}<p>${c.reset} ${c.dim}.${c.reset} Host port for noVNC
+
+  ${c.bold}VM Options${c.reset} ${c.dim}(Windows/macOS only, requires KVM)${c.reset}
+    --version ${c.dim}<v>${c.reset} ${c.dim}..${c.reset} OS version ${c.dim}(Win: 11/10/8; macOS: 11-15)${c.reset}
+    --ram ${c.dim}<size>${c.reset} ${c.dim}....${c.reset} VM RAM ${c.dim}(default: 4G)${c.reset}
+    --cpus ${c.dim}<n>${c.reset} ${c.dim}......${c.reset} VM CPU cores ${c.dim}(default: 2)${c.reset}
+    --disk ${c.dim}<size>${c.reset} ${c.dim}...${c.reset} VM disk size ${c.dim}(default: 64G)${c.reset}
+
+  ${c.bold}MCP Options${c.reset}
+    --container-url ${c.dim}<u>${c.reset}  Container API URL ${c.dim}(default: auto-detect)${c.reset}
+    --api-token ${c.dim}<t>${c.reset} ${c.dim}....${c.reset} Bearer token for container auth
+    --start ${c.dim}.........${c.reset} Auto-launch container if none running
 `);
     break;
   default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmbk/compeek",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "AI eyes and hands for any desktop application — a general-purpose computer use agent framework powered by Claude Opus 4.6",
   "license": "MIT",
   "author": "rmbk",
@@ -26,7 +26,8 @@
     "compeek": "bin/compeek.mjs"
   },
   "files": [
-    "bin/"
+    "bin/",
+    "dist/"
   ],
   "scripts": {
     "dev:client": "vite",
@@ -37,15 +38,22 @@
     "docker:build": "docker build -f docker/Dockerfile -t compeek .",
     "docker:run": "docker run -p 3000:3000 -p 6080:6080 -p 5900:5900 --shm-size=512m -it compeek",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:e2e": "playwright test --project=ui",
+    "test:e2e:integration": "COMPEEK_E2E_INTEGRATION=1 playwright test --project=integration",
+    "test:e2e:all": "COMPEEK_E2E_INTEGRATION=1 playwright test",
+    "test:e2e:ui": "playwright test --project=ui --ui"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.74.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "cors": "^2.8.5",
     "express": "^4.21.0",
-    "sharp": "^0.34.5"
+    "sharp": "^0.34.5",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.2",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/cors": "^2.8.17",