@magpiecloud/mags 1.8.12 → 1.8.14

package/README.md

@@ -6,7 +6,7 @@ Execute scripts instantly on Magpie's microVM infrastructure. VMs boot in <100ms
 
 Mags is a CLI and SDK for running scripts on ephemeral microVMs. Each execution gets its own isolated VM that:
 
-- Boots in <100ms (from warm pool)
+- Boots in ~300ms (from warm pool)
 - Supports optional S3-backed persistent workspaces (with `-p` flag)
 - Syncs /root directory automatically when persistence is enabled
 - Can expose public URLs for web services
@@ -419,7 +419,7 @@ mags run 'apk add ffmpeg imagemagick'
 
 | Metric | Value |
 |--------|-------|
-| Warm start | <100ms |
+| Warm start | ~300ms |
 | Cold start | ~4 seconds |
 | Script overhead | ~50ms |
 | Workspace sync | Every 30 seconds |

package/bin/mags.js

@@ -429,6 +429,23 @@ async function newVM(args) {
     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',
@@ -1449,123 +1466,225 @@ async function browserSession(args) {
   log('gray', `Stop with: mags stop ${workspace || requestId}`);
 }
 
-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);
+// 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);
+    }
   }
 
-  // First, try to find a running/sleeping job for this workspace
-  const existingJob = await findWorkspaceJob(nameOrId);
+  const ws = new WebSocket(wsUrl, {
+    headers: {
+      'Authorization': `Bearer ${API_TOKEN}`,
+    },
+    perMessageDeflate: false,
+    rejectUnauthorized: false,
+  });
 
-  let jobID;
+  // 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}'`);
-    jobID = existingJob.request_id;
+    return existingJob.request_id;
   } else if (existingJob && existingJob.status === 'sleeping') {
     log('yellow', `Waking sleeping VM for '${nameOrId}'...`);
-    jobID = existingJob.request_id;
-  } else {
-    // 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'
-    };
+    return existingJob.request_id;
+  }
 
-    const response = await request('POST', '/api/v1/mags-jobs', payload);
+  // 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'
+  };
 
-    if (!response.request_id) {
-      log('red', 'Failed to start VM:');
-      console.log(JSON.stringify(response, null, 2));
-      process.exit(1);
-    }
+  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);
+  }
 
-    jobID = response.request_id;
-    log('gray', `Job: ${jobID}`);
+  const jobID = response.request_id;
+  log('gray', `Job: ${jobID}`);
 
-    // Wait for VM to be ready (status=running AND vm_id assigned)
-    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);
+  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);
     }
-    console.log('');
+    process.stdout.write('.');
+    await sleep(300);
   }
+  console.log('');
+  return jobID;
+}
 
-  // Enable SSH access (port 22)
-  log('blue', 'Enabling SSH access...');
+// 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);
-    }
+    if (accessResp.error) log('red', accessResp.error);
     process.exit(1);
   }
+  return accessResp.ssh_private_key;
+}
 
-  const sshHost = accessResp.ssh_host;
-  const sshPort = accessResp.ssh_port;
-  const sshKey = accessResp.ssh_private_key;
-
-  if (!sshHost || !sshPort) {
-    log('red', 'SSH access enabled but no connection details returned');
-    console.log(JSON.stringify(accessResp, null, 2));
+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);
   }
 
-  log('green', `Connecting to ${sshHost}:${sshPort}...`);
+  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`);
 
-  // Build SSH arguments
   const sshArgs = [
-    '-tt',  // Force TTY allocation even when stdin isn't a terminal
+    '-tt',
     '-o', 'StrictHostKeyChecking=no',
     '-o', 'UserKnownHostsFile=/dev/null',
     '-o', 'LogLevel=ERROR',
-    '-p', sshPort.toString()
+    '-o', `ProxyCommand=${magsPath} proxy ${jobID}`,
+    '-i', keyFile,
+    'root@mags-vm',
   ];
 
-  // If API returned an SSH key, write it to a temp file and use it
-  let keyFile = null;
-  if (sshKey) {
-    keyFile = path.join(os.tmpdir(), `mags_ssh_${Date.now()}`);
-    fs.writeFileSync(keyFile, sshKey, { mode: 0o600 });
-    sshArgs.push('-i', keyFile);
-  }
-
-  sshArgs.push(`root@${sshHost}`);
-
   const ssh = spawn('ssh', sshArgs, {
-    stdio: 'inherit'  // Inherit stdin/stdout/stderr for interactive session
+    stdio: 'inherit'
   });
 
   ssh.on('error', (err) => {
-    if (keyFile) {
-      try { fs.unlinkSync(keyFile); } catch (e) {}
-    }
+    try { fs.unlinkSync(keyFile); } catch (e) {}
     if (err.code === 'ENOENT') {
       log('red', 'SSH client not found. Please install OpenSSH.');
-      log('gray', 'On macOS/Linux: ssh is usually pre-installed');
-      log('gray', 'On Windows: Install OpenSSH or use WSL');
     } else {
       log('red', `SSH error: ${err.message}`);
     }
@@ -1573,10 +1692,7 @@ async function sshToJob(nameOrId) {
   });
 
   ssh.on('close', (code) => {
-    // Clean up temp key file
-    if (keyFile) {
-      try { fs.unlinkSync(keyFile); } catch (e) {}
-    }
+    try { fs.unlinkSync(keyFile); } catch (e) {}
     if (code === 0) {
       log('green', '\nSSH session ended');
     } else {
@@ -1612,31 +1728,21 @@ async function execOnJob(nameOrId, command) {
     process.exit(1);
   }
 
-  // Enable SSH access
-  log('blue', 'Enabling SSH access...');
-  const accessResp = await request('POST', `/api/v1/mags-jobs/${jobID}/access`, { port: 22 });
-
-  if (!accessResp.success || !accessResp.ssh_host || !accessResp.ssh_port) {
-    log('red', 'Failed to enable SSH access');
-    if (accessResp.error) log('red', accessResp.error);
-    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 });
 
-  // Write SSH key to temp file
-  let keyFile = null;
   const sshArgs = [
     '-o', 'StrictHostKeyChecking=no',
     '-o', 'UserKnownHostsFile=/dev/null',
     '-o', 'LogLevel=ERROR',
-    '-p', accessResp.ssh_port.toString()
+    '-o', `ProxyCommand=${magsPath} proxy ${jobID}`,
+    '-i', keyFile,
   ];
 
-  if (accessResp.ssh_private_key) {
-    keyFile = path.join(os.tmpdir(), `mags_ssh_${Date.now()}`);
-    fs.writeFileSync(keyFile, accessResp.ssh_private_key, { mode: 0o600 });
-    sshArgs.push('-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`;
@@ -1644,18 +1750,18 @@ async function execOnJob(nameOrId, command) {
   if (process.stdin.isTTY) {
     sshArgs.push('-t');
   }
-  sshArgs.push(`root@${accessResp.ssh_host}`, wrappedCmd);
+  sshArgs.push('root@mags-vm', wrappedCmd);
 
   const ssh = spawn('ssh', sshArgs, { stdio: 'inherit' });
 
   ssh.on('error', (err) => {
-    if (keyFile) try { fs.unlinkSync(keyFile); } catch (e) {}
+    try { fs.unlinkSync(keyFile); } catch (e) {}
     log('red', `SSH error: ${err.message}`);
     process.exit(1);
   });
 
   ssh.on('close', (code) => {
-    if (keyFile) try { fs.unlinkSync(keyFile); } catch (e) {}
+    try { fs.unlinkSync(keyFile); } catch (e) {}
     process.exit(code || 0);
   });
 }
@@ -1751,6 +1857,9 @@ async function main() {
       case 'setup-claude':
         await setupClaude();
         break;
+      case 'proxy':
+        await proxyTunnel(args[1]);
+        break;
       default:
         if (!command) {
           // No command - check if logged in

package/index.js

@@ -333,7 +333,7 @@ class Mags {
   }
 
   /**
-   * Execute a command on an existing running/sleeping VM via SSH
+   * Execute a command on an existing running/sleeping VM via HTTP exec endpoint
    * @param {string} nameOrId - Job name, workspace ID, or request ID
    * @param {string} command - Command to execute
    * @param {object} options - Options
@@ -350,58 +350,12 @@ class Mags {
     }
 
     const requestId = job.request_id || job.id;
-    const access = await this.enableAccess(requestId, 22);
-
-    if (!access.success || !access.ssh_host) {
-      throw new MagsError(`Failed to enable SSH access: ${access.error || 'unknown error'}`);
-    }
-
-    const { execFile } = require('child_process');
-    const fs = require('fs');
-    const os = require('os');
-    const path = require('path');
-
-    const escaped = command.replace(/'/g, "'\\''");
-    const wrapped =
-      `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`;
-
-    let keyFile = null;
-    try {
-      const sshArgs = [
-        '-o', 'StrictHostKeyChecking=no',
-        '-o', 'UserKnownHostsFile=/dev/null',
-        '-o', 'LogLevel=ERROR',
-        '-p', String(access.ssh_port),
-      ];
-
-      if (access.ssh_private_key) {
-        keyFile = path.join(os.tmpdir(), `mags_ssh_${Date.now()}`);
-        fs.writeFileSync(keyFile, access.ssh_private_key, { mode: 0o600 });
-        sshArgs.push('-i', keyFile);
-      }
+    const resp = await this._request('POST', `/api/v1/mags-jobs/${requestId}/exec`, {
+      command,
+      timeout: Math.ceil(timeout / 1000),
+    });
 
-      sshArgs.push(`root@${access.ssh_host}`, wrapped);
-
-      return new Promise((resolve, reject) => {
-        execFile('ssh', sshArgs, { timeout, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
-          if (keyFile) try { fs.unlinkSync(keyFile); } catch {}
-          if (err && err.killed) {
-            reject(new MagsError(`Command timed out after ${timeout}ms`));
-          } else {
-            resolve({
-              exitCode: err ? err.code || 1 : 0,
-              output: stdout,
-              stderr: stderr,
-            });
-          }
-        });
-      });
-    } catch (e) {
-      if (keyFile) try { require('fs').unlinkSync(keyFile); } catch {}
-      throw e;
-    }
+    return { exitCode: resp.exit_code, output: resp.stdout, stderr: resp.stderr };
   }
 
   /**

package/nodejs/index.js

@@ -328,7 +328,7 @@ class Mags {
   }
 
   /**
-   * Execute a command on an existing running/sleeping VM via SSH
+   * Execute a command on an existing running/sleeping VM via HTTP exec endpoint
    * @param {string} nameOrId - Job name, workspace ID, or request ID
    * @param {string} command - Command to execute
    * @param {object} options - Options
@@ -345,58 +345,12 @@ class Mags {
     }
 
     const requestId = job.request_id || job.id;
-    const access = await this.enableAccess(requestId, 22);
-
-    if (!access.success || !access.ssh_host) {
-      throw new MagsError(`Failed to enable SSH access: ${access.error || 'unknown error'}`);
-    }
-
-    const { execFileSync, execFile } = require('child_process');
-    const fs = require('fs');
-    const os = require('os');
-    const path = require('path');
-
-    const escaped = command.replace(/'/g, "'\\''");
-    const wrapped =
-      `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`;
-
-    let keyFile = null;
-    try {
-      const sshArgs = [
-        '-o', 'StrictHostKeyChecking=no',
-        '-o', 'UserKnownHostsFile=/dev/null',
-        '-o', 'LogLevel=ERROR',
-        '-p', String(access.ssh_port),
-      ];
-
-      if (access.ssh_private_key) {
-        keyFile = path.join(os.tmpdir(), `mags_ssh_${Date.now()}`);
-        fs.writeFileSync(keyFile, access.ssh_private_key, { mode: 0o600 });
-        sshArgs.push('-i', keyFile);
-      }
+    const resp = await this._request('POST', `/api/v1/mags-jobs/${requestId}/exec`, {
+      command,
+      timeout: Math.ceil(timeout / 1000),
+    });
 
-      sshArgs.push(`root@${access.ssh_host}`, wrapped);
-
-      return new Promise((resolve, reject) => {
-        const proc = execFile('ssh', sshArgs, { timeout, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
-          if (keyFile) try { fs.unlinkSync(keyFile); } catch {}
-          if (err && err.killed) {
-            reject(new MagsError(`Command timed out after ${timeout}ms`));
-          } else {
-            resolve({
-              exitCode: err ? err.code || 1 : 0,
-              output: stdout,
-              stderr: stderr,
-            });
-          }
-        });
-      });
-    } catch (e) {
-      if (keyFile) try { require('fs').unlinkSync(keyFile); } catch {}
-      throw e;
-    }
+    return { exitCode: resp.exit_code, output: resp.stdout, stderr: resp.stderr };
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpiecloud/mags",
-  "version": "1.8.12",
+  "version": "1.8.14",
   "description": "Mags CLI - Execute scripts on Magpie's instant VM infrastructure",
   "main": "index.js",
   "bin": {
@@ -23,5 +23,8 @@
   "homepage": "https://mags.run",
   "engines": {
     "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
   }
 }

package/python/README.md

@@ -135,15 +135,19 @@ print(f"Jobs: {usage['total_jobs']}, VM seconds: {usage['vm_seconds']:.0f}")
 | `find_job(name_or_id)` | Find a running/sleeping job by name or workspace |
 | `exec(name_or_id, command)` | Run a command on an existing VM via SSH |
 | `stop(name_or_id)` | Stop a running job |
+| `url(name_or_id, port)` | Enable public URL and return full URL |
 | `resize(workspace, disk_gb)` | Resize a workspace's disk |
 | `status(request_id)` | Get job status |
 | `logs(request_id)` | Get job logs |
 | `list_jobs(page, page_size)` | List recent jobs |
-| `update_job(request_id, startup_command)` | Update job config |
+| `update_job(request_id, **opts)` | Update job config (`startup_command`, `no_sleep`) |
 | `enable_access(request_id, port)` | Enable URL or SSH access |
 | `usage(window_days)` | Get usage summary |
 | `upload_file(path)` | Upload a file, returns file ID |
 | `upload_files(paths)` | Upload multiple files |
+| `url_alias_create(sub, ws_id)` | Create a stable URL alias |
+| `url_alias_list()` | List URL aliases |
+| `url_alias_delete(sub)` | Delete a URL alias |
 | `cron_create(**opts)` | Create a cron job |
 | `cron_list()` | List cron jobs |
 | `cron_get(id)` | Get a cron job |
@@ -154,4 +158,4 @@ print(f"Jobs: {usage['total_jobs']}, VM seconds: {usage['vm_seconds']:.0f}")
 
 - Website: [mags.run](https://mags.run)
 - Node.js SDK: `npm install @magpiecloud/mags`
-- CLI: `go install` or download from releases
+- CLI: `npm install -g @magpiecloud/mags`

package/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "magpie-mags"
-version = "1.3.5"
+version = "1.3.7"
 description = "Mags SDK - Execute scripts on Magpie's instant VM infrastructure"
 readme = "README.md"
 license = {text = "MIT"}