@magpiecloud/mags 1.7.0 → 1.7.1

package/bin/mags.js

@@ -389,10 +389,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 +415,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);
 
@@ -1255,7 +1267,7 @@ async function main() {
         break;
       case 'new':
         await requireAuth();
-        await newVM(args[1]);
+        await newVM(args.slice(1));
         break;
       case 'run':
         await requireAuth();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpiecloud/mags",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "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