@magpiecloud/mags 1.6.2 → 1.7.1

package/bin/mags.js

@@ -207,6 +207,7 @@ ${colors.bold}Commands:${colors.reset}
   list                            List recent jobs
   url <name|id> [port]            Enable URL access for a job
   stop <name|id>                  Stop a running job
+  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
@@ -388,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);
   }
 
@@ -403,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);
 
@@ -687,6 +700,40 @@ async function stopJob(nameOrId) {
   }
 }
 
+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) => {
@@ -1215,12 +1262,12 @@ async function main() {
         break;
       case '--version':
       case '-v':
-        console.log('mags v1.6.2');
+        console.log('mags v1.7.0');
         process.exit(0);
         break;
       case 'new':
         await requireAuth();
-        await newVM(args[1]);
+        await newVM(args.slice(1));
         break;
       case 'run':
         await requireAuth();
@@ -1250,6 +1297,10 @@ async function main() {
         await requireAuth();
         await stopJob(args[1]);
         break;
+      case 'sync':
+        await requireAuth();
+        await syncWorkspace(args[1]);
+        break;
       case 'cron':
         await requireAuth();
         await cronCommand(args.slice(1));

package/package.json

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

@@ -10,7 +10,7 @@
     />
     <meta name="api-base" content="https://api.magpiecloud.com" />
     <meta name="auth-base" content="https://api.magpiecloud.com" />
-    <link rel="stylesheet" href="styles.css?v=2" />
+    <link rel="stylesheet" href="styles.css?v=3" />
     <script src="env.js"></script>
   </head>
   <body>
@@ -174,317 +174,282 @@ console.log(result.status); // "completed"</code></pre>
         <div class="container">
           <div class="section-title">
             <p>Usage Patterns</p>
-            <h2>Click a pattern to see how it works.</h2>
+            <h2>Everything you can do with Mags.</h2>
           </div>
-          <div class="pattern-list">
-            <!-- Run a script -->
-            <div class="pattern-card open">
-              <div class="pattern-header">
-                <div>
-                  <h4>Run a script</h4>
-                  <p class="pattern-desc">Execute a one-off command in a fresh microVM.</p>
-                </div>
-                <span class="chevron">&#9660;</span>
-              </div>
-              <div class="pattern-body tab-group">
-                <div class="tab-bar">
-                  <button class="tab active" data-tab="p1-cli">CLI</button>
-                  <button class="tab" data-tab="p1-python">Python</button>
-                  <button class="tab" data-tab="p1-node">Node.js</button>
-                </div>
-                <div class="tab-content active" data-tab="p1-cli">
-                  <pre><code>mags run 'echo Hello World && uname -a'</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p1-python">
-                  <pre><code>result = m.run_and_wait("echo Hello World && uname -a")
-print(result["status"])    # "completed"
-print(result["exit_code"]) # 0</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p1-node">
-                  <pre><code>const result = await mags.runAndWait('echo Hello World && uname -a');
-console.log(result.status);   // "completed"
-console.log(result.exitCode); // 0</code></pre>
-                </div>
-              </div>
+          <div class="tab-group">
+            <div class="tab-bar">
+              <button class="tab active" data-tab="ref-cli">CLI</button>
+              <button class="tab" data-tab="ref-python">Python SDK</button>
+              <button class="tab" data-tab="ref-node">Node.js SDK</button>
             </div>
 
-            <!-- Persistent workspace -->
-            <div class="pattern-card">
-              <div class="pattern-header">
-                <div>
-                  <h4>Persistent workspace</h4>
-                  <p class="pattern-desc">Install packages once, reuse across runs. Files persist to S3.</p>
-                </div>
-                <span class="chevron">&#9660;</span>
+            <!-- ── CLI Reference ── -->
+            <div class="tab-content active" data-tab="ref-cli">
+              <div class="ref-section">
+                <h3>Install</h3>
+                <pre><code>npm install -g @magpiecloud/mags
+mags login</code></pre>
               </div>
-              <div class="pattern-body tab-group">
-                <div class="tab-bar">
-                  <button class="tab active" data-tab="p2-cli">CLI</button>
-                  <button class="tab" data-tab="p2-python">Python</button>
-                  <button class="tab" data-tab="p2-node">Node.js</button>
-                </div>
-                <div class="tab-content active" data-tab="p2-cli">
-                  <pre><code># First run: install dependencies
-mags run -w myproject 'pip install flask requests'
 
-# Second run: they're already there
-mags run -w myproject 'python3 -c "import flask; print(flask.__version__)"'</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p2-python">
-                  <pre><code># First run
-m.run_and_wait("pip install flask requests", workspace_id="myproject")
-
-# Second run: flask is already installed
-m.run_and_wait(
-    'python3 -c "import flask; print(flask.__version__)"',
-    workspace_id="myproject",
-)</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p2-node">
-                  <pre><code>// First run
-await mags.runAndWait('pip install flask requests', { workspaceId: 'myproject' });
-
-// Second run: flask is already installed
-await mags.runAndWait('python3 -c "import flask; print(flask.__version__)"', {
-  workspaceId: 'myproject',
-});</code></pre>
+              <div class="ref-section">
+                <h3>Commands</h3>
+                <div class="ref-table-wrap">
+                  <table class="ref-table">
+                    <thead><tr><th>Command</th><th>Description</th></tr></thead>
+                    <tbody>
+                      <tr><td><code>mags run &lt;script&gt;</code></td><td>Execute a script in a fresh microVM</td></tr>
+                      <tr><td><code>mags ssh &lt;workspace&gt;</code></td><td>SSH into a VM (auto-starts if needed)</td></tr>
+                      <tr><td><code>mags list</code></td><td>List recent jobs</td></tr>
+                      <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>
+                      <tr><td><code>mags cron add [opts] &lt;script&gt;</code></td><td>Create a scheduled cron job</td></tr>
+                      <tr><td><code>mags cron list</code></td><td>List cron jobs</td></tr>
+                      <tr><td><code>mags cron remove &lt;id&gt;</code></td><td>Delete a cron job</td></tr>
+                    </tbody>
+                  </table>
                 </div>
               </div>
-            </div>
 
-            <!-- SSH into a VM -->
-            <div class="pattern-card">
-              <div class="pattern-header">
-                <div>
-                  <h4>SSH into a VM</h4>
-                  <p class="pattern-desc">Open an interactive shell or run a command via SSH.</p>
+              <div class="ref-section">
+                <h3>Run Flags</h3>
+                <div class="ref-table-wrap">
+                  <table class="ref-table">
+                    <thead><tr><th>Flag</th><th>Description</th></tr></thead>
+                    <tbody>
+                      <tr><td><code>-w, --workspace &lt;id&gt;</code></td><td>Persist files to S3 across runs</td></tr>
+                      <tr><td><code>--base &lt;workspace&gt;</code></td><td>Mount a workspace read-only as a base image</td></tr>
+                      <tr><td><code>-p, --persistent</code></td><td>Keep VM alive after script (sleeps when idle)</td></tr>
+                      <tr><td><code>-e, --ephemeral</code></td><td>No S3 sync &mdash; fastest execution</td></tr>
+                      <tr><td><code>-f, --file &lt;path&gt;</code></td><td>Upload file(s) to VM (repeatable)</td></tr>
+                      <tr><td><code>-n, --name &lt;name&gt;</code></td><td>Name the job for easy reference</td></tr>
+                      <tr><td><code>--url</code></td><td>Enable public HTTPS URL (requires <code>-p</code>)</td></tr>
+                      <tr><td><code>--port &lt;port&gt;</code></td><td>Port to expose for URL (default: 8080)</td></tr>
+                      <tr><td><code>--startup-command &lt;cmd&gt;</code></td><td>Command to run when VM wakes from sleep</td></tr>
+                    </tbody>
+                  </table>
                 </div>
-                <span class="chevron">&#9660;</span>
               </div>
-              <div class="pattern-body tab-group">
-                <div class="tab-bar">
-                  <button class="tab active" data-tab="p3-cli">CLI</button>
-                  <button class="tab" data-tab="p3-python">Python</button>
-                  <button class="tab" data-tab="p3-rest">REST</button>
-                </div>
-                <div class="tab-content active" data-tab="p3-cli">
-                  <pre><code># Interactive shell
+
+              <div class="ref-section">
+                <h3>Examples</h3>
+                <pre><code># Run a one-off command
+mags run 'echo Hello World && uname -a'
+
+# Persistent workspace &mdash; files survive across runs
+mags run -w myproject 'pip install flask requests'
+mags run -w myproject 'python3 app.py'
+
+# 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
+
+# SSH into a workspace (auto-starts VM if needed)
 mags ssh myproject
 
-# Run a single command
-mags ssh myproject "cat /etc/os-release"</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p3-python">
-                  <pre><code># Start a persistent job, then enable SSH
-job = m.run("sleep 3600", workspace_id="myproject", persistent=True)
+# Persistent VM with public URL
+mags run -w webapp -p --url --port 8080 \
+  --startup-command 'python3 -m http.server 8080' \
+  'python3 -m http.server 8080'
 
-# Enable SSH access
-ssh = m.enable_access(job["request_id"], port=22)
-print(f"ssh root@{ssh['ssh_host']} -p {ssh['ssh_port']}")</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p3-rest">
-                  <pre><code>curl -X POST .../mags-jobs/$ID/access \
-  -H "Authorization: Bearer $TOKEN" \
-  -d '{"port": 22}'
-# Returns ssh_host, ssh_port, ssh_private_key</code></pre>
-                </div>
+# Upload files and run
+mags run -f script.py -f data.csv 'python3 script.py'
+
+# Ephemeral (fastest &mdash; no S3 sync)
+mags run -e 'uname -a && df -h'
+
+# Cron job
+mags cron add --name backup --schedule "0 0 * * *" \
+  -w backups 'tar czf backup.tar.gz /data'</code></pre>
               </div>
             </div>
 
-            <!-- Expose a URL -->
-            <div class="pattern-card">
-              <div class="pattern-header">
-                <div>
-                  <h4>Expose a public URL</h4>
-                  <p class="pattern-desc">Run a web server and get a public HTTPS URL. Auto-wakes from sleep.</p>
-                </div>
-                <span class="chevron">&#9660;</span>
+            <!-- ── Python SDK Reference ── -->
+            <div class="tab-content" data-tab="ref-python">
+              <div class="ref-section">
+                <h3>Install</h3>
+                <pre><code>pip install magpie-mags
+export MAGS_API_TOKEN="your-token"</code></pre>
               </div>
-              <div class="pattern-body tab-group">
-                <div class="tab-bar">
-                  <button class="tab active" data-tab="p4-cli">CLI</button>
-                  <button class="tab" data-tab="p4-python">Python</button>
-                  <button class="tab" data-tab="p4-node">Node.js</button>
-                </div>
-                <div class="tab-content active" data-tab="p4-cli">
-                  <pre><code>mags run -w webapp -p --url --port 8080 \
-  --startup-command "python3 -m http.server 8080" \
-  'echo "Hello" > index.html && python3 -m http.server 8080'
 
-# Output: https://&lt;subdomain&gt;.apps.magpiecloud.com</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p4-python">
-                  <pre><code>job = m.run(
-    'echo "Hello" > index.html && python3 -m http.server 8080',
-    workspace_id="webapp",
-    persistent=True,
-    startup_command="python3 -m http.server 8080",
-)
-# Wait for running, then enable access
-access = m.enable_access(job["request_id"], port=8080)
-print(access["url"])</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p4-node">
-                  <pre><code>const job = await mags.run('python3 -m http.server 8080', {
-  workspaceId: 'webapp',
-  persistent: true,
-  startupCommand: 'python3 -m http.server 8080',
-});
-const access = await mags.enableAccess(job.requestId, { port: 8080 });
-console.log(access.url);</code></pre>
+              <div class="ref-section">
+                <h3>Methods</h3>
+                <div class="ref-table-wrap">
+                  <table class="ref-table">
+                    <thead><tr><th>Method</th><th>Description</th></tr></thead>
+                    <tbody>
+                      <tr><td><code>run(script, **opts)</code></td><td>Submit a job (returns immediately)</td></tr>
+                      <tr><td><code>run_and_wait(script, **opts)</code></td><td>Submit + block until complete</td></tr>
+                      <tr><td><code>status(request_id)</code></td><td>Get job status</td></tr>
+                      <tr><td><code>logs(request_id)</code></td><td>Get job logs</td></tr>
+                      <tr><td><code>list_jobs()</code></td><td>List recent jobs</td></tr>
+                      <tr><td><code>enable_access(id, port)</code></td><td>Enable URL or SSH access</td></tr>
+                      <tr><td><code>upload_files(paths)</code></td><td>Upload files, returns file IDs</td></tr>
+                      <tr><td><code>list_workspaces()</code></td><td>List persistent workspaces</td></tr>
+                      <tr><td><code>delete_workspace(id)</code></td><td>Delete workspace + S3 data</td></tr>
+                      <tr><td><code>cron_create(**opts)</code></td><td>Create a cron job</td></tr>
+                      <tr><td><code>cron_list()</code></td><td>List cron jobs</td></tr>
+                      <tr><td><code>cron_delete(id)</code></td><td>Delete a cron job</td></tr>
+                      <tr><td><code>usage(window_days)</code></td><td>Get usage stats</td></tr>
+                    </tbody>
+                  </table>
                 </div>
               </div>
-            </div>
 
-            <!-- Upload files -->
-            <div class="pattern-card">
-              <div class="pattern-header">
-                <div>
-                  <h4>Upload files</h4>
-                  <p class="pattern-desc">Upload local files into the VM before your script runs.</p>
+              <div class="ref-section">
+                <h3>Run Options</h3>
+                <div class="ref-table-wrap">
+                  <table class="ref-table">
+                    <thead><tr><th>Parameter</th><th>Description</th></tr></thead>
+                    <tbody>
+                      <tr><td><code>workspace_id</code></td><td>Persist files to S3 across runs</td></tr>
+                      <tr><td><code>base_workspace_id</code></td><td>Mount a workspace read-only as base image</td></tr>
+                      <tr><td><code>persistent</code></td><td>Keep VM alive after script completes</td></tr>
+                      <tr><td><code>ephemeral</code></td><td>No S3 sync (fastest)</td></tr>
+                      <tr><td><code>file_ids</code></td><td>List of uploaded file IDs to include</td></tr>
+                      <tr><td><code>startup_command</code></td><td>Command to run when VM wakes</td></tr>
+                    </tbody>
+                  </table>
                 </div>
-                <span class="chevron">&#9660;</span>
               </div>
-              <div class="pattern-body tab-group">
-                <div class="tab-bar">
-                  <button class="tab active" data-tab="p5-cli">CLI</button>
-                  <button class="tab" data-tab="p5-python">Python</button>
-                  <button class="tab" data-tab="p5-rest">REST</button>
-                </div>
-                <div class="tab-content active" data-tab="p5-cli">
-                  <pre><code>mags run -f script.py -f data.csv \
-  'python3 script.py'</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p5-python">
-                  <pre><code>file_ids = m.upload_files(["script.py", "data.csv"])
-result = m.run_and_wait(
-    "python3 /uploads/script.py",
-    file_ids=file_ids,
-)</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p5-rest">
-                  <pre><code># 1. Upload file
-curl -X POST .../mags-files \
-  -H "Authorization: Bearer $TOKEN" \
-  -F "file=@script.py"
-# Returns: { "file_id": "abc123" }
-
-# 2. Use in job
-curl -X POST .../mags-jobs \
-  -d '{ "script": "python3 /uploads/script.py", "file_ids": ["abc123"], "type": "inline" }'</code></pre>
-                </div>
+
+              <div class="ref-section">
+                <h3>Examples</h3>
+                <pre><code>from mags import Mags
+m = Mags()  # reads MAGS_API_TOKEN from env
+
+# Run a command and wait
+result = m.run_and_wait("echo Hello World")
+print(result["status"])    # "completed"
+
+# Persistent workspace
+m.run_and_wait("pip install flask", workspace_id="myproject")
+m.run_and_wait("python3 app.py", workspace_id="myproject")
+
+# Base image
+m.run_and_wait("npm test", base_workspace_id="golden")
+m.run_and_wait("npm test", base_workspace_id="golden", workspace_id="fork-1")
+
+# SSH access
+job = m.run("sleep 3600", workspace_id="dev", persistent=True)
+ssh = m.enable_access(job["request_id"], port=22)
+print(f"ssh root@{ssh['ssh_host']} -p {ssh['ssh_port']}")
+
+# Public URL
+job = m.run("python3 -m http.server 8080",
+    workspace_id="webapp", persistent=True,
+    startup_command="python3 -m http.server 8080")
+access = m.enable_access(job["request_id"], port=8080)
+
+# Upload files
+file_ids = m.upload_files(["script.py", "data.csv"])
+m.run_and_wait("python3 /uploads/script.py", file_ids=file_ids)
+
+# Workspaces
+workspaces = m.list_workspaces()
+m.delete_workspace("myproject")
+
+# Cron
+m.cron_create(name="backup", cron_expression="0 0 * * *",
+    script="tar czf backup.tar.gz /data", workspace_id="backups")</code></pre>
               </div>
+              <p><a class="text-link" href="https://pypi.org/project/magpie-mags/" rel="noreferrer">View on PyPI &rarr;</a></p>
             </div>
 
-            <!-- Cron jobs -->
-            <div class="pattern-card">
-              <div class="pattern-header">
-                <div>
-                  <h4>Schedule cron jobs</h4>
-                  <p class="pattern-desc">Run scripts on a recurring schedule.</p>
-                </div>
-                <span class="chevron">&#9660;</span>
+            <!-- ── Node.js SDK Reference ── -->
+            <div class="tab-content" data-tab="ref-node">
+              <div class="ref-section">
+                <h3>Install</h3>
+                <pre><code>npm install @magpiecloud/mags
+export MAGS_API_TOKEN="your-token"</code></pre>
               </div>
-              <div class="pattern-body tab-group">
-                <div class="tab-bar">
-                  <button class="tab active" data-tab="p6-cli">CLI</button>
-                  <button class="tab" data-tab="p6-python">Python</button>
-                  <button class="tab" data-tab="p6-rest">REST</button>
-                </div>
-                <div class="tab-content active" data-tab="p6-cli">
-                  <pre><code>mags cron add \
-  --name "health-check" \
-  --schedule "0 */2 * * *" \
-  -w monitors \
-  'curl -sf https://myapp.com/health'
-
-mags cron list
-mags cron remove &lt;id&gt;</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p6-python">
-                  <pre><code>cron = m.cron_create(
-    name="health-check",
-    cron_expression="0 */2 * * *",
-    script='curl -sf https://myapp.com/health',
-    workspace_id="monitors",
-)
-print(cron["id"])
 
-# List and manage
-jobs = m.cron_list()
-m.cron_delete(cron["id"])</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p6-rest">
-                  <pre><code>curl -X POST .../mags-cron \
-  -H "Authorization: Bearer $TOKEN" \
-  -d '{
-    "name": "health-check",
-    "cron_expression": "0 */2 * * *",
-    "script": "curl -sf https://myapp.com/health",
-    "workspace_id": "monitors"
-  }'</code></pre>
+              <div class="ref-section">
+                <h3>Methods</h3>
+                <div class="ref-table-wrap">
+                  <table class="ref-table">
+                    <thead><tr><th>Method</th><th>Description</th></tr></thead>
+                    <tbody>
+                      <tr><td><code>run(script, opts)</code></td><td>Submit a job (returns immediately)</td></tr>
+                      <tr><td><code>runAndWait(script, opts)</code></td><td>Submit + block until complete</td></tr>
+                      <tr><td><code>status(requestId)</code></td><td>Get job status</td></tr>
+                      <tr><td><code>logs(requestId)</code></td><td>Get job logs</td></tr>
+                      <tr><td><code>listJobs()</code></td><td>List recent jobs</td></tr>
+                      <tr><td><code>enableAccess(id, { port })</code></td><td>Enable URL or SSH access</td></tr>
+                      <tr><td><code>uploadFile(path)</code></td><td>Upload a file, returns file ID</td></tr>
+                      <tr><td><code>cronCreate(opts)</code></td><td>Create a cron job</td></tr>
+                      <tr><td><code>cronList()</code></td><td>List cron jobs</td></tr>
+                      <tr><td><code>cronDelete(id)</code></td><td>Delete a cron job</td></tr>
+                      <tr><td><code>usage(windowDays)</code></td><td>Get usage stats</td></tr>
+                    </tbody>
+                  </table>
                 </div>
               </div>
-            </div>
 
-            <!-- Manage workspaces -->
-            <div class="pattern-card">
-              <div class="pattern-header">
-                <div>
-                  <h4>Manage workspaces</h4>
-                  <p class="pattern-desc">List and delete persistent workspaces.</p>
+              <div class="ref-section">
+                <h3>Run Options</h3>
+                <div class="ref-table-wrap">
+                  <table class="ref-table">
+                    <thead><tr><th>Parameter</th><th>Description</th></tr></thead>
+                    <tbody>
+                      <tr><td><code>workspaceId</code></td><td>Persist files to S3 across runs</td></tr>
+                      <tr><td><code>baseWorkspaceId</code></td><td>Mount a workspace read-only as base image</td></tr>
+                      <tr><td><code>persistent</code></td><td>Keep VM alive after script completes</td></tr>
+                      <tr><td><code>ephemeral</code></td><td>No S3 sync (fastest)</td></tr>
+                      <tr><td><code>fileIds</code></td><td>Array of uploaded file IDs to include</td></tr>
+                      <tr><td><code>startupCommand</code></td><td>Command to run when VM wakes</td></tr>
+                    </tbody>
+                  </table>
                 </div>
-                <span class="chevron">&#9660;</span>
               </div>
-              <div class="pattern-body tab-group">
-                <div class="tab-bar">
-                  <button class="tab active" data-tab="p7-cli">CLI</button>
-                  <button class="tab" data-tab="p7-python">Python</button>
-                  <button class="tab" data-tab="p7-rest">REST</button>
-                </div>
-                <div class="tab-content active" data-tab="p7-cli">
-                  <pre><code>mags workspace list
-mags workspace delete myproject</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p7-python">
-                  <pre><code>workspaces = m.list_workspaces()
-for ws in workspaces["workspaces"]:
-    print(ws["workspace_id"], ws["job_count"])
 
-m.delete_workspace("myproject")</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p7-rest">
-                  <pre><code># List workspaces
-curl .../mags-workspaces -H "Authorization: Bearer $TOKEN"
+              <div class="ref-section">
+                <h3>Examples</h3>
+                <pre><code>const Mags = require('@magpiecloud/mags');
+const mags = new Mags({ apiToken: process.env.MAGS_API_TOKEN });
 
-# Delete a workspace
-curl -X DELETE .../mags-workspaces/myproject \
-  -H "Authorization: Bearer $TOKEN"</code></pre>
-                </div>
-              </div>
-            </div>
+// Run a command and wait
+const result = await mags.runAndWait('echo Hello World');
+console.log(result.status);   // "completed"
 
-            <!-- Ephemeral run -->
-            <div class="pattern-card">
-              <div class="pattern-header">
-                <div>
-                  <h4>Ephemeral run (fastest)</h4>
-                  <p class="pattern-desc">Skip S3 sync for maximum speed. No workspace data is saved.</p>
-                </div>
-                <span class="chevron">&#9660;</span>
-              </div>
-              <div class="pattern-body tab-group">
-                <div class="tab-bar">
-                  <button class="tab active" data-tab="p8-cli">CLI</button>
-                  <button class="tab" data-tab="p8-python">Python</button>
-                </div>
-                <div class="tab-content active" data-tab="p8-cli">
-                  <pre><code>mags run -e 'uname -a && df -h'</code></pre>
-                </div>
-                <div class="tab-content" data-tab="p8-python">
-                  <pre><code>result = m.run_and_wait("uname -a && df -h", ephemeral=True)</code></pre>
-                </div>
+// Persistent workspace
+await mags.runAndWait('pip install flask', { workspaceId: 'myproject' });
+await mags.runAndWait('python3 app.py', { workspaceId: 'myproject' });
+
+// Base image
+await mags.runAndWait('npm test', { baseWorkspaceId: 'golden' });
+await mags.runAndWait('npm test', { baseWorkspaceId: 'golden', workspaceId: 'fork-1' });
+
+// SSH access
+const job = await mags.run('sleep 3600', { workspaceId: 'dev', persistent: true });
+const ssh = await mags.enableAccess(job.requestId, { port: 22 });
+console.log(`ssh root@${ssh.sshHost} -p ${ssh.sshPort}`);
+
+// Public URL
+const webJob = await mags.run('python3 -m http.server 8080', {
+  workspaceId: 'webapp', persistent: true,
+  startupCommand: 'python3 -m http.server 8080',
+});
+const access = await mags.enableAccess(webJob.requestId, { port: 8080 });
+console.log(access.url);
+
+// Upload files
+const fileId = await mags.uploadFile('script.py');
+await mags.runAndWait('python3 /uploads/script.py', { fileIds: [fileId] });
+
+// Cron
+await mags.cronCreate({
+  name: 'backup', cronExpression: '0 0 * * *',
+  script: 'tar czf backup.tar.gz /data', workspaceId: 'backups',
+});</code></pre>
               </div>
+              <p><a class="text-link" href="https://www.npmjs.com/package/@magpiecloud/mags" rel="noreferrer">View on npm &rarr;</a></p>
             </div>
           </div>
         </div>
@@ -702,7 +667,7 @@ console.log(result.logs);</code></pre>
       </div>
     </footer>
 
-    <script src="script.js?v=2"></script>
+    <script src="script.js?v=3"></script>
     <script>
     (function() {
       var token = localStorage.getItem('microvm-access-token');

package/website/styles.css

@@ -823,6 +823,69 @@ code {
   display: block;
 }
 
+/* ── Reference tables ─────────────────────────────────── */
+
+.ref-section {
+  margin-bottom: 2rem;
+}
+
+.ref-section h3 {
+  margin: 0 0 0.75rem;
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+.ref-table-wrap {
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+  background: var(--surface);
+}
+
+.ref-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.88rem;
+}
+
+.ref-table thead {
+  background: var(--surface-muted);
+}
+
+.ref-table th {
+  text-align: left;
+  padding: 0.65rem 1rem;
+  font-weight: 600;
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--text-muted);
+}
+
+.ref-table td {
+  padding: 0.6rem 1rem;
+  border-top: 1px solid var(--border);
+  vertical-align: top;
+}
+
+.ref-table td:first-child {
+  white-space: nowrap;
+}
+
+.ref-table code {
+  font-family: var(--mono);
+  font-size: 0.82rem;
+  background: var(--surface-muted);
+  padding: 0.15rem 0.4rem;
+  border-radius: 4px;
+}
+
+@media (max-width: 768px) {
+  .ref-table td:first-child {
+    white-space: normal;
+  }
+}
+
 /* ── Inline tab bar (for endpoint cards in api.html) ───── */
 
 .code-tabs {