@magpiecloud/mags 1.7.0 → 1.7.2

package/bin/mags.js

@@ -202,6 +202,7 @@ ${colors.bold}Commands:${colors.reset}
   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)
+  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
@@ -240,6 +241,7 @@ ${colors.bold}Examples:${colors.reset}
   mags login
   mags new myvm                     # Create VM, get ID
   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
@@ -389,10 +391,21 @@ To use Mags, you need to authenticate first.
 }
 
 // Create a new persistent VM
-async function newVM(name) {
+async function newVM(args) {
+  let name = null;
+  let baseWorkspace = null;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--base' && args[i + 1]) {
+      baseWorkspace = args[++i];
+    } else if (!name) {
+      name = args[i];
+    }
+  }
+
   if (!name) {
     log('red', 'Error: Name required');
-    console.log(`\nUsage: mags new <name>\n`);
+    console.log(`\nUsage: mags new <name> [--base <workspace>]\n`);
     process.exit(1);
   }
 
@@ -404,6 +417,7 @@ async function newVM(name) {
     workspace_id: name,
     startup_command: 'sleep infinity'
   };
+  if (baseWorkspace) payload.base_workspace_id = baseWorkspace;
 
   const response = await request('POST', '/api/v1/mags-jobs', payload);
 
@@ -1229,6 +1243,75 @@ async function sshToJob(nameOrId) {
   });
 }
 
+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);
+  }
+
+  // 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);
+  }
+
+  // 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()
+  ];
+
+  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
+  const wrappedCmd = `if [ -d /overlay/bin ]; then chroot /overlay /bin/sh -c '${command.replace(/'/g, "'\\''")}'; else /bin/sh -c '${command.replace(/'/g, "'\\''")}'; fi`;
+  sshArgs.push(`root@${accessResp.ssh_host}`, wrappedCmd);
+
+  const ssh = spawn('ssh', sshArgs, { stdio: 'inherit' });
+
+  ssh.on('error', (err) => {
+    if (keyFile) 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) {}
+    process.exit(code || 0);
+  });
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
@@ -1255,7 +1338,7 @@ async function main() {
         break;
       case 'new':
         await requireAuth();
-        await newVM(args[1]);
+        await newVM(args.slice(1));
         break;
       case 'run':
         await requireAuth();
@@ -1265,6 +1348,10 @@ async function main() {
         await requireAuth();
         await sshToJob(args[1]);
         break;
+      case 'exec':
+        await requireAuth();
+        await execOnJob(args[1], args.slice(2).join(' '));
+        break;
       case 'url':
         await requireAuth();
         await enableUrlAccess(args[1], parseInt(args[2]) || 8080);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpiecloud/mags",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Mags CLI - Execute scripts on Magpie's instant VM infrastructure",
   "main": "index.js",
   "bin": {

package/python/INTEGRATION.md

@@ -116,20 +116,39 @@ result = run_with_packages(
 
 ### With a pre-built base image
 
-For repeated runs, avoid re-installing packages every time by using a base workspace:
+For repeated runs, avoid re-installing packages every time by creating a base workspace and syncing it:
 
 ```python
 # One-time setup: create a base workspace with common packages
-m.run_and_wait(
+job = m.run(
     "pip install pandas numpy requests flask scikit-learn",
     workspace_id="python-base",
+    persistent=True,
 )
 
+# Wait for setup to finish, then sync to S3
+import time
+for _ in range(60):
+    status = m.status(job["request_id"])
+    if status["status"] == "running":
+        break
+    time.sleep(1)
+
+# Force sync — persists everything to S3 immediately
+m.sync(job["request_id"])
+
 # Every subsequent run inherits the base (read-only, no install needed)
 result = m.run_and_wait(
     "python3 -c 'import pandas; print(pandas.__version__)'",
     base_workspace_id="python-base",
 )
+
+# Fork: load base, save changes to a new workspace
+result = m.run_and_wait(
+    "pip install torch",
+    base_workspace_id="python-base",
+    workspace_id="python-ml",
+)
 ```
 
 ---
@@ -259,7 +278,7 @@ def run_data_pipeline(sql_query, workspace_id="etl-pipeline"):
 python3 << 'PYEOF'
 import sqlite3, json
 
-conn = sqlite3.connect("/workspace/data.db")
+conn = sqlite3.connect("/root/data.db")
 cursor = conn.execute("{sql_query}")
 rows = cursor.fetchall()
 print(json.dumps(rows))
@@ -430,7 +449,7 @@ cron = m.cron_create(
 m.cron_create(
     name="db-backup",
     cron_expression="0 2 * * *",
-    script="pg_dump $DATABASE_URL | gzip > /workspace/backup-$(date +%F).sql.gz",
+    script="pg_dump $DATABASE_URL | gzip > /root/backup-$(date +%F).sql.gz",
     workspace_id="backups",
 )
 
@@ -462,17 +481,17 @@ def deploy_preview(user_id, html_content):
     import shlex
 
     script = f"""
-mkdir -p /workspace/site
-cat > /workspace/site/index.html << 'HTMLEOF'
+mkdir -p /root/site
+cat > /root/site/index.html << 'HTMLEOF'
 {html_content}
 HTMLEOF
-cd /workspace/site && python3 -m http.server 8080
+cd /root/site && python3 -m http.server 8080
 """
     job = m.run(
         script,
         workspace_id=f"preview-{user_id}",
         persistent=True,
-        startup_command="cd /workspace/site && python3 -m http.server 8080",
+        startup_command="cd /root/site && python3 -m http.server 8080",
     )
 
     # Wait for VM to start
@@ -528,6 +547,40 @@ m.run_and_wait("echo 'no persistence'", ephemeral=True)
 | Read-only base | omit | `"my-base"` | Base mounted read-only. Changes discarded. |
 | Fork | `"fork-1"` | `"my-base"` | Starts from base, saves to `fork-1`. |
 
+### Syncing workspaces
+
+Workspaces sync to S3 automatically when a job completes. For persistent VMs (`persistent=True`), workspaces also sync every 30 seconds and on sleep.
+
+Use `m.sync()` to force an immediate sync without stopping the VM — useful for persisting a base image you've just set up:
+
+```python
+# Set up a base workspace on a persistent VM
+job = m.run(
+    "pip install pandas numpy scikit-learn",
+    workspace_id="ml-base",
+    persistent=True,
+)
+
+# Wait for the install to finish
+import time
+for _ in range(60):
+    status = m.status(job["request_id"])
+    if status["status"] == "running":
+        break
+    time.sleep(1)
+
+# Force sync — base image is now available for other jobs
+m.sync(job["request_id"])
+
+# List and manage workspaces
+workspaces = m.list_workspaces()
+for ws in workspaces.get("workspaces", []):
+    print(f"{ws['workspace_id']} — {ws['job_count']} jobs")
+
+# Delete a workspace (removes stored data from S3)
+m.delete_workspace("old-workspace")
+```
+
 ---
 
 ## File Uploads

package/python/src/mags/client.py

@@ -241,6 +241,14 @@ class Mags:
         """
         return self._request("DELETE", f"/mags-workspaces/{workspace_id}")
 
+    def sync(self, request_id: str) -> dict:
+        """Sync a running job's workspace to S3 without stopping the VM.
+
+        Use this to persist workspace changes immediately, e.g. after
+        setting up a base image.
+        """
+        return self._request("POST", f"/mags-jobs/{request_id}/sync")
+
     # ── cron jobs ────────────────────────────────────────────────────
 
     def cron_create(

package/website/index.html

@@ -203,6 +203,7 @@ mags login</code></pre>
                       <tr><td><code>mags status &lt;id&gt;</code></td><td>Get job status</td></tr>
                       <tr><td><code>mags logs &lt;id&gt;</code></td><td>Get job output</td></tr>
                       <tr><td><code>mags stop &lt;id&gt;</code></td><td>Stop a running job</td></tr>
+                      <tr><td><code>mags sync &lt;workspace&gt;</code></td><td>Sync workspace to S3 (without stopping VM)</td></tr>
                       <tr><td><code>mags url &lt;id&gt; [port]</code></td><td>Enable public URL access</td></tr>
                       <tr><td><code>mags workspace list</code></td><td>List persistent workspaces</td></tr>
                       <tr><td><code>mags workspace delete &lt;id&gt;</code></td><td>Delete workspace + S3 data</td></tr>
@@ -243,7 +244,9 @@ mags run 'echo Hello World && uname -a'
 mags run -w myproject 'pip install flask requests'
 mags run -w myproject 'python3 app.py'
 
-# Base image &mdash; start from a pre-configured workspace
+# Base image &mdash; create a golden image, sync it, then reuse
+mags run -w golden -p 'apt install -y nodejs && npm install -g typescript'
+mags sync golden                                # persist to S3
 mags run --base golden 'npm test'               # read-only, changes discarded
 mags run --base golden -w fork-1 'npm test'     # fork: load golden, save to fork-1