npm - @magpiecloud/mags - Versions diffs - 1.8.11 → 1.8.13 - Mend

@magpiecloud/mags 1.8.11 → 1.8.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md +16 -12
package/bin/mags.js +31 -5
package/index.js +7 -2
package/nodejs/README.md +10 -4
package/package.json +1 -1
package/python/README.md +7 -3
package/python/dist/magpie_mags-1.3.5-py3-none-any.whl +0 -0
package/python/dist/magpie_mags-1.3.5.tar.gz +0 -0
package/python/pyproject.toml +1 -1
package/python/src/magpie_mags.egg-info/PKG-INFO +2 -2
package/python/src/mags/client.py +13 -3
package/website/api.html +137 -8
package/website/cookbook.html +1 -1
package/website/index.html +149 -95
package/website/llms.txt +76 -31
package/website/mags.md +3 -2
package/python/dist/magpie_mags-1.3.4-py3-none-any.whl +0 -0
package/python/dist/magpie_mags-1.3.4.tar.gz +0 -0

package/website/index.html CHANGED Viewed

@@ -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=6" />
+    <link rel="stylesheet" href="styles.css?v=7" />
     <script src="env.js"></script>
   </head>
   <body>
@@ -59,10 +59,9 @@
             </div>
             <div class="tab-content active" data-tab="hero-cli">
               <pre><code>mags run 'echo Hello World'
-mags run -w myproject 'pip install flask'
-mags ssh myproject</code></pre>
-              <p class="card-note">Run a script, keep your files, then jump in with SSH.</p>
+mags run -w myproject -p 'pip install flask'
+mags new dev && mags ssh dev</code></pre>
+              <p class="card-note">Run a script, persist your files to the cloud, then jump in with SSH.</p>
             </div>
             <div class="tab-content" data-tab="hero-python">
               <pre><code>from mags import Mags
@@ -112,7 +111,7 @@ console.log(result.logs);</code></pre>
                 <article class="card" data-reveal>
                   <h3>3. Run</h3>
                   <pre><code>mags run 'echo Hello World'</code></pre>
-                  <p>Add <code>-w myproject</code> to keep files between runs, synced to the cloud.</p>
+                  <p>Add <code>-w myproject -p</code> to persist files to the cloud between runs.</p>
                 </article>
               </div>
             </div>
@@ -186,14 +185,45 @@ mags login</code></pre>
               </div>
               <div class="ref-section">
-                <h3>Commands</h3>
+                <h3>Running Scripts</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>Run a script in a fresh sandbox. Fastest &mdash; no workspace, no persistence.</td></tr>
+                      <tr><td><code>mags run -w &lt;name&gt; &lt;script&gt;</code></td><td>Run with a named workspace. Data stays on the VM only &mdash; deleted after 10 min idle.</td></tr>
+                      <tr><td><code>mags run -w &lt;name&gt; -p &lt;script&gt;</code></td><td>Run with a persistent workspace. Files synced to S3 and survive across runs indefinitely.</td></tr>
+                      <tr><td><code>mags run --url --port &lt;port&gt; &lt;script&gt;</code></td><td>Request a public HTTPS URL for your sandbox (requires <code>-p</code>).</td></tr>
+                      <tr><td><code>mags run --no-sleep &lt;script&gt;</code></td><td>Keep sandbox running 24/7, never auto-sleep (requires <code>-p</code>).</td></tr>
+                      <tr><td><code>mags run -e &lt;script&gt;</code></td><td>Ephemeral &mdash; no workspace at all, fastest possible execution.</td></tr>
+                      <tr><td><code>mags run --base &lt;workspace&gt; &lt;script&gt;</code></td><td>Use an existing workspace as a read-only base image (OverlayFS).</td></tr>
+                      <tr><td><code>mags run -f &lt;file&gt; &lt;script&gt;</code></td><td>Upload file(s) into the sandbox before running (repeatable).</td></tr>
+                    </tbody>
+                  </table>
+                </div>
+              </div>
+              <div class="ref-section">
+                <h3>Sandboxes</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 new &lt;name&gt;</code></td><td>Create a new sandbox. Workspace lives on local disk only.</td></tr>
+                      <tr><td><code>mags new &lt;name&gt; -p</code></td><td>Create a sandbox with persistent workspace &mdash; synced to S3.</td></tr>
+                      <tr><td><code>mags exec &lt;name&gt; &lt;cmd&gt;</code></td><td>Execute a command on an existing sandbox.</td></tr>
+                      <tr><td><code>mags ssh &lt;name&gt;</code></td><td>SSH into a sandbox. Auto-starts if sleeping or stopped.</td></tr>
+                    </tbody>
+                  </table>
+                </div>
+              </div>
+              <div class="ref-section">
+                <h3>Management</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 sandbox</td></tr>
-                      <tr><td><code>mags ssh &lt;workspace&gt;</code></td><td>SSH into a sandbox (auto-starts if needed)</td></tr>
-                      <tr><td><code>mags exec &lt;workspace&gt; &lt;cmd&gt;</code></td><td>Run a command on an existing sandbox</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>
@@ -201,10 +231,16 @@ mags login</code></pre>
                       <tr><td><code>mags set &lt;id&gt; [options]</code></td><td>Update VM settings (e.g. <code>--no-sleep</code>, <code>--sleep</code>)</td></tr>
                       <tr><td><code>mags sync &lt;workspace&gt;</code></td><td>Sync workspace to the cloud now</td></tr>
                       <tr><td><code>mags url &lt;id&gt; [port]</code></td><td>Enable public URL access</td></tr>
+                      <tr><td><code>mags resize &lt;workspace&gt; --disk &lt;GB&gt;</code></td><td>Resize workspace disk</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 + cloud data</td></tr>
+                      <tr><td><code>mags url alias &lt;sub&gt; &lt;workspace&gt;</code></td><td>Create a stable URL alias</td></tr>
+                      <tr><td><code>mags url alias list</code></td><td>List URL aliases</td></tr>
+                      <tr><td><code>mags url alias remove &lt;sub&gt;</code></td><td>Delete a URL alias</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 enable &lt;id&gt;</code></td><td>Enable a cron job</td></tr>
+                      <tr><td><code>mags cron disable &lt;id&gt;</code></td><td>Disable a cron job</td></tr>
                       <tr><td><code>mags cron remove &lt;id&gt;</code></td><td>Delete a cron job</td></tr>
                     </tbody>
                   </table>
@@ -212,20 +248,14 @@ mags login</code></pre>
               </div>
               <div class="ref-section">
-                <h3>Run Flags</h3>
+                <h3>Additional 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>Keep files across runs (synced to the cloud)</td></tr>
-                      <tr><td><code>--base &lt;workspace&gt;</code></td><td>Clone a workspace as a starting point (read-only)</td></tr>
-                      <tr><td><code>-p, --persistent</code></td><td>Keep sandbox alive after script (sleeps when idle)</td></tr>
-                      <tr><td><code>--no-sleep</code></td><td>Never auto-sleep this VM (requires <code>-p</code>)</td></tr>
-                      <tr><td><code>-e, --ephemeral</code></td><td>No cloud sync &mdash; fastest execution</td></tr>
-                      <tr><td><code>-f, --file &lt;path&gt;</code></td><td>Upload file(s) into the sandbox (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>-n, --name &lt;name&gt;</code></td><td>Alias for <code>-w</code></td></tr>
+                      <tr><td><code>-e, --ephemeral</code></td><td>No workspace at all, fastest possible execution</td></tr>
+                      <tr><td><code>--base &lt;workspace&gt;</code></td><td>Use an existing workspace as a read-only base image</td></tr>
                       <tr><td><code>--disk &lt;GB&gt;</code></td><td>Custom disk size in GB (default: 2)</td></tr>
                       <tr><td><code>--startup-command &lt;cmd&gt;</code></td><td>Command to run when sandbox wakes from sleep</td></tr>
                     </tbody>
@@ -235,39 +265,25 @@ mags login</code></pre>
               <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 cloud
-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 sandbox if needed)
-mags ssh myproject
-# Run a command on an existing sandbox
-mags exec myproject 'node --version'
-# Persistent sandbox with public URL
-mags run -w webapp -p --url --port 8080 \
+                <pre><code># Persistent workspace &mdash; install packages, then run your app
+mags run -w myproject -p 'pip install flask requests'
+mags run -w myproject -p 'python3 app.py'
+# Golden image &mdash; create once, fork many times
+mags run -w golden -p 'apk add nodejs npm && npm install -g typescript'
+mags sync golden
+mags run --base golden -w fork-1 -p 'npm test'
+# Interactive sandbox with SSH
+mags new dev -p
+mags ssh dev
+mags exec dev 'node --version'
+# Always-on web server with public URL
+mags run -w webapp -p --no-sleep --url --port 8080 \
   --startup-command 'python3 -m http.server 8080' \
   'python3 -m http.server 8080'
-# Always-on sandbox (never auto-sleeps)
-mags run -w worker -p --no-sleep 'python3 worker.py'
-# Upload files and run
-mags run -f script.py -f data.csv 'python3 script.py'
-# Ephemeral (fastest &mdash; no cloud 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>
@@ -290,21 +306,28 @@ export MAGS_API_TOKEN="your-token"</code></pre>
                     <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>new(name)</code></td><td>Create persistent VM workspace</td></tr>
-                      <tr><td><code>exec(name, command)</code></td><td>Run command on existing sandbox</td></tr>
+                      <tr><td><code>new(name, **opts)</code></td><td>Create VM sandbox (pass <code>persistent=True</code> for S3)</td></tr>
+                      <tr><td><code>exec(name, command)</code></td><td>Run command on existing sandbox via SSH</td></tr>
                       <tr><td><code>stop(name_or_id)</code></td><td>Stop a running job</td></tr>
                       <tr><td><code>find_job(name_or_id)</code></td><td>Find job by name or workspace</td></tr>
                       <tr><td><code>url(name_or_id, port)</code></td><td>Enable public URL access</td></tr>
+                      <tr><td><code>resize(workspace, disk_gb)</code></td><td>Resize workspace disk</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>update_job(request_id, **opts)</code></td><td>Update job settings (<code>no_sleep</code>, <code>startup_command</code>)</td></tr>
                       <tr><td><code>enable_access(id, port)</code></td><td>Enable URL or SSH access (low-level)</td></tr>
+                      <tr><td><code>upload_file(path)</code></td><td>Upload a file, returns file ID</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 + cloud data</td></tr>
                       <tr><td><code>sync(request_id)</code></td><td>Sync workspace to S3 now</td></tr>
+                      <tr><td><code>url_alias_create(sub, ws_id)</code></td><td>Create a stable URL alias</td></tr>
+                      <tr><td><code>url_alias_list()</code></td><td>List URL aliases</td></tr>
+                      <tr><td><code>url_alias_delete(sub)</code></td><td>Delete a URL alias</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_update(id, **opts)</code></td><td>Update a cron job</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>
@@ -318,11 +341,11 @@ export MAGS_API_TOKEN="your-token"</code></pre>
                   <table class="ref-table">
                     <thead><tr><th>Parameter</th><th>Description</th></tr></thead>
                     <tbody>
-                      <tr><td><code>workspace_id</code></td><td>Keep files across runs (synced to the cloud)</td></tr>
+                      <tr><td><code>workspace_id</code></td><td>Name the workspace. Local only unless <code>persistent=True</code>.</td></tr>
+                      <tr><td><code>persistent</code></td><td>Keep sandbox alive, sync workspace to S3. Files persist indefinitely.</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 sandbox alive after script completes</td></tr>
                       <tr><td><code>no_sleep</code></td><td>Never auto-sleep (requires <code>persistent=True</code>)</td></tr>
-                      <tr><td><code>ephemeral</code></td><td>No cloud sync (fastest)</td></tr>
+                      <tr><td><code>ephemeral</code></td><td>No workspace, no 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 sandbox wakes</td></tr>
                     </tbody>
@@ -339,23 +362,25 @@ m = Mags()  # reads MAGS_API_TOKEN from env
 result = m.run_and_wait("echo Hello World")
 print(result["status"])    # "completed"
-# Create a persistent workspace
+# Local workspace (no S3 sync, good for analysis)
+m.run_and_wait("python3 analyze.py", workspace_id="analysis")
+# Persistent workspace (synced to S3)
+m.run("pip install flask",
+    workspace_id="my-project", persistent=True)
+# Create a sandbox (local disk)
 m.new("my-project")
+# Create with S3 persistence
+m.new("my-project", persistent=True)
 # Execute commands on existing sandbox
 result = m.exec("my-project", "ls -la /root")
 print(result["output"])
-m.exec("my-project", "pip install flask")
-# Stop a job
-m.stop("my-project")
-# Find a job by name or workspace
-job = m.find_job("my-project")
-print(job["status"])  # "running", "sleeping", etc.
 # Public URL
-m.new("webapp")
+m.new("webapp", persistent=True)
 info = m.url("webapp", port=3000)
 print(info["url"])  # https://xyz.apps.magpiecloud.com
@@ -394,15 +419,28 @@ export MAGS_API_TOKEN="your-token"</code></pre>
                     <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>new(name, opts)</code></td><td>Create a VM sandbox (add <code>persistent: true</code> for S3)</td></tr>
+                      <tr><td><code>exec(nameOrId, command)</code></td><td>Run command on existing sandbox via SSH</td></tr>
+                      <tr><td><code>stop(nameOrId)</code></td><td>Stop a running job</td></tr>
+                      <tr><td><code>findJob(nameOrId)</code></td><td>Find job by name or workspace</td></tr>
+                      <tr><td><code>url(nameOrId, port)</code></td><td>Enable public URL access</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>list()</code></td><td>List recent jobs</td></tr>
+                      <tr><td><code>updateJob(requestId, opts)</code></td><td>Update job settings (<code>noSleep</code>, <code>startupCommand</code>)</td></tr>
+                      <tr><td><code>enableAccess(requestId, port)</code></td><td>Enable URL or SSH access</td></tr>
+                      <tr><td><code>resize(workspace, diskGb)</code></td><td>Resize workspace disk</td></tr>
+                      <tr><td><code>uploadFiles(paths)</code></td><td>Upload files, returns file IDs</td></tr>
+                      <tr><td><code>sync(requestId)</code></td><td>Sync workspace to S3 now</td></tr>
+                      <tr><td><code>listWorkspaces()</code></td><td>List persistent workspaces</td></tr>
+                      <tr><td><code>deleteWorkspace(id)</code></td><td>Delete workspace + cloud data</td></tr>
+                      <tr><td><code>urlAliasCreate(sub, wsId)</code></td><td>Create a stable URL alias</td></tr>
+                      <tr><td><code>urlAliasList()</code></td><td>List URL aliases</td></tr>
+                      <tr><td><code>urlAliasDelete(sub)</code></td><td>Delete a URL alias</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>
+                      <tr><td><code>usage(opts)</code></td><td>Get usage stats</td></tr>
                     </tbody>
                   </table>
                 </div>
@@ -414,11 +452,11 @@ export MAGS_API_TOKEN="your-token"</code></pre>
                   <table class="ref-table">
                     <thead><tr><th>Parameter</th><th>Description</th></tr></thead>
                     <tbody>
-                      <tr><td><code>workspaceId</code></td><td>Keep files across runs (synced to the cloud)</td></tr>
+                      <tr><td><code>workspaceId</code></td><td>Name the workspace. Local only unless <code>persistent: true</code>.</td></tr>
+                      <tr><td><code>persistent</code></td><td>Keep sandbox alive, sync workspace to S3. Files persist indefinitely.</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 sandbox alive after script completes</td></tr>
                       <tr><td><code>noSleep</code></td><td>Never auto-sleep (requires <code>persistent: true</code>)</td></tr>
-                      <tr><td><code>ephemeral</code></td><td>No cloud sync (fastest)</td></tr>
+                      <tr><td><code>ephemeral</code></td><td>No workspace, no 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 sandbox wakes</td></tr>
                     </tbody>
@@ -435,17 +473,23 @@ const mags = new Mags({ apiToken: process.env.MAGS_API_TOKEN });
 const result = await mags.runAndWait('echo Hello World');
 console.log(result.status);   // "completed"
-// Persistent workspace
-await mags.runAndWait('pip install flask', { workspaceId: 'myproject' });
-await mags.runAndWait('python3 app.py', { workspaceId: 'myproject' });
+// Local workspace (no S3 sync, good for analysis)
+await mags.runAndWait('python3 analyze.py', { workspaceId: 'analysis' });
+// Persistent workspace (synced to S3)
+await mags.runAndWait('pip install flask', { workspaceId: 'myproject', persistent: true });
+await mags.runAndWait('python3 app.py', { workspaceId: 'myproject', persistent: true });
 // Base image
 await mags.runAndWait('npm test', { baseWorkspaceId: 'golden' });
-await mags.runAndWait('npm test', { baseWorkspaceId: 'golden', workspaceId: 'fork-1' });
+await mags.runAndWait('npm test', { baseWorkspaceId: 'golden', workspaceId: 'fork-1', persistent: true });
+// Create a sandbox
+await mags.new('dev', { persistent: true });
 // SSH access
 const job = await mags.run('sleep 3600', { workspaceId: 'dev', persistent: true });
-const ssh = await mags.enableAccess(job.requestId, { port: 22 });
+const ssh = await mags.enableAccess(job.requestId, 22);
 console.log(`ssh root@${ssh.sshHost} -p ${ssh.sshPort}`);
 // Public URL
@@ -453,8 +497,8 @@ 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);
+const { url } = await mags.url('webapp', 8080);
+console.log(url);
 // Always-on sandbox (never auto-sleeps)
 await mags.run('python3 worker.py', {
@@ -488,10 +532,10 @@ await mags.cronCreate({
             <article class="panel" data-reveal>
               <h3>Backed up to object storage</h3>
               <ul class="list">
-                <li>Files, packages, and configs persist automatically</li>
-                <li>Optional backup to S3-compatible object storage</li>
+                <li>Use <code>-w</code> for a local workspace (no cloud sync, good for throwaway analysis)</li>
+                <li>Add <code>-p</code> to sync to S3 &mdash; files, packages, and configs persist indefinitely</li>
                 <li>Clone a workspace as a read-only base for new sandboxes</li>
-                <li>Survives reboots, sleep, and agent restarts</li>
+                <li>Survives reboots, sleep, and agent restarts (with <code>-p</code>)</li>
               </ul>
             </article>
             <article class="panel" data-reveal>
@@ -569,8 +613,8 @@ await mags.run('node server.js', {
 m = Mags()  # reads MAGS_API_TOKEN from env
-# Create a workspace, run commands on it
-m.new("demo")
+# Create a sandbox, run commands on it
+m.new("demo")  # local disk; use persistent=True for S3
 result = m.exec("demo", "uname -a")
 print(result["output"])
@@ -583,13 +627,14 @@ print(result["status"])  # "completed"</code></pre>
                   <ul class="list">
                     <li><code>run(script, **opts)</code> &mdash; submit a job</li>
                     <li><code>run_and_wait(script, **opts)</code> &mdash; submit + block</li>
-                    <li><code>new(name)</code> &mdash; create persistent VM</li>
+                    <li><code>new(name, **opts)</code> &mdash; create VM sandbox</li>
                     <li><code>exec(name, command)</code> &mdash; run on existing sandbox</li>
                     <li><code>stop(name_or_id)</code> &mdash; stop a job</li>
                     <li><code>find_job(name_or_id)</code> &mdash; find by name/workspace</li>
                     <li><code>url(name_or_id, port)</code> &mdash; enable public URL</li>
+                    <li><code>resize(workspace, disk_gb)</code> &mdash; resize disk</li>
                     <li><code>status(id)</code> / <code>logs(id)</code> / <code>list_jobs()</code></li>
-                    <li><code>upload_files(paths)</code> &mdash; upload files</li>
+                    <li><code>upload_file(path)</code> / <code>upload_files(paths)</code></li>
                     <li><code>list_workspaces()</code> / <code>delete_workspace(id)</code></li>
                     <li><code>sync(id)</code> &mdash; sync workspace to S3</li>
                     <li><code>cron_create(**opts)</code> / <code>cron_list()</code> / <code>cron_delete(id)</code></li>
@@ -619,14 +664,17 @@ console.log(result.logs);</code></pre>
                   <ul class="list">
                     <li><code>run(script, opts)</code> &mdash; submit a job</li>
                     <li><code>runAndWait(script, opts)</code> &mdash; submit + block</li>
-                    <li><code>status(requestId)</code> &mdash; get job status</li>
-                    <li><code>logs(requestId)</code> &mdash; get job logs</li>
-                    <li><code>listJobs()</code> &mdash; list recent jobs</li>
-                    <li><code>enableAccess(id, { port })</code> &mdash; URL or SSH</li>
-                    <li><code>uploadFile(path)</code> &mdash; upload a file</li>
-                    <li><code>cronCreate(opts)</code> &mdash; create cron</li>
-                    <li><code>cronList()</code> / <code>cronDelete(id)</code></li>
-                    <li><code>usage(windowDays)</code> &mdash; usage stats</li>
+                    <li><code>new(name, opts)</code> &mdash; create VM sandbox</li>
+                    <li><code>exec(nameOrId, command)</code> &mdash; run on existing sandbox</li>
+                    <li><code>stop(nameOrId)</code> &mdash; stop a job</li>
+                    <li><code>findJob(nameOrId)</code> &mdash; find by name/workspace</li>
+                    <li><code>url(nameOrId, port)</code> &mdash; enable public URL</li>
+                    <li><code>status(id)</code> / <code>logs(id)</code> / <code>list()</code></li>
+                    <li><code>enableAccess(requestId, port)</code> &mdash; URL or SSH</li>
+                    <li><code>uploadFiles(paths)</code> &mdash; upload files</li>
+                    <li><code>listWorkspaces()</code> / <code>deleteWorkspace(id)</code></li>
+                    <li><code>sync(id)</code> &mdash; sync workspace to S3</li>
+                    <li><code>cronCreate(opts)</code> / <code>cronList()</code> / <code>cronDelete(id)</code></li>
                   </ul>
                   <p style="margin-top:1rem"><a class="text-link" href="https://www.npmjs.com/package/@magpiecloud/mags" rel="noreferrer">npm &rarr;</a></p>
                 </article>
@@ -653,12 +701,18 @@ console.log(result.logs);</code></pre>
                     <li><code>GET /mags-jobs/:id/status</code> &mdash; status</li>
                     <li><code>GET /mags-jobs/:id/logs</code> &mdash; logs</li>
                     <li><code>POST /mags-jobs/:id/access</code> &mdash; URL/SSH</li>
+                    <li><code>POST /mags-jobs/:id/stop</code> &mdash; stop job</li>
+                    <li><code>POST /mags-jobs/:id/sync</code> &mdash; sync workspace</li>
                     <li><code>PATCH /mags-jobs/:id</code> &mdash; update</li>
                     <li><code>POST /mags-files</code> &mdash; upload file</li>
                     <li><code>GET /mags-workspaces</code> &mdash; list ws</li>
                     <li><code>DELETE /mags-workspaces/:id</code> &mdash; delete ws</li>
+                    <li><code>POST /mags-url-aliases</code> &mdash; create alias</li>
+                    <li><code>GET /mags-url-aliases</code> &mdash; list aliases</li>
+                    <li><code>DELETE /mags-url-aliases/:sub</code> &mdash; delete alias</li>
                     <li><code>POST /mags-cron</code> &mdash; create cron</li>
                     <li><code>GET /mags-cron</code> &mdash; list cron</li>
+                    <li><code>PATCH /mags-cron/:id</code> &mdash; update cron</li>
                     <li><code>DELETE /mags-cron/:id</code> &mdash; delete cron</li>
                   </ul>
                   <p style="margin-top:1rem"><a class="text-link" href="api.html">Full API reference &rarr;</a></p>
@@ -731,7 +785,7 @@ console.log(result.logs);</code></pre>
       </div>
     </footer>
-    <script src="script.js?v=7"></script>
+    <script src="script.js?v=8"></script>
     <script>
     (function() {
       var token = localStorage.getItem('microvm-access-token');