@magpiecloud/mags 1.8.16 → 1.8.17

package/nodejs/bin/mags.js

@@ -0,0 +1,1882 @@
+#!/usr/bin/env node
+
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { exec, spawn } = require('child_process');
+
+// Config file path
+const CONFIG_DIR = path.join(process.env.HOME || process.env.USERPROFILE, '.mags');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const SSH_KEY_FILE = path.join(CONFIG_DIR, 'ssh_key');
+
+// Claude skill paths
+const CLAUDE_GLOBAL_DIR = path.join(process.env.HOME || process.env.USERPROFILE, '.claude', 'commands');
+const SKILL_URL = 'https://mags.run/mags.md';
+
+// Load saved config
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    }
+  } catch (err) {
+    // Ignore errors
+  }
+  return {};
+}
+
+// Save config
+function saveConfig(config) {
+  try {
+    if (!fs.existsSync(CONFIG_DIR)) {
+      fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+// Configuration
+const config = loadConfig();
+const API_URL = process.env.MAGS_API_URL || config.api_url || 'https://api.magpiecloud.com';
+let API_TOKEN = process.env.MAGS_API_TOKEN || config.api_token || '';
+
+// Colors
+const colors = {
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+  bold: '\x1b[1m',
+  reset: '\x1b[0m'
+};
+
+function log(color, msg) {
+  console.log(`${colors[color]}${msg}${colors.reset}`);
+}
+
+// Prompt for input
+function prompt(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// Open URL in browser
+function openBrowser(url) {
+  const platform = process.platform;
+  let cmd;
+
+  if (platform === 'darwin') {
+    cmd = `open "${url}"`;
+  } else if (platform === 'win32') {
+    cmd = `start "${url}"`;
+  } else {
+    cmd = `xdg-open "${url}"`;
+  }
+
+  exec(cmd, (err) => {
+    if (err) {
+      log('yellow', `Could not open browser automatically.`);
+      log('cyan', `Please open this URL manually: ${url}`);
+    }
+  });
+}
+
+function request(method, path, body = null) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, API_URL);
+    const isHttps = url.protocol === 'https:';
+    const lib = isHttps ? https : http;
+
+    const options = {
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname + url.search,
+      method,
+      headers: {
+        'Authorization': `Bearer ${API_TOKEN}`,
+        'Content-Type': 'application/json'
+      }
+    };
+
+    const req = lib.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch {
+          resolve(data);
+        }
+      });
+    });
+
+    req.on('error', reject);
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// Resolve job ID from name or ID
+async function resolveJobId(nameOrId) {
+  // If it looks like a UUID, use it directly
+  if (nameOrId.match(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)) {
+    return nameOrId;
+  }
+
+  // Otherwise, search by name/workspace
+  const resp = await request('GET', `/api/v1/mags-jobs?page=1&page_size=50`);
+  if (resp.jobs && resp.jobs.length > 0) {
+    // Try exact match on name first (prefer running/sleeping)
+    let job = resp.jobs.find(j => j.name === nameOrId && (j.status === 'running' || j.status === 'sleeping'));
+    if (job) return job.request_id;
+
+    // Try workspace_id match (prefer running/sleeping)
+    job = resp.jobs.find(j => j.workspace_id === nameOrId && (j.status === 'running' || j.status === 'sleeping'));
+    if (job) return job.request_id;
+
+    // Try exact name match (any status)
+    job = resp.jobs.find(j => j.name === nameOrId);
+    if (job) return job.request_id;
+
+    // Try workspace_id match (any status)
+    job = resp.jobs.find(j => j.workspace_id === nameOrId);
+    if (job) return job.request_id;
+
+    // Try partial name match (running/sleeping jobs only)
+    job = resp.jobs.find(j =>
+      (j.status === 'running' || j.status === 'sleeping') &&
+      (j.name && j.name.includes(nameOrId))
+    );
+    if (job) return job.request_id;
+  }
+
+  return nameOrId; // Return as-is, let API handle error
+}
+
+// Find a running or sleeping job for a workspace
+async function findWorkspaceJob(workspace) {
+  const resp = await request('GET', `/api/v1/mags-jobs?page=1&page_size=50`);
+  if (resp.jobs && resp.jobs.length > 0) {
+    // Prefer running, then sleeping
+    let job = resp.jobs.find(j => j.workspace_id === workspace && j.status === 'running');
+    if (job) return job;
+    job = resp.jobs.find(j => j.workspace_id === workspace && j.status === 'sleeping');
+    if (job) return job;
+  }
+  return null;
+}
+
+function usage() {
+  console.log(`
+${colors.cyan}${colors.bold}Mags CLI - Instant VM Execution${colors.reset}
+
+Usage: mags <command> [options] [script]
+
+${colors.bold}Commands:${colors.reset}
+  login                           Authenticate with Magpie
+  logout                          Remove saved credentials
+  whoami                          Show current authenticated user
+  new <name>                      Create a new persistent VM (returns ID only)
+  run [options] <script>          Execute a script on a microVM
+  ssh <workspace|name|id>         Open SSH session (auto-starts VM if needed)
+  browser [workspace]             Start a Chromium browser session (CDP access)
+  exec <workspace> <command>      Run a command on an existing VM
+  status <name|id>                Get job status
+  logs <name|id>                  Get job logs
+  list                            List recent jobs
+  url <name|id> [port]            Enable URL access for a job
+  url alias <sub> <workspace>    Create a stable URL alias for a workspace
+  url alias list                 List your URL aliases
+  url alias remove <subdomain>   Delete a URL alias
+  set <name|id> [options]          Update VM settings
+  stop <name|id>                  Stop a running job
+  resize <workspace> --disk <GB>  Resize a workspace's disk (restarts VM)
+  sync <workspace|id>             Sync workspace to S3 (without stopping)
+  workspace list                  List persistent workspaces
+  workspace delete <id>           Delete a workspace and its S3 data
+  setup-claude                    Install Mags skill for Claude Code
+
+${colors.bold}Run Options:${colors.reset}
+  -n, --name <name>               Set job/workspace name (used as both)
+  -p, --persistent                Keep VM alive after script completes
+  --no-sleep                      Never auto-sleep this VM (requires -p)
+  --base <workspace>              Mount workspace read-only as base image
+  -e, --ephemeral                 No workspace/S3 sync (fastest execution)
+  -f, --file <path>               Upload file(s) to VM (repeatable)
+  --disk <GB>                     Custom disk size in GB (default: 2)
+  --url                           Enable public URL access (requires -p)
+  --port <port>                   Port to expose for URL (default: 8080)
+  --startup-command <cmd>         Command to run when VM wakes from sleep
+
+${colors.bold}Cron Commands:${colors.reset}
+  cron add [options] <script>     Create a scheduled cron job
+  cron list                       List all cron jobs
+  cron remove <id>                Delete a cron job
+  cron enable <id>                Enable a cron job
+  cron disable <id>               Disable a cron job
+
+${colors.bold}Cron Options:${colors.reset}
+  --name <name>                   Cron job name (required)
+  --schedule <expr>               Cron expression (required, e.g. "0 * * * *")
+  -w, --workspace <id>            Workspace for cron jobs (alias for --name)
+  -p, --persistent                Keep VM alive after cron script
+
+${colors.bold}Examples:${colors.reset}
+  mags login
+  mags new myvm                     # Create VM (local disk only)
+  mags new myvm -p                   # Create VM with S3 persistence
+  mags ssh myvm                     # SSH (auto-starts if needed)
+  mags exec myvm 'ls -la'           # Run command on existing VM
+  mags run 'echo Hello World'
+  mags run -e 'echo fast'           # Ephemeral (no S3 sync)
+  mags run -f script.py 'python3 script.py'  # Upload + run file
+  mags run -n myproject 'python3 script.py'
+  mags run --base golden 'npm test'           # Use golden as read-only base
+  mags run --base golden -n fork-1 'npm test' # Base + save changes to fork-1
+  mags run -p --url 'python3 -m http.server 8080'
+  mags run -n webapp -p --url --port 3000 'npm start'
+  mags browser myproject            # Start browser with workspace
+  mags workspace list               # List workspaces
+  mags workspace delete myproject   # Delete workspace
+  mags cron add --name backup --schedule "0 0 * * *" 'tar czf backup.tar.gz data/'
+  mags cron list
+  mags status myvm
+  mags logs myvm
+  mags url myvm 8080
+  mags url alias my-api myvm          # Stable URL: my-api.apps.magpiecloud.com
+  mags url alias my-api myvm --lfg    # Stable URL: my-api.app.lfg.run
+  mags url alias list                 # List all aliases
+  mags url alias remove my-api        # Remove alias
+  mags setup-claude                 # Install Claude Code skill
+`);
+  process.exit(1);
+}
+
+async function login() {
+  console.log(`
+${colors.cyan}${colors.bold}Mags Login${colors.reset}
+
+To authenticate, you need an API token from Magpie.
+`);
+
+  log('blue', 'Opening Mags to create an API token...');
+  console.log('');
+
+  const tokenUrl = 'https://mags.run/tokens';
+  openBrowser(tokenUrl);
+
+  await sleep(1000);
+
+  console.log(`${colors.gray}If the browser didn't open, visit:${colors.reset}`);
+  console.log(`${colors.cyan}${tokenUrl}${colors.reset}`);
+  console.log('');
+  console.log(`${colors.gray}1. Click "Create Token"${colors.reset}`);
+  console.log(`${colors.gray}2. Give it a name (e.g., "mags-cli")${colors.reset}`);
+  console.log(`${colors.gray}3. Copy the token and paste it below${colors.reset}`);
+  console.log('');
+
+  const token = await prompt(`${colors.bold}Paste your API token: ${colors.reset}`);
+
+  if (!token) {
+    log('red', 'No token provided. Login cancelled.');
+    process.exit(1);
+  }
+
+  // Validate token by making a test request
+  API_TOKEN = token;
+  log('blue', 'Verifying token...');
+
+  try {
+    const resp = await request('GET', '/api/v1/mags-jobs?page=1&page_size=1');
+
+    if (resp.error === 'unauthorized' || resp.error === 'Unauthorized') {
+      log('red', 'Invalid token. Please check and try again.');
+      process.exit(1);
+    }
+
+    // Save token
+    const newConfig = { ...config, api_token: token };
+    if (saveConfig(newConfig)) {
+      console.log('');
+      log('green', 'Login successful!');
+      log('gray', `Token saved to ${CONFIG_FILE}`);
+      console.log('');
+      log('cyan', 'You can now run mags commands. Try:');
+      console.log(`  ${colors.bold}mags new myvm${colors.reset}`);
+      console.log(`  ${colors.bold}mags ssh myvm${colors.reset}`);
+    } else {
+      log('yellow', 'Login successful, but could not save token to config file.');
+      log('yellow', 'You may need to login again next time.');
+    }
+  } catch (err) {
+    log('red', `Error validating token: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+async function logout() {
+  if (!config.api_token) {
+    log('yellow', 'You are not logged in.');
+    return;
+  }
+
+  const newConfig = { ...config };
+  delete newConfig.api_token;
+
+  if (saveConfig(newConfig)) {
+    log('green', 'Logged out successfully.');
+    log('gray', 'Token removed from config.');
+  } else {
+    log('red', 'Could not remove token from config file.');
+  }
+}
+
+async function whoami() {
+  if (!API_TOKEN) {
+    log('yellow', 'Not logged in.');
+    log('gray', 'Run `mags login` to authenticate.');
+    return;
+  }
+
+  log('blue', 'Checking authentication...');
+
+  try {
+    const resp = await request('GET', '/api/v1/mags-jobs?page=1&page_size=1');
+
+    if (resp.error === 'unauthorized' || resp.error === 'Unauthorized') {
+      log('red', 'Token is invalid or expired.');
+      log('gray', 'Run `mags login` to re-authenticate.');
+      return;
+    }
+
+    log('green', 'Authenticated');
+    if (process.env.MAGS_API_TOKEN) {
+      log('gray', 'Using token from MAGS_API_TOKEN environment variable');
+    } else {
+      log('gray', `Using token from ${CONFIG_FILE}`);
+    }
+  } catch (err) {
+    log('red', `Error: ${err.message}`);
+  }
+}
+
+async function requireAuth() {
+  if (API_TOKEN) return true;
+
+  console.log(`
+${colors.yellow}You are not logged in.${colors.reset}
+
+To use Mags, you need to authenticate first.
+`);
+
+  const answer = await prompt(`${colors.bold}Would you like to login now? (Y/n): ${colors.reset}`);
+
+  if (answer.toLowerCase() === 'n' || answer.toLowerCase() === 'no') {
+    log('gray', 'You can login later with: mags login');
+    process.exit(0);
+  }
+
+  await login();
+  return true;
+}
+
+// Create a new persistent VM
+async function newVM(args) {
+  let name = null;
+  let baseWorkspace = null;
+  let diskGB = 0;
+  let persistent = false;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '-p' || args[i] === '--persistent') {
+      persistent = true;
+    } else if (args[i] === '--base' && args[i + 1]) {
+      baseWorkspace = args[++i];
+    } else if (args[i] === '--disk' && args[i + 1]) {
+      diskGB = parseInt(args[++i]) || 0;
+    } else if (!name) {
+      name = args[i];
+    }
+  }
+
+  if (!name) {
+    log('red', 'Error: Name required');
+    console.log(`\nUsage: mags new <name> [-p] [--base <workspace>] [--disk <GB>]`);
+    console.log(`  -p, --persistent  Enable S3 data persistence\n`);
+    process.exit(1);
+  }
+
+  // Check if a VM with this name already exists (running or sleeping)
+  try {
+    const jobs = await request('GET', '/api/v1/mags-jobs');
+    const existing = (jobs.jobs || []).find(j =>
+      j.name === name && (j.status === 'running' || j.status === 'sleeping')
+    );
+    if (existing) {
+      log('yellow', `Sandbox '${name}' already exists (status: ${existing.status})`);
+      console.log(`  SSH:  mags ssh ${name}`);
+      console.log(`  Exec: mags exec ${name} <command>`);
+      console.log(`  Stop: mags stop ${name}`);
+      process.exit(0);
+    }
+  } catch (e) {
+    // Non-fatal — proceed with creation if list fails
+  }
+
+  const payload = {
+    script: 'sleep infinity',
+    type: 'inline',
+    persistent: true,
+    name: name,
+    workspace_id: name,
+    startup_command: 'sleep infinity',
+    no_sync: !persistent
+  };
+  if (baseWorkspace) payload.base_workspace_id = baseWorkspace;
+  if (diskGB) payload.disk_gb = diskGB;
+
+  const response = await request('POST', '/api/v1/mags-jobs', payload);
+
+  if (!response.request_id) {
+    log('red', 'Failed to create VM:');
+    console.log(JSON.stringify(response, null, 2));
+    process.exit(1);
+  }
+
+  // Wait for VM to be ready
+  const maxAttempts = 60;
+  let attempt = 0;
+
+  while (attempt < maxAttempts) {
+    const status = await request('GET', `/api/v1/mags-jobs/${response.request_id}/status`);
+
+    if (status.status === 'running') {
+      log('green', `VM '${name}' created successfully${persistent ? ' (persistent)' : ' (local disk)'}`);
+      console.log(`  ID:  ${response.request_id}`);
+      console.log(`  SSH: mags ssh ${name}`);
+      if (!persistent) {
+        log('gray', `  Data is on local disk only. Use -p flag for S3 persistence.`);
+      }
+      return;
+    } else if (status.status === 'error') {
+      log('red', `VM creation failed: ${status.error_message || 'Unknown error'}`);
+      process.exit(1);
+    }
+
+    await sleep(500);
+    attempt++;
+  }
+
+  log('yellow', 'VM creation timed out, but may still be starting');
+  console.log(response.request_id);
+}
+
+async function runJob(args) {
+  let script = '';
+  let baseWorkspace = '';
+  let name = '';
+  let persistent = false;
+  let noSleep = false;
+  let ephemeral = false;
+  let enableUrl = false;
+  let port = 8080;
+  let startupCommand = '';
+  let diskGB = 0;
+  let fileArgs = [];
+
+  // Parse flags
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '-w':
+      case '--workspace':
+      case '-n':
+      case '--name':
+        name = args[++i];
+        break;
+      case '--base':
+        baseWorkspace = args[++i];
+        break;
+      case '-p':
+      case '--persistent':
+        persistent = true;
+        break;
+      case '--no-sleep':
+        noSleep = true;
+        break;
+      case '-e':
+      case '--ephemeral':
+        ephemeral = true;
+        break;
+      case '-f':
+      case '--file':
+        fileArgs.push(args[++i]);
+        break;
+      case '--url':
+        enableUrl = true;
+        break;
+      case '--port':
+        port = parseInt(args[++i]) || 8080;
+        break;
+      case '--disk':
+        diskGB = parseInt(args[++i]) || 0;
+        break;
+      case '--startup-command':
+        startupCommand = args[++i];
+        break;
+      default:
+        script = args.slice(i).join(' ');
+        i = args.length;
+    }
+  }
+
+  if (!script) {
+    log('red', 'Error: No script provided');
+    usage();
+  }
+
+  // Validate flag combinations
+  if (ephemeral && name) {
+    log('red', 'Error: Cannot use --ephemeral with --name; ephemeral VMs have no persistent storage');
+    process.exit(1);
+  }
+  if (ephemeral && persistent) {
+    log('red', 'Error: Cannot use --ephemeral with --persistent; ephemeral VMs are destroyed after execution');
+    process.exit(1);
+  }
+  if (ephemeral && baseWorkspace) {
+    log('red', 'Error: Cannot use --ephemeral with --base; ephemeral VMs have no workspace support');
+    process.exit(1);
+  }
+  if (noSleep && !persistent) {
+    log('red', 'Error: --no-sleep requires --persistent (-p)');
+    process.exit(1);
+  }
+
+  // Upload files if any
+  let fileIds = [];
+  if (fileArgs.length > 0) {
+    for (const filePath of fileArgs) {
+      log('blue', `Uploading ${filePath}...`);
+      const fileId = await uploadFile(filePath);
+      if (fileId) {
+        fileIds.push(fileId);
+        log('green', `Uploaded: ${filePath} (${fileId})`);
+      } else {
+        log('red', `Failed to upload: ${filePath}`);
+        process.exit(1);
+      }
+    }
+  }
+
+  log('blue', 'Submitting job...');
+
+  const payload = {
+    script,
+    type: 'inline',
+    persistent
+  };
+  if (noSleep) payload.no_sleep = true;
+  // name and workspace_id are always the same
+  if (name) {
+    payload.name = name;
+    if (!ephemeral) payload.workspace_id = name;
+  }
+  if (baseWorkspace) payload.base_workspace_id = baseWorkspace;
+  if (startupCommand) payload.startup_command = startupCommand;
+  if (fileIds.length > 0) payload.file_ids = fileIds;
+  if (diskGB) payload.disk_gb = diskGB;
+
+  const response = await request('POST', '/api/v1/mags-jobs', payload);
+
+  if (!response.request_id) {
+    log('red', 'Failed to submit job:');
+    console.log(JSON.stringify(response, null, 2));
+    process.exit(1);
+  }
+
+  const requestId = response.request_id;
+  log('green', `Job submitted: ${requestId}`);
+  if (name) log('blue', `Name: ${name}`);
+  if (baseWorkspace) log('blue', `Base workspace: ${baseWorkspace} (read-only)`);
+  if (persistent) log('yellow', 'Persistent: VM will stay alive');
+
+  // Poll for completion (200ms intervals, 600 attempts = 2 min timeout)
+  const maxAttempts = 600;
+  let attempt = 0;
+
+  while (attempt < maxAttempts) {
+    const status = await request('GET', `/api/v1/mags-jobs/${requestId}/status`);
+
+    if (status.status === 'completed') {
+      log('green', `Completed in ${status.script_duration_ms}ms`);
+      break;
+    } else if (status.status === 'running' && persistent) {
+      // If --url requested, wait until VM is actually assigned (vm_id populated)
+      if (enableUrl && !status.vm_id) {
+        process.stdout.write('.');
+        await sleep(200);
+        attempt++;
+        continue;
+      }
+
+      log('green', 'VM running');
+
+      if (enableUrl && status.subdomain) {
+        log('blue', `Enabling URL access on port ${port}...`);
+        const accessResp = await request('POST', `/api/v1/mags-jobs/${requestId}/access`, { port });
+        if (accessResp.success) {
+          log('green', `URL: https://${status.subdomain}.apps.magpiecloud.com`);
+        } else {
+          log('yellow', `Warning: Could not enable URL access${accessResp.error ? ': ' + accessResp.error : ''}`);
+        }
+      }
+      return;
+    } else if (status.status === 'error') {
+      log('red', 'Job failed');
+      console.log(JSON.stringify(status, null, 2));
+      process.exit(1);
+    }
+
+    process.stdout.write('.');
+    await sleep(200);
+    attempt++;
+  }
+
+  console.log('');
+
+  // Get logs
+  log('cyan', 'Output:');
+  const logsResp = await request('GET', `/api/v1/mags-jobs/${requestId}/logs`);
+  if (logsResp.logs) {
+    logsResp.logs
+      .filter(l => l.source === 'stdout' || l.source === 'stderr')
+      .forEach(l => console.log(l.message));
+  }
+}
+
+async function enableUrlAccess(nameOrId, port = 8080) {
+  if (!nameOrId) {
+    log('red', 'Error: Job name or ID required');
+    usage();
+  }
+
+  const requestId = await resolveJobId(nameOrId);
+  log('blue', `Enabling URL access on port ${port}...`);
+
+  const accessResp = await request('POST', `/api/v1/mags-jobs/${requestId}/access`, { port });
+
+  if (accessResp.success) {
+    const status = await request('GET', `/api/v1/mags-jobs/${requestId}/status`);
+    if (status.subdomain) {
+      log('green', `URL enabled: https://${status.subdomain}.apps.magpiecloud.com`);
+    } else {
+      log('green', 'URL access enabled');
+    }
+  } else {
+    log('red', 'Failed to enable URL access');
+    console.log(JSON.stringify(accessResp, null, 2));
+    process.exit(1);
+  }
+}
+
+async function urlAliasCommand(args) {
+  if (args.length === 0) {
+    log('red', 'Error: URL alias subcommand required');
+    console.log('\nUsage:');
+    console.log('  mags url alias <subdomain> <workspace> [--lfg]');
+    console.log('  mags url alias list');
+    console.log('  mags url alias remove <subdomain>');
+    process.exit(1);
+  }
+
+  const subcommand = args[0];
+
+  switch (subcommand) {
+    case 'list':
+    case 'ls':
+      await urlAliasList();
+      break;
+    case 'remove':
+    case 'rm':
+    case 'delete':
+      if (!args[1]) {
+        log('red', 'Error: Subdomain required');
+        console.log('\nUsage: mags url alias remove <subdomain>');
+        process.exit(1);
+      }
+      await urlAliasRemove(args[1]);
+      break;
+    default:
+      // mags url alias <subdomain> <workspace> [--lfg]
+      const subdomain = args[0];
+      const workspace = args[1];
+      if (!workspace) {
+        log('red', 'Error: Workspace required');
+        console.log('\nUsage: mags url alias <subdomain> <workspace> [--lfg]');
+        process.exit(1);
+      }
+      const useLfg = args.includes('--lfg');
+      await urlAliasCreate(subdomain, workspace, useLfg);
+      break;
+  }
+}
+
+async function urlAliasCreate(subdomain, workspaceId, useLfg) {
+  const domain = useLfg ? 'app.lfg.run' : 'apps.magpiecloud.com';
+  log('blue', `Creating URL alias: ${subdomain}.${domain} → workspace '${workspaceId}'...`);
+
+  const resp = await request('POST', '/api/v1/mags-url-aliases', {
+    subdomain,
+    workspace_id: workspaceId,
+    domain,
+  });
+
+  if (resp.error) {
+    log('red', `Error: ${resp.error}`);
+    process.exit(1);
+  }
+
+  if (resp.url) {
+    log('green', `URL alias created: ${resp.url}`);
+  } else {
+    log('green', `URL alias created: https://${subdomain}.${domain}`);
+  }
+}
+
+async function urlAliasList() {
+  const resp = await request('GET', '/api/v1/mags-url-aliases');
+  const aliases = resp.aliases || [];
+
+  if (aliases.length > 0) {
+    log('cyan', 'URL Aliases:\n');
+    aliases.forEach(a => {
+      console.log(`  ${colors.bold}${a.subdomain}${colors.reset}`);
+      console.log(`    URL: ${colors.green}${a.url}${colors.reset}`);
+      console.log(`    Workspace: ${a.workspace_id}  Domain: ${a.domain}`);
+      console.log('');
+    });
+    log('gray', `Total: ${aliases.length} alias(es)`);
+  } else {
+    log('yellow', 'No URL aliases found');
+  }
+}
+
+async function urlAliasRemove(subdomain) {
+  log('blue', `Removing URL alias '${subdomain}'...`);
+  const resp = await request('DELETE', `/api/v1/mags-url-aliases/${subdomain}`);
+  if (resp.error) {
+    log('red', `Error: ${resp.error}`);
+    process.exit(1);
+  }
+  log('green', resp.message || `URL alias '${subdomain}' removed`);
+}
+
+async function getStatus(nameOrId) {
+  if (!nameOrId) {
+    log('red', 'Error: Job name or ID required');
+    usage();
+  }
+  const requestId = await resolveJobId(nameOrId);
+  const status = await request('GET', `/api/v1/mags-jobs/${requestId}/status`);
+  console.log(JSON.stringify(status, null, 2));
+}
+
+async function getLogs(nameOrId) {
+  if (!nameOrId) {
+    log('red', 'Error: Job name or ID required');
+    usage();
+  }
+  const requestId = await resolveJobId(nameOrId);
+  const logsResp = await request('GET', `/api/v1/mags-jobs/${requestId}/logs`);
+  if (logsResp.logs) {
+    logsResp.logs.forEach(l => {
+      const levelColor = l.level === 'error' ? 'red' : l.level === 'warn' ? 'yellow' : 'gray';
+      console.log(`${colors[levelColor]}[${l.level}]${colors.reset} ${l.message}`);
+    });
+  }
+}
+
+async function listJobs() {
+  const resp = await request('GET', '/api/v1/mags-jobs?page=1&page_size=10');
+  if (resp.jobs && resp.jobs.length > 0) {
+    log('cyan', 'Recent Jobs:\n');
+    resp.jobs.forEach(job => {
+      const statusColor = job.status === 'completed' ? 'green'
+        : job.status === 'running' ? 'blue'
+        : job.status === 'error' ? 'red'
+        : 'yellow';
+      console.log(`${colors.gray}${job.request_id}${colors.reset}`);
+      console.log(`  Name: ${job.name || '-'}`);
+      console.log(`  Status: ${colors[statusColor]}${job.status}${colors.reset}`);
+      console.log(`  Workspace: ${job.workspace_id || '-'}`);
+      console.log(`  Duration: ${job.script_duration_ms ? job.script_duration_ms + 'ms' : '-'}`);
+      console.log(`  Created: ${job.created_at || '-'}`);
+      console.log('');
+    });
+  } else {
+    log('yellow', 'No jobs found');
+  }
+}
+
+async function stopJob(nameOrId) {
+  if (!nameOrId) {
+    log('red', 'Error: Job name or ID required');
+    usage();
+  }
+  const requestId = await resolveJobId(nameOrId);
+  log('blue', `Stopping job ${requestId}...`);
+  const resp = await request('POST', `/api/v1/mags-jobs/${requestId}/stop`);
+  if (resp.success) {
+    log('green', 'Job stopped');
+  } else {
+    log('red', 'Failed to stop job');
+    console.log(JSON.stringify(resp, null, 2));
+  }
+}
+
+async function setJobSettings(args) {
+  let nameOrId = null;
+  let noSleep = null;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--no-sleep') {
+      noSleep = true;
+    } else if (args[i] === '--sleep') {
+      noSleep = false;
+    } else if (!nameOrId) {
+      nameOrId = args[i];
+    }
+  }
+
+  if (!nameOrId) {
+    log('red', 'Error: Job name or ID required');
+    console.log(`\nUsage: mags set <name|id> [options]\n`);
+    console.log('Options:');
+    console.log('  --no-sleep   Never auto-sleep this VM');
+    console.log('  --sleep      Re-enable auto-sleep');
+    process.exit(1);
+  }
+
+  const payload = {};
+  if (noSleep !== null) payload.no_sleep = noSleep;
+
+  if (Object.keys(payload).length === 0) {
+    log('red', 'Error: No settings to update. Use --no-sleep or --sleep');
+    process.exit(1);
+  }
+
+  const requestId = await resolveJobId(nameOrId);
+  log('blue', `Updating settings for ${requestId}...`);
+  const resp = await request('PATCH', `/api/v1/mags-jobs/${requestId}`, payload);
+  if (resp.success) {
+    if (noSleep === true) log('green', 'VM set to never auto-sleep');
+    if (noSleep === false) log('green', 'VM set to auto-sleep when idle');
+  } else {
+    log('red', `Failed: ${resp.error || 'unknown error'}`);
+  }
+}
+
+async function resizeVM(args) {
+  let name = null;
+  let diskGB = 0;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--disk' && args[i + 1]) {
+      diskGB = parseInt(args[++i]) || 0;
+    } else if (!name) {
+      name = args[i];
+    }
+  }
+
+  if (!name || !diskGB) {
+    log('red', 'Error: Workspace name and --disk <GB> required');
+    console.log('\nUsage: mags resize <workspace> --disk <GB>\n');
+    process.exit(1);
+  }
+
+  // Find existing job for this workspace
+  const existingJob = await findWorkspaceJob(name);
+  if (existingJob) {
+    // Sync workspace before stopping (preserve files)
+    if (existingJob.status === 'running') {
+      log('blue', 'Syncing workspace before resize...');
+      await request('POST', `/api/v1/mags-jobs/${existingJob.request_id}/sync`);
+    }
+    log('blue', `Stopping existing VM...`);
+    await request('POST', `/api/v1/mags-jobs/${existingJob.request_id}/stop`);
+    // Brief wait for the stop to complete
+    await new Promise(r => setTimeout(r, 1000));
+  }
+
+  // Create new VM with the same workspace name and new disk size
+  log('blue', `Creating new VM with ${diskGB}GB disk...`);
+  const payload = {
+    script: 'sleep infinity',
+    type: 'inline',
+    persistent: true,
+    name: name,
+    workspace_id: name,
+    startup_command: 'sleep infinity',
+    disk_gb: diskGB,
+  };
+
+  const response = await request('POST', '/api/v1/mags-jobs', payload);
+  if (!response.request_id) {
+    log('red', 'Failed to create VM:');
+    console.log(JSON.stringify(response, null, 2));
+    process.exit(1);
+  }
+
+  log('green', `Resized '${name}' to ${diskGB}GB disk`);
+  log('gray', `Job: ${response.request_id}`);
+}
+
+async function syncWorkspace(nameOrId) {
+  if (!nameOrId) {
+    log('red', 'Error: Workspace name or job ID required');
+    console.log('\nUsage: mags sync <workspace|id>\n');
+    console.log('Syncs the workspace filesystem to S3 without stopping the VM.');
+    console.log('Use this after setting up a base image to persist your changes.\n');
+    console.log('Examples:');
+    console.log('  mags sync myproject');
+    console.log('  mags sync golden        # after setting up base image');
+    process.exit(1);
+  }
+
+  // Try to find a running job for this workspace
+  const existingJob = await findWorkspaceJob(nameOrId);
+  let requestId;
+
+  if (existingJob && existingJob.status === 'running') {
+    requestId = existingJob.request_id;
+  } else {
+    // Try as a direct job ID
+    requestId = await resolveJobId(nameOrId);
+  }
+
+  log('blue', `Syncing workspace...`);
+  const resp = await request('POST', `/api/v1/mags-jobs/${requestId}/sync`);
+  if (resp.success) {
+    log('green', 'Workspace synced to S3 successfully');
+  } else {
+    log('red', 'Failed to sync workspace');
+    if (resp.error) log('red', resp.error);
+    process.exit(1);
+  }
+}
+
+// Download a file from URL
+function downloadFile(url) {
+  return new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    const lib = urlObj.protocol === 'https:' ? https : http;
+
+    lib.get(url, (res) => {
+      // Handle redirects
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        downloadFile(res.headers.location).then(resolve).catch(reject);
+        return;
+      }
+
+      if (res.statusCode !== 200) {
+        reject(new Error(`Failed to download: HTTP ${res.statusCode}`));
+        return;
+      }
+
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve(data));
+    }).on('error', reject);
+  });
+}
+
+async function setupClaude() {
+  console.log(`
+${colors.cyan}${colors.bold}Mags Claude Code Skill Setup${colors.reset}
+
+This will install the Mags skill for Claude Code, allowing you to run
+scripts on instant VMs directly from Claude.
+`);
+
+  // Ask where to install
+  console.log(`${colors.bold}Installation options:${colors.reset}`);
+  console.log(`  1. Global (all projects) - ~/.claude/commands/`);
+  console.log(`  2. Current project only - ./.claude/commands/`);
+  console.log('');
+
+  const choice = await prompt(`${colors.bold}Choose installation type [1/2]: ${colors.reset}`);
+
+  let targetDir;
+  if (choice === '2') {
+    targetDir = path.join(process.cwd(), '.claude', 'commands');
+    log('blue', 'Installing to current project...');
+  } else {
+    targetDir = CLAUDE_GLOBAL_DIR;
+    log('blue', 'Installing globally...');
+  }
+
+  // Create directory if it doesn't exist
+  try {
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+  } catch (err) {
+    log('red', `Failed to create directory: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Download skill file
+  log('blue', `Downloading skill from ${SKILL_URL}...`);
+
+  try {
+    const skillContent = await downloadFile(SKILL_URL);
+
+    const targetFile = path.join(targetDir, 'mags.md');
+    fs.writeFileSync(targetFile, skillContent);
+
+    console.log('');
+    log('green', 'Mags skill installed successfully!');
+    log('gray', `Location: ${targetFile}`);
+    console.log('');
+    log('cyan', 'Next steps:');
+    console.log(`  1. Make sure you're logged in: ${colors.bold}mags login${colors.reset}`);
+    console.log(`  2. In Claude Code, use: ${colors.bold}/mags <your request>${colors.reset}`);
+    console.log('');
+    log('cyan', 'Example prompts:');
+    console.log('  /mags run echo Hello World');
+    console.log('  /mags create a python environment with numpy');
+    console.log('  /mags run a flask server and give me the URL');
+
+  } catch (err) {
+    log('red', `Failed to download skill: ${err.message}`);
+    log('gray', `You can manually download from: ${SKILL_URL}`);
+    process.exit(1);
+  }
+}
+
+// Upload file via multipart form data
+async function uploadFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    log('red', `File not found: ${filePath}`);
+    return null;
+  }
+
+  const fileName = path.basename(filePath);
+  const fileData = fs.readFileSync(filePath);
+  const boundary = '----MagsBoundary' + Date.now().toString(16);
+
+  // Build multipart body
+  const parts = [];
+  parts.push(`--${boundary}\r\n`);
+  parts.push(`Content-Disposition: form-data; name="file"; filename="${fileName}"\r\n`);
+  parts.push(`Content-Type: application/octet-stream\r\n\r\n`);
+  const header = Buffer.from(parts.join(''));
+  const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+  const body = Buffer.concat([header, fileData, footer]);
+
+  return new Promise((resolve, reject) => {
+    const url = new URL('/api/v1/mags-files', API_URL);
+    const isHttps = url.protocol === 'https:';
+    const lib = isHttps ? https : http;
+
+    const options = {
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname,
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${API_TOKEN}`,
+        'Content-Type': `multipart/form-data; boundary=${boundary}`,
+        'Content-Length': body.length
+      }
+    };
+
+    const req = lib.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.file_id) {
+            resolve(parsed.file_id);
+          } else {
+            resolve(null);
+          }
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+
+    req.on('error', () => resolve(null));
+    req.write(body);
+    req.end();
+  });
+}
+
+// Cron job management
+async function cronCommand(args) {
+  if (args.length === 0) {
+    log('red', 'Error: Cron subcommand required (add, list, remove, enable, disable)');
+    usage();
+    return;
+  }
+
+  const subcommand = args[0];
+  const subArgs = args.slice(1);
+
+  switch (subcommand) {
+    case 'add':
+      await cronAdd(subArgs);
+      break;
+    case 'list':
+    case 'ls':
+      await cronList();
+      break;
+    case 'remove':
+    case 'rm':
+    case 'delete':
+      if (!subArgs[0]) {
+        log('red', 'Error: Cron job ID required');
+        process.exit(1);
+      }
+      await cronRemove(subArgs[0]);
+      break;
+    case 'enable':
+      if (!subArgs[0]) {
+        log('red', 'Error: Cron job ID required');
+        process.exit(1);
+      }
+      await cronToggle(subArgs[0], true);
+      break;
+    case 'disable':
+      if (!subArgs[0]) {
+        log('red', 'Error: Cron job ID required');
+        process.exit(1);
+      }
+      await cronToggle(subArgs[0], false);
+      break;
+    default:
+      log('red', `Unknown cron subcommand: ${subcommand}`);
+      usage();
+  }
+}
+
+async function cronAdd(args) {
+  let cronName = '';
+  let schedule = '';
+  let workspace = '';
+  let persistent = false;
+  let script = '';
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--name':
+        cronName = args[++i];
+        break;
+      case '--schedule':
+        schedule = args[++i];
+        break;
+      case '-w':
+      case '--workspace':
+        workspace = args[++i];
+        break;
+      case '-p':
+      case '--persistent':
+        persistent = true;
+        break;
+      default:
+        script = args.slice(i).join(' ');
+        i = args.length;
+    }
+  }
+
+  if (!cronName) {
+    log('red', 'Error: --name is required for cron jobs');
+    process.exit(1);
+  }
+  if (!schedule) {
+    log('red', 'Error: --schedule is required (e.g. "0 * * * *")');
+    process.exit(1);
+  }
+  if (!script) {
+    log('red', 'Error: Script is required');
+    process.exit(1);
+  }
+
+  const payload = {
+    name: cronName,
+    cron_expression: schedule,
+    script,
+    persistent
+  };
+  if (workspace) payload.workspace_id = workspace;
+
+  const resp = await request('POST', '/api/v1/mags-cron', payload);
+  if (resp.id) {
+    log('green', `Cron job created: ${resp.id}`);
+    log('blue', `Name: ${cronName}`);
+    log('blue', `Schedule: ${schedule}`);
+    if (resp.next_run_at) log('blue', `Next run: ${resp.next_run_at}`);
+  } else {
+    log('red', 'Failed to create cron job:');
+    console.log(JSON.stringify(resp, null, 2));
+    process.exit(1);
+  }
+}
+
+async function cronList() {
+  const resp = await request('GET', '/api/v1/mags-cron');
+  if (resp.cron_jobs && resp.cron_jobs.length > 0) {
+    log('cyan', 'Cron Jobs:\n');
+    resp.cron_jobs.forEach(cron => {
+      const statusColor = cron.enabled ? 'green' : 'yellow';
+      console.log(`${colors.gray}${cron.id}${colors.reset}`);
+      console.log(`  Name: ${cron.name}`);
+      console.log(`  Schedule: ${cron.cron_expression}`);
+      console.log(`  Enabled: ${colors[statusColor]}${cron.enabled}${colors.reset}`);
+      console.log(`  Workspace: ${cron.workspace_id || '-'}`);
+      console.log(`  Runs: ${cron.run_count || 0}`);
+      console.log(`  Last Run: ${cron.last_run_at || '-'}`);
+      console.log(`  Next Run: ${cron.next_run_at || '-'}`);
+      console.log(`  Last Status: ${cron.last_status || '-'}`);
+      console.log('');
+    });
+  } else {
+    log('yellow', 'No cron jobs found');
+  }
+}
+
+async function cronRemove(id) {
+  const resp = await request('DELETE', `/api/v1/mags-cron/${id}`);
+  if (resp.success) {
+    log('green', 'Cron job deleted');
+  } else {
+    log('red', 'Failed to delete cron job');
+    console.log(JSON.stringify(resp, null, 2));
+  }
+}
+
+async function cronToggle(id, enabled) {
+  const resp = await request('PATCH', `/api/v1/mags-cron/${id}`, { enabled });
+  if (resp.id) {
+    log('green', `Cron job ${enabled ? 'enabled' : 'disabled'}`);
+    if (resp.next_run_at) log('blue', `Next run: ${resp.next_run_at}`);
+  } else {
+    log('red', `Failed to ${enabled ? 'enable' : 'disable'} cron job`);
+    console.log(JSON.stringify(resp, null, 2));
+  }
+}
+
+// Workspace management
+async function workspaceCommand(args) {
+  if (args.length === 0) {
+    log('red', 'Error: Workspace subcommand required (list, delete)');
+    console.log('\nUsage:');
+    console.log('  mags workspace list');
+    console.log('  mags workspace delete <workspace-id>');
+    process.exit(1);
+  }
+
+  const subcommand = args[0];
+
+  switch (subcommand) {
+    case 'list':
+    case 'ls':
+      await workspaceList();
+      break;
+    case 'delete':
+    case 'rm':
+    case 'remove':
+      if (!args[1]) {
+        log('red', 'Error: Workspace ID required');
+        console.log('\nUsage: mags workspace delete <workspace-id>');
+        process.exit(1);
+      }
+      await workspaceDelete(args[1]);
+      break;
+    default:
+      log('red', `Unknown workspace subcommand: ${subcommand}`);
+      console.log('\nUsage:');
+      console.log('  mags workspace list');
+      console.log('  mags workspace delete <workspace-id>');
+      process.exit(1);
+  }
+}
+
+async function workspaceList() {
+  const resp = await request('GET', '/api/v1/mags-workspaces');
+  if (resp.workspaces && resp.workspaces.length > 0) {
+    log('cyan', 'Workspaces:\n');
+    resp.workspaces.forEach(ws => {
+      const statusColor = ws.has_active ? 'blue' : 'yellow';
+      const status = ws.has_active ? 'active' : 'idle';
+      console.log(`  ${colors.bold}${ws.workspace_id}${colors.reset}`);
+      console.log(`    Jobs: ${ws.job_count}  Status: ${colors[statusColor]}${status}${colors.reset}  Last used: ${ws.last_used || '-'}`);
+      console.log('');
+    });
+    log('gray', `Total: ${resp.total} workspace(s)`);
+  } else {
+    log('yellow', 'No workspaces found');
+  }
+}
+
+async function workspaceDelete(workspaceId) {
+  log('blue', `Deleting workspace '${workspaceId}'...`);
+  const resp = await request('DELETE', `/api/v1/mags-workspaces/${workspaceId}`);
+  if (resp.success) {
+    log('green', resp.message || `Workspace '${workspaceId}' deleted`);
+  } else {
+    log('red', resp.error || 'Failed to delete workspace');
+    if (resp.error && resp.error.includes('active job')) {
+      log('gray', 'Stop active jobs first with: mags stop <job-id>');
+    }
+    process.exit(1);
+  }
+}
+
+async function browserSession(args) {
+  let workspace = '';
+  let name = '';
+
+  // Parse args: mags browser [workspace] [--name <n>]
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === '-n' || args[i] === '--name') && args[i + 1]) {
+      name = args[++i];
+    } else if (!workspace) {
+      workspace = args[i];
+    }
+  }
+
+  // Check for existing running/sleeping browser session with this workspace
+  if (workspace) {
+    const existingJob = await findWorkspaceJob(workspace);
+
+    if (existingJob && existingJob.status === 'running') {
+      // Check if it's already a browser session
+      const status = await request('GET', `/api/v1/mags-jobs/${existingJob.request_id}/status`);
+      if (status.browser_mode && status.debug_ws_url) {
+        log('green', 'Found existing browser session');
+        console.log('');
+        log('cyan', `CDP Endpoint: ${status.debug_ws_url}`);
+        console.log('');
+        log('gray', 'Connect with Playwright:');
+        console.log(`  const browser = await chromium.connectOverCDP('${status.debug_ws_url}');`);
+        console.log('');
+        log('gray', 'Connect with Puppeteer:');
+        console.log(`  const browser = await puppeteer.connect({ browserWSEndpoint: '${status.debug_ws_url}' });`);
+        return;
+      }
+    }
+  }
+
+  log('blue', 'Starting browser session...');
+
+  const payload = {
+    script: 'echo "Browser session ready"',
+    type: 'inline',
+    browser_mode: true,
+    persistent: true
+  };
+  if (workspace) payload.workspace_id = workspace;
+  if (name) payload.name = name;
+  if (!name && workspace) payload.name = `browser-${workspace}`;
+
+  const response = await request('POST', '/api/v1/mags-jobs', payload);
+
+  if (!response.request_id) {
+    log('red', 'Failed to start browser session:');
+    console.log(JSON.stringify(response, null, 2));
+    process.exit(1);
+  }
+
+  const requestId = response.request_id;
+  log('gray', `Job: ${requestId}`);
+
+  // Wait for VM + Chromium to be ready
+  log('blue', 'Waiting for Chromium to start...');
+  let status;
+  for (let i = 0; i < 90; i++) {
+    status = await request('GET', `/api/v1/mags-jobs/${requestId}/status`);
+    if (status.status === 'running' && status.debug_ws_url) {
+      break;
+    }
+    if (status.status === 'error') {
+      log('red', `Browser session failed: ${status.error_message || 'Unknown error'}`);
+      process.exit(1);
+    }
+    process.stdout.write('.');
+    await sleep(1000);
+  }
+  console.log('');
+
+  if (!status || !status.debug_ws_url) {
+    // VM is running but no CDP URL yet - it may still be initializing
+    if (status && status.status === 'running' && status.subdomain) {
+      const wsUrl = `wss://${status.subdomain}.apps.magpiecloud.com`;
+      log('green', 'Browser session ready!');
+      console.log('');
+      log('cyan', `CDP Endpoint: ${wsUrl}`);
+      console.log('');
+      log('gray', 'Connect with Playwright:');
+      console.log(`  const browser = await chromium.connectOverCDP('${wsUrl}');`);
+      console.log('');
+      log('gray', 'Connect with Puppeteer:');
+      console.log(`  const browser = await puppeteer.connect({ browserWSEndpoint: '${wsUrl}' });`);
+    } else {
+      log('yellow', 'Browser session started but CDP URL not yet available.');
+      log('yellow', `Check status with: mags status ${requestId}`);
+    }
+    return;
+  }
+
+  log('green', 'Browser session ready!');
+  console.log('');
+  log('cyan', `CDP Endpoint: ${status.debug_ws_url}`);
+  console.log('');
+  log('gray', 'Connect with Playwright:');
+  console.log(`  const browser = await chromium.connectOverCDP('${status.debug_ws_url}');`);
+  console.log('');
+  log('gray', 'Connect with Puppeteer:');
+  console.log(`  const browser = await puppeteer.connect({ browserWSEndpoint: '${status.debug_ws_url}' });`);
+  console.log('');
+  log('gray', `Stop with: mags stop ${workspace || requestId}`);
+}
+
+// WebSocket tunnel proxy — pipes stdin/stdout through a WebSocket to the agent SSH proxy.
+// Used as SSH ProxyCommand: ssh -o ProxyCommand="mags proxy <jobID>" root@mags-vm
+async function proxyTunnel(jobID) {
+  const url = new URL(`/api/v1/mags-jobs/${jobID}/tunnel`, API_URL);
+  const wsUrl = url.toString().replace(/^http/, 'ws');
+
+  // Dynamic import for WebSocket
+  let WebSocket;
+  try {
+    WebSocket = require('ws');
+  } catch {
+    if (typeof globalThis.WebSocket !== 'undefined') {
+      WebSocket = globalThis.WebSocket;
+    } else {
+      process.stderr.write('Error: ws package required. Run: npm install -g ws\n');
+      process.exit(1);
+    }
+  }
+
+  const ws = new WebSocket(wsUrl, {
+    headers: {
+      'Authorization': `Bearer ${API_TOKEN}`,
+    },
+    perMessageDeflate: false,
+    rejectUnauthorized: false,
+  });
+
+  // Buffer stdin data until WebSocket is open AND key is received
+  const pendingData = [];
+  let bridgeReady = false;
+  let firstMessage = true;
+
+  process.stdin.on('data', (data) => {
+    if (bridgeReady && ws.readyState === WebSocket.OPEN) {
+      ws.send(data);
+    } else {
+      pendingData.push(Buffer.from(data));
+    }
+  });
+
+  ws.on('open', () => {
+    // Don't flush yet — wait for first message (SSH key)
+  });
+
+  ws.on('message', (data, isBinary) => {
+    if (firstMessage && !isBinary) {
+      // First text message is the SSH private key — save to temp file
+      firstMessage = false;
+      const keyData = Buffer.from(data).toString('utf8');
+      if (keyData.startsWith('-----BEGIN')) {
+        const keyPath = path.join(os.tmpdir(), `mags_tunnel_key_${jobID}`);
+        fs.writeFileSync(keyPath, keyData, { mode: 0o600 });
+      }
+      // Now start the SSH data bridge
+      bridgeReady = true;
+      for (const buf of pendingData) {
+        ws.send(buf);
+      }
+      pendingData.length = 0;
+      return;
+    }
+    process.stdout.write(Buffer.from(data));
+  });
+
+  ws.on('close', () => {
+    process.exit(0);
+  });
+
+  ws.on('error', (err) => {
+    process.stderr.write(`Tunnel error: ${err.message}\n`);
+    process.exit(1);
+  });
+
+  process.stdin.on('end', () => {
+    ws.close();
+  });
+}
+
+// Fetch SSH key from tunnel endpoint (quick WS handshake)
+async function fetchTunnelKey(jobID) {
+  const WebSocket = require('ws');
+  const url = new URL(`/api/v1/mags-jobs/${jobID}/tunnel`, API_URL);
+  const wsUrl = url.toString().replace(/^http/, 'ws');
+
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(wsUrl, {
+      headers: { 'Authorization': `Bearer ${API_TOKEN}` },
+      perMessageDeflate: false,
+      rejectUnauthorized: false,
+    });
+
+    const timeout = setTimeout(() => {
+      ws.close();
+      reject(new Error('Tunnel key fetch timeout'));
+    }, 60000);
+
+    ws.on('message', (data, isBinary) => {
+      if (!isBinary) {
+        const key = Buffer.from(data).toString('utf8');
+        if (key.startsWith('-----BEGIN')) {
+          clearTimeout(timeout);
+          ws.close();
+          resolve(key);
+          return;
+        }
+      }
+      // Not a key message — shouldn't happen as first message
+      clearTimeout(timeout);
+      ws.close();
+      reject(new Error('No SSH key received from tunnel'));
+    });
+
+    ws.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+
+// Resolve a workspace name to a job ID, creating a new VM if needed
+async function resolveOrCreateJob(nameOrId) {
+  const existingJob = await findWorkspaceJob(nameOrId);
+
+  if (existingJob && existingJob.status === 'running') {
+    log('green', `Found running VM for '${nameOrId}'`);
+    return existingJob.request_id;
+  } else if (existingJob && existingJob.status === 'sleeping') {
+    log('yellow', `Waking sleeping VM for '${nameOrId}'...`);
+    return existingJob.request_id;
+  }
+
+  // No running/sleeping VM — start a new persistent one
+  log('blue', `Starting VM with workspace '${nameOrId}'...`);
+  const payload = {
+    script: 'echo "SSH session ready" && sleep 3600',
+    type: 'inline',
+    workspace_id: nameOrId,
+    persistent: true,
+    startup_command: 'sleep 3600'
+  };
+
+  const response = await request('POST', '/api/v1/mags-jobs', payload);
+  if (!response.request_id) {
+    log('red', 'Failed to start VM:');
+    console.log(JSON.stringify(response, null, 2));
+    process.exit(1);
+  }
+
+  const jobID = response.request_id;
+  log('gray', `Job: ${jobID}`);
+
+  log('blue', 'Waiting for VM...');
+  for (let i = 0; i < 60; i++) {
+    const status = await request('GET', `/api/v1/mags-jobs/${jobID}/status`);
+    if (status.status === 'running' && status.vm_id) break;
+    if (status.status === 'error') {
+      log('red', 'VM failed to start');
+      process.exit(1);
+    }
+    process.stdout.write('.');
+    await sleep(300);
+  }
+  console.log('');
+  return jobID;
+}
+
+// Get SSH key for a job (calls EnableAccess to set up agent proxy and get key)
+async function getSSHKey(jobID) {
+  const accessResp = await request('POST', `/api/v1/mags-jobs/${jobID}/access`, { port: 22 });
+  if (!accessResp.success) {
+    log('red', 'Failed to enable SSH access');
+    if (accessResp.error) log('red', accessResp.error);
+    process.exit(1);
+  }
+  return accessResp.ssh_private_key;
+}
+
+async function sshToJob(nameOrId) {
+  if (!nameOrId) {
+    log('red', 'Error: Workspace, job name, or job ID required');
+    console.log(`\nUsage: mags ssh <workspace|name|id>\n`);
+    console.log('Examples:');
+    console.log('  mags ssh myproject          # Auto-starts VM if needed');
+    console.log('  mags ssh 7bd12031-25ff...');
+    console.log('');
+    console.log('Get job names/IDs with: mags list');
+    process.exit(1);
+  }
+
+  const jobID = await resolveOrCreateJob(nameOrId);
+
+  // Fetch SSH key from tunnel endpoint (also warms up the agent proxy)
+  log('blue', 'Setting up tunnel...');
+  const sshKey = await fetchTunnelKey(jobID);
+  const magsPath = process.argv[1];
+  const keyFile = path.join(os.tmpdir(), `mags_tunnel_key_${jobID}`);
+  fs.writeFileSync(keyFile, sshKey, { mode: 0o600 });
+
+  log('green', `Connecting via secure tunnel...`);
+  console.log(`${colors.gray}(Use Ctrl+D or 'exit' to disconnect)${colors.reset}\n`);
+
+  const sshArgs = [
+    '-tt',
+    '-o', 'StrictHostKeyChecking=no',
+    '-o', 'UserKnownHostsFile=/dev/null',
+    '-o', 'LogLevel=ERROR',
+    '-o', `ProxyCommand=${magsPath} proxy ${jobID}`,
+    '-i', keyFile,
+    'root@mags-vm',
+  ];
+
+  const ssh = spawn('ssh', sshArgs, {
+    stdio: 'inherit'
+  });
+
+  ssh.on('error', (err) => {
+    try { fs.unlinkSync(keyFile); } catch (e) {}
+    if (err.code === 'ENOENT') {
+      log('red', 'SSH client not found. Please install OpenSSH.');
+    } else {
+      log('red', `SSH error: ${err.message}`);
+    }
+    process.exit(1);
+  });
+
+  ssh.on('close', (code) => {
+    try { fs.unlinkSync(keyFile); } catch (e) {}
+    if (code === 0) {
+      log('green', '\nSSH session ended');
+    } else {
+      log('yellow', `\nSSH session ended with code ${code}`);
+    }
+    process.exit(code || 0);
+  });
+}
+
+async function execOnJob(nameOrId, command) {
+  if (!nameOrId || !command) {
+    log('red', 'Error: Workspace and command required');
+    console.log(`\nUsage: mags exec <workspace|name|id> <command>\n`);
+    console.log('Examples:');
+    console.log('  mags exec myproject "ls -la"');
+    console.log('  mags exec myproject "node --version"');
+    process.exit(1);
+  }
+
+  // Find a running/sleeping job for this workspace
+  const existingJob = await findWorkspaceJob(nameOrId);
+
+  let jobID;
+  if (existingJob && existingJob.status === 'running') {
+    log('green', `Found running VM for '${nameOrId}'`);
+    jobID = existingJob.request_id;
+  } else if (existingJob && existingJob.status === 'sleeping') {
+    log('yellow', `Waking sleeping VM for '${nameOrId}'...`);
+    jobID = existingJob.request_id;
+  } else {
+    log('red', `No running or sleeping VM found for '${nameOrId}'`);
+    log('gray', `Start one with: mags new ${nameOrId}`);
+    process.exit(1);
+  }
+
+  // Fetch SSH key from tunnel endpoint (also warms up the agent proxy)
+  log('blue', 'Setting up tunnel...');
+  const sshKey = await fetchTunnelKey(jobID);
+  const magsPath = process.argv[1];
+  const keyFile = path.join(os.tmpdir(), `mags_tunnel_key_${jobID}`);
+  fs.writeFileSync(keyFile, sshKey, { mode: 0o600 });
+
+  const sshArgs = [
+    '-o', 'StrictHostKeyChecking=no',
+    '-o', 'UserKnownHostsFile=/dev/null',
+    '-o', 'LogLevel=ERROR',
+    '-o', `ProxyCommand=${magsPath} proxy ${jobID}`,
+    '-i', keyFile,
+  ];
+
+  // Wrap command to use chroot if overlay is mounted, with proper env
+  const escaped = command.replace(/'/g, "'\\''");
+  const wrappedCmd = `if [ -d /overlay/bin ]; then chroot /overlay /bin/sh -l -c 'cd /root 2>/dev/null; ${escaped}'; else cd /root 2>/dev/null; ${escaped}; fi`;
+  // Allocate TTY so interactive CLIs (e.g. claude) work
+  if (process.stdin.isTTY) {
+    sshArgs.push('-t');
+  }
+  sshArgs.push('root@mags-vm', wrappedCmd);
+
+  const ssh = spawn('ssh', sshArgs, { stdio: 'inherit' });
+
+  ssh.on('error', (err) => {
+    try { fs.unlinkSync(keyFile); } catch (e) {}
+    log('red', `SSH error: ${err.message}`);
+    process.exit(1);
+  });
+
+  ssh.on('close', (code) => {
+    try { fs.unlinkSync(keyFile); } catch (e) {}
+    process.exit(code || 0);
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  try {
+    switch (command) {
+      case 'login':
+        await login();
+        break;
+      case 'logout':
+        await logout();
+        break;
+      case 'whoami':
+        await whoami();
+        break;
+      case '--help':
+      case '-h':
+        usage();
+        break;
+      case '--version':
+      case '-v':
+        console.log('mags v1.8.8');
+        process.exit(0);
+        break;
+      case 'new':
+        await requireAuth();
+        await newVM(args.slice(1));
+        break;
+      case 'run':
+        await requireAuth();
+        await runJob(args.slice(1));
+        break;
+      case 'ssh':
+        await requireAuth();
+        await sshToJob(args[1]);
+        break;
+      case 'browser':
+        await requireAuth();
+        await browserSession(args.slice(1));
+        break;
+      case 'exec':
+        await requireAuth();
+        await execOnJob(args[1], args.slice(2).join(' '));
+        break;
+      case 'url':
+        await requireAuth();
+        if (args[1] === 'alias') {
+          await urlAliasCommand(args.slice(2));
+        } else {
+          await enableUrlAccess(args[1], parseInt(args[2]) || 8080);
+        }
+        break;
+      case 'status':
+        await requireAuth();
+        await getStatus(args[1]);
+        break;
+      case 'logs':
+        await requireAuth();
+        await getLogs(args[1]);
+        break;
+      case 'list':
+        await requireAuth();
+        await listJobs();
+        break;
+      case 'set':
+        await requireAuth();
+        await setJobSettings(args.slice(1));
+        break;
+      case 'stop':
+        await requireAuth();
+        await stopJob(args[1]);
+        break;
+      case 'resize':
+        await requireAuth();
+        await resizeVM(args.slice(1));
+        break;
+      case 'sync':
+        await requireAuth();
+        await syncWorkspace(args[1]);
+        break;
+      case 'cron':
+        await requireAuth();
+        await cronCommand(args.slice(1));
+        break;
+      case 'workspace':
+        await requireAuth();
+        await workspaceCommand(args.slice(1));
+        break;
+      case 'setup-claude':
+        await setupClaude();
+        break;
+      case 'proxy':
+        await proxyTunnel(args[1]);
+        break;
+      default:
+        if (!command) {
+          // No command - check if logged in
+          if (!API_TOKEN) {
+            await requireAuth();
+          } else {
+            usage();
+          }
+        } else {
+          log('red', `Unknown command: ${command}`);
+          usage();
+        }
+    }
+  } catch (err) {
+    log('red', `Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();