@magpiecloud/mags 1.6.1 → 1.7.0

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
@@ -215,6 +216,7 @@ ${colors.bold}Run Options:${colors.reset}
   -w, --workspace <id>            Use persistent workspace (S3 sync)
   -n, --name <name>               Set job name (for easier reference)
   -p, --persistent                Keep VM alive after script completes
+  --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)
   --url                           Enable public URL access (requires -p)
@@ -242,6 +244,8 @@ ${colors.bold}Examples:${colors.reset}
   mags run -e 'echo fast'           # Ephemeral (no S3 sync)
   mags run -f script.py 'python3 script.py'  # Upload + run file
   mags run -w myproject 'python3 script.py'
+  mags run --base golden 'npm test'           # Use golden as read-only base
+  mags run --base golden -w fork-1 'npm test' # Base + save changes to fork-1
   mags run -p --url 'python3 -m http.server 8080'
   mags run -n webapp -w webapp -p --url --port 3000 'npm start'
   mags workspace list               # List workspaces
@@ -436,6 +440,7 @@ async function newVM(name) {
 async function runJob(args) {
   let script = '';
   let workspace = '';
+  let baseWorkspace = '';
   let name = '';
   let persistent = false;
   let ephemeral = false;
@@ -455,6 +460,9 @@ async function runJob(args) {
       case '--name':
         name = args[++i];
         break;
+      case '--base':
+        baseWorkspace = args[++i];
+        break;
       case '-p':
       case '--persistent':
         persistent = true;
@@ -496,6 +504,10 @@ async function runJob(args) {
     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);
+  }
 
   // Upload files if any
   let fileIds = [];
@@ -523,6 +535,7 @@ async function runJob(args) {
   // Only set workspace_id if not ephemeral
   if (!ephemeral && workspace) payload.workspace_id = workspace;
   if (name) payload.name = name;
+  if (baseWorkspace) payload.base_workspace_id = baseWorkspace;
   if (startupCommand) payload.startup_command = startupCommand;
   if (fileIds.length > 0) payload.file_ids = fileIds;
 
@@ -538,6 +551,7 @@ async function runJob(args) {
   log('green', `Job submitted: ${requestId}`);
   if (name) log('blue', `Name: ${name}`);
   if (workspace) log('blue', `Workspace: ${workspace}`);
+  if (baseWorkspace) log('blue', `Base workspace: ${baseWorkspace} (read-only)`);
   if (persistent) log('yellow', 'Persistent: VM will stay alive');
 
   // Poll for completion
@@ -674,6 +688,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) => {
@@ -1202,7 +1250,7 @@ async function main() {
         break;
       case '--version':
       case '-v':
-        console.log('mags v1.6.1');
+        console.log('mags v1.7.0');
         process.exit(0);
         break;
       case 'new':
@@ -1237,6 +1285,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.1",
+  "version": "1.7.0",
   "description": "Mags CLI - Execute scripts on Magpie's instant VM infrastructure",
   "main": "index.js",
   "bin": {

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,279 @@ 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 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; start from a pre-configured workspace
+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 +664,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 {