@magpiecloud/mags 1.8.12 → 1.8.13

package/README.md

@@ -6,7 +6,7 @@ Execute scripts instantly on Magpie's microVM infrastructure. VMs boot in <100ms
 
 Mags is a CLI and SDK for running scripts on ephemeral microVMs. Each execution gets its own isolated VM that:
 
-- Boots in <100ms (from warm pool)
+- Boots in ~300ms (from warm pool)
 - Supports optional S3-backed persistent workspaces (with `-p` flag)
 - Syncs /root directory automatically when persistence is enabled
 - Can expose public URLs for web services
@@ -419,7 +419,7 @@ mags run 'apk add ffmpeg imagemagick'
 
 | Metric | Value |
 |--------|-------|
-| Warm start | <100ms |
+| Warm start | ~300ms |
 | Cold start | ~4 seconds |
 | Script overhead | ~50ms |
 | Workspace sync | Every 30 seconds |

package/bin/mags.js

@@ -429,6 +429,23 @@ async function newVM(args) {
     process.exit(1);
   }
 
+  // Check if a VM with this name already exists (running or sleeping)
+  try {
+    const jobs = await request('GET', '/api/v1/mags-jobs');
+    const existing = (jobs.jobs || []).find(j =>
+      j.name === name && (j.status === 'running' || j.status === 'sleeping')
+    );
+    if (existing) {
+      log('yellow', `Sandbox '${name}' already exists (status: ${existing.status})`);
+      console.log(`  SSH:  mags ssh ${name}`);
+      console.log(`  Exec: mags exec ${name} <command>`);
+      console.log(`  Stop: mags stop ${name}`);
+      process.exit(0);
+    }
+  } catch (e) {
+    // Non-fatal — proceed with creation if list fails
+  }
+
   const payload = {
     script: 'sleep infinity',
     type: 'inline',

package/package.json

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

package/python/README.md

@@ -135,15 +135,19 @@ print(f"Jobs: {usage['total_jobs']}, VM seconds: {usage['vm_seconds']:.0f}")
 | `find_job(name_or_id)` | Find a running/sleeping job by name or workspace |
 | `exec(name_or_id, command)` | Run a command on an existing VM via SSH |
 | `stop(name_or_id)` | Stop a running job |
+| `url(name_or_id, port)` | Enable public URL and return full URL |
 | `resize(workspace, disk_gb)` | Resize a workspace's disk |
 | `status(request_id)` | Get job status |
 | `logs(request_id)` | Get job logs |
 | `list_jobs(page, page_size)` | List recent jobs |
-| `update_job(request_id, startup_command)` | Update job config |
+| `update_job(request_id, **opts)` | Update job config (`startup_command`, `no_sleep`) |
 | `enable_access(request_id, port)` | Enable URL or SSH access |
 | `usage(window_days)` | Get usage summary |
 | `upload_file(path)` | Upload a file, returns file ID |
 | `upload_files(paths)` | Upload multiple files |
+| `url_alias_create(sub, ws_id)` | Create a stable URL alias |
+| `url_alias_list()` | List URL aliases |
+| `url_alias_delete(sub)` | Delete a URL alias |
 | `cron_create(**opts)` | Create a cron job |
 | `cron_list()` | List cron jobs |
 | `cron_get(id)` | Get a cron job |
@@ -154,4 +158,4 @@ print(f"Jobs: {usage['total_jobs']}, VM seconds: {usage['vm_seconds']:.0f}")
 
 - Website: [mags.run](https://mags.run)
 - Node.js SDK: `npm install @magpiecloud/mags`
-- CLI: `go install` or download from releases
+- CLI: `npm install -g @magpiecloud/mags`

package/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "magpie-mags"
-version = "1.3.5"
+version = "1.3.6"
 description = "Mags SDK - Execute scripts on Magpie's instant VM infrastructure"
 readme = "README.md"
 license = {text = "MIT"}

package/python/src/magpie_mags.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: magpie-mags
-Version: 1.3.4
+Version: 1.3.5
 Summary: Mags SDK - Execute scripts on Magpie's instant VM infrastructure
 Author: Magpie Cloud
 License: MIT
@@ -156,7 +156,7 @@ print(f"Jobs: {usage['total_jobs']}, VM seconds: {usage['vm_seconds']:.0f}")
 |--------|-------------|
 | `run(script, **opts)` | Submit a job (`persistent`, `no_sleep`, `workspace_id`, ...) |
 | `run_and_wait(script, **opts)` | Submit and block until done |
-| `new(name, **opts)` | Create a persistent VM workspace |
+| `new(name, **opts)` | Create a VM sandbox (`persistent=True` for S3) |
 | `find_job(name_or_id)` | Find a running/sleeping job by name or workspace |
 | `exec(name_or_id, command)` | Run a command on an existing VM via SSH |
 | `stop(name_or_id)` | Stop a running job |

package/website/api.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=6" />
+    <link rel="stylesheet" href="styles.css?v=7" />
     <script src="env.js"></script>
     <style>
       .endpoint { margin-bottom: 2.5rem; }
@@ -283,11 +283,14 @@ m = Mags(api_token="your-token")
             <a href="#get-status">Get Status</a>
             <a href="#get-logs">Get Logs</a>
             <a href="#list-jobs">List Jobs</a>
+            <a href="#stop-job">Stop Job</a>
             <a href="#enable-access">Enable Access</a>
             <a href="#update-job">Update Job</a>
+            <a href="#sync-workspace">Sync Workspace</a>
             <a href="#upload-file">Upload File</a>
             <a href="#list-workspaces">List Workspaces</a>
             <a href="#delete-workspace">Delete Workspace</a>
+            <a href="#url-aliases">URL Aliases</a>
             <a href="#cron-endpoints">Cron Jobs</a>
           </div>
 
@@ -542,12 +545,48 @@ for job in resp["jobs"]:
     print(job["request_id"], job["status"])</code></pre>
               </div>
               <div class="tab-content" data-tab="lj-js">
-                <pre><code>const resp = await mags.listJobs({ page: 1, pageSize: 10 });
+                <pre><code>const resp = await mags.list({ page: 1, pageSize: 10 });
 resp.jobs.forEach(j => console.log(j.requestId, j.status));</code></pre>
               </div>
             </div>
           </div>
 
+          <!-- Stop Job -->
+          <div class="endpoint card wide" id="stop-job" data-reveal>
+            <h3>Stop Job</h3>
+            <div class="method-url">
+              <span class="method post">POST</span>
+              <span class="url-path">/api/v1/mags-jobs/:id/stop</span>
+            </div>
+            <p>Stop a running or sleeping job. The VM is terminated and the workspace is synced to S3 if persistent.</p>
+
+            <p class="response-label">Response (200)</p>
+            <pre><code>{ "success": true, "message": "Job stopped" }</code></pre>
+
+            <div class="code-tabs tab-group">
+              <p class="response-label">SDK examples</p>
+              <div class="tab-bar">
+                <button class="tab active" data-tab="sj2-curl">curl</button>
+                <button class="tab" data-tab="sj2-py">Python</button>
+                <button class="tab" data-tab="sj2-js">Node.js</button>
+                <button class="tab" data-tab="sj2-cli">CLI</button>
+              </div>
+              <div class="tab-content active" data-tab="sj2-curl">
+                <pre><code>curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs/$ID/stop \
+  -H "Authorization: Bearer $TOKEN"</code></pre>
+              </div>
+              <div class="tab-content" data-tab="sj2-py">
+                <pre><code>m.stop("myproject")  # accepts name, workspace ID, or request ID</code></pre>
+              </div>
+              <div class="tab-content" data-tab="sj2-js">
+                <pre><code>await mags.stop('myproject'); // accepts name, workspace ID, or request ID</code></pre>
+              </div>
+              <div class="tab-content" data-tab="sj2-cli">
+                <pre><code>mags stop myproject</code></pre>
+              </div>
+            </div>
+          </div>
+
           <!-- Enable Access -->
           <div class="endpoint card wide" id="enable-access" data-reveal>
             <h3>Enable Access (SSH or HTTP)</h3>
@@ -601,11 +640,11 @@ print(access.get("url"))</code></pre>
               </div>
               <div class="tab-content" data-tab="ea-js">
                 <pre><code>// SSH access
-const ssh = await mags.enableAccess(requestId, { port: 22 });
+const ssh = await mags.enableAccess(requestId, 22);
 console.log(`ssh root@${ssh.sshHost} -p ${ssh.sshPort}`);
 
 // HTTP access
-const access = await mags.enableAccess(requestId, { port: 8080 });</code></pre>
+const access = await mags.enableAccess(requestId, 8080);</code></pre>
               </div>
             </div>
           </div>
@@ -714,6 +753,37 @@ file_ids = m.upload_files(["script.py", "data.csv"])</code></pre>
             </div>
           </div>
 
+          <!-- Sync Workspace -->
+          <div class="endpoint card wide" id="sync-workspace" data-reveal>
+            <h3>Sync Workspace</h3>
+            <div class="method-url">
+              <span class="method post">POST</span>
+              <span class="url-path">/api/v1/mags-jobs/:id/sync</span>
+            </div>
+            <p>Trigger an immediate workspace sync to S3 without stopping the VM.</p>
+
+            <p class="response-label">Response (200)</p>
+            <pre><code>{ "success": true, "message": "Sync initiated" }</code></pre>
+
+            <div class="code-tabs tab-group">
+              <p class="response-label">SDK examples</p>
+              <div class="tab-bar">
+                <button class="tab active" data-tab="sw-py">Python</button>
+                <button class="tab" data-tab="sw-js">Node.js</button>
+                <button class="tab" data-tab="sw-cli">CLI</button>
+              </div>
+              <div class="tab-content active" data-tab="sw-py">
+                <pre><code>m.sync(request_id)</code></pre>
+              </div>
+              <div class="tab-content" data-tab="sw-js">
+                <pre><code>await mags.sync(requestId);</code></pre>
+              </div>
+              <div class="tab-content" data-tab="sw-cli">
+                <pre><code>mags sync myproject</code></pre>
+              </div>
+            </div>
+          </div>
+
           <!-- List Workspaces -->
           <div class="endpoint card wide" id="list-workspaces" data-reveal>
             <h3>List Workspaces</h3>
@@ -794,6 +864,65 @@ mags workspace delete myproject --force  # skip confirmation</code></pre>
             </div>
           </div>
 
+          <!-- URL Aliases -->
+          <div class="endpoint card wide" id="url-aliases" data-reveal>
+            <h3>URL Aliases</h3>
+            <div class="method-url">
+              <span class="method post">POST</span>
+              <span class="url-path">/api/v1/mags-url-aliases</span>
+            </div>
+            <div class="method-url" style="margin-left:0.5rem">
+              <span class="method get">GET</span>
+              <span class="url-path">/api/v1/mags-url-aliases</span>
+            </div>
+            <div class="method-url" style="margin-left:0.5rem">
+              <span class="method delete">DELETE</span>
+              <span class="url-path">/api/v1/mags-url-aliases/:subdomain</span>
+            </div>
+            <p>Create stable, human-readable URL aliases for your sandboxes. Aliases point to a workspace and automatically follow the active VM.</p>
+
+            <p class="response-label">Create request body</p>
+            <table class="field-table">
+              <thead>
+                <tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr>
+              </thead>
+              <tbody>
+                <tr><td><code>subdomain</code></td><td>string</td><td><span class="required">YES</span></td><td>Subdomain for the alias (e.g. <code>my-api</code>).</td></tr>
+                <tr><td><code>workspace_id</code></td><td>string</td><td><span class="required">YES</span></td><td>Workspace to point the alias at.</td></tr>
+                <tr><td><code>domain</code></td><td>string</td><td>no</td><td>Custom domain (default: <code>apps.magpiecloud.com</code>).</td></tr>
+              </tbody>
+            </table>
+
+            <div class="code-tabs tab-group">
+              <p class="response-label">SDK examples</p>
+              <div class="tab-bar">
+                <button class="tab active" data-tab="ua-cli">CLI</button>
+                <button class="tab" data-tab="ua-py">Python</button>
+                <button class="tab" data-tab="ua-js">Node.js</button>
+              </div>
+              <div class="tab-content active" data-tab="ua-cli">
+                <pre><code># Create alias
+mags url alias my-api myproject
+
+# List aliases
+mags url alias list
+
+# Delete alias
+mags url alias remove my-api</code></pre>
+              </div>
+              <div class="tab-content" data-tab="ua-py">
+                <pre><code>m.url_alias_create("my-api", "myproject")
+aliases = m.url_alias_list()
+m.url_alias_delete("my-api")</code></pre>
+              </div>
+              <div class="tab-content" data-tab="ua-js">
+                <pre><code>await mags.urlAliasCreate('my-api', 'myproject');
+const aliases = await mags.urlAliasList();
+await mags.urlAliasDelete('my-api');</code></pre>
+              </div>
+            </div>
+          </div>
+
           <!-- Cron Endpoints -->
           <div class="endpoint card wide" id="cron-endpoints" data-reveal>
             <h3>Cron Jobs</h3>
@@ -961,6 +1090,6 @@ mags cron remove &lt;id&gt;</code></pre>
       </div>
     </footer>
 
-    <script src="script.js?v=7"></script>
+    <script src="script.js?v=8"></script>
   </body>
 </html>

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=6" />
+    <link rel="stylesheet" href="styles.css?v=7" />
     <script src="env.js"></script>
   </head>
   <body>
@@ -59,9 +59,8 @@
             </div>
             <div class="tab-content active" data-tab="hero-cli">
               <pre><code>mags run 'echo Hello World'
-
 mags run -w myproject -p 'pip install flask'
-mags ssh myproject</code></pre>
+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">
@@ -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,21 +248,14 @@ mags login</code></pre>
               </div>
 
               <div class="ref-section">
-                <h3>Run Flags</h3>
-                <p><code>-w</code> and <code>-n</code> are aliases &mdash; both set the job name and workspace ID.</p>
+                <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;name&gt;</code></td><td>Name the job/workspace. Data stays local to the VM only. Add <code>-p</code> to sync to S3 and persist.</td></tr>
                       <tr><td><code>-n, --name &lt;name&gt;</code></td><td>Alias for <code>-w</code></td></tr>
-                      <tr><td><code>-p, --persistent</code></td><td>Keep sandbox alive after script, sync workspace to S3. Files persist across runs indefinitely.</td></tr>
-                      <tr><td><code>--base &lt;workspace&gt;</code></td><td>Clone a workspace as a read-only starting point (OverlayFS)</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 workspace, no 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>--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>-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>
@@ -236,43 +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'
-
-# Local workspace &mdash; data stays on VM only (no S3 sync)
-# Good for data analysis and throwaway work
-mags run -w analysis -f data.csv 'python3 analyze.py'
-
-# Persistent workspace &mdash; files synced to S3, survive across runs
+                <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'
 
-# Base image &mdash; create a golden image, sync it, then reuse
+# Golden image &mdash; create once, fork many times
 mags run -w golden -p 'apk add nodejs npm && 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 -p 'npm test'    # fork: load golden, save fork-1 to S3
+mags sync golden
+mags run --base golden -w fork-1 -p 'npm test'
 
-# SSH into a workspace (auto-starts sandbox if needed)
-mags ssh myproject
+# Interactive sandbox with SSH
+mags new dev -p
+mags ssh dev
+mags exec dev 'node --version'
 
-# 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 \
+# 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 workspace at all)
-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>
@@ -295,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, persistent=True)</code></td><td>Create VM sandbox (add persistent for S3)</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>
@@ -401,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>
@@ -453,9 +484,12 @@ await mags.runAndWait('python3 app.py', { workspaceId: 'myproject', persistent:
 await mags.runAndWait('npm test', { baseWorkspaceId: 'golden' });
 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
@@ -463,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', {
@@ -593,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, persistent=True)</code> &mdash; create VM sandbox (add persistent for S3)</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>
@@ -629,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>
@@ -663,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>
@@ -741,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');