@magpiecloud/mags 1.8.11 → 1.8.12

package/README.md

@@ -7,8 +7,8 @@ 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)
-- Has persistent workspaces synced to S3
-- Syncs /root directory automatically every 30 seconds
+- Supports optional S3-backed persistent workspaces (with `-p` flag)
+- Syncs /root directory automatically when persistence is enabled
 - Can expose public URLs for web services
 - Provides SSH access through secure proxy
 - Auto-sleeps when idle and wakes on request
@@ -51,16 +51,17 @@ export MAGS_API_TOKEN="your-token-here"
 mags run 'echo Hello World'
 ```
 
-### Create a persistent VM
+### Create a sandbox
 
 ```bash
-# Create a new VM with workspace "myproject"
+# Create a new VM (local disk only)
 mags new myproject
 
+# Create with S3 data persistence
+mags new myproject -p
+
 # SSH into it
 mags ssh myproject
-
-# Your /root directory persists to S3 automatically
 ```
 
 ### Run with a persistent workspace
@@ -91,7 +92,7 @@ mags run -p --url 'python3 -m http.server 8080'
 | `mags login` | Authenticate with Magpie (saves token locally) |
 | `mags logout` | Remove saved credentials |
 | `mags whoami` | Show current authentication status |
-| `mags new <workspace>` | Create a persistent VM with workspace |
+| `mags new <workspace> [-p]` | Create a VM sandbox (add `-p` for S3 persistence) |
 | `mags run [options] <script>` | Execute a script on a microVM |
 | `mags ssh <workspace>` | Open interactive SSH session to a VM |
 | `mags status <job-id>` | Get job status |
@@ -230,7 +231,7 @@ If an always-on VM's host becomes unhealthy, the orchestrator automatically re-p
 ### Interactive Development
 
 ```bash
-# Create a persistent dev environment
+# Create a dev environment (local disk)
 mags new dev-env
 
 # SSH in and work
@@ -263,7 +264,7 @@ const mags = new Mags({
 |--------|-------------|
 | `run(script, options)` | Submit a job. Options: `name`, `workspaceId`, `baseWorkspaceId`, `persistent`, `noSleep`, `ephemeral`, `startupCommand`, `environment`, `fileIds`, `diskGb` |
 | `runAndWait(script, options)` | Submit and block until done. Extra options: `timeout`, `pollInterval` |
-| `new(name, options)` | Create a persistent VM and wait until running. Options: `baseWorkspaceId`, `diskGb`, `timeout` |
+| `new(name, options)` | Create a VM sandbox and wait until running. Options: `persistent`, `baseWorkspaceId`, `diskGb`, `timeout` |
 | `status(requestId)` | Get job status |
 | `logs(requestId)` | Get job logs |
 | `list({page, pageSize})` | List recent jobs (paginated) |
@@ -315,9 +316,12 @@ const mags = new Mags({
 const result = await mags.runAndWait('echo Hello World');
 console.log(result.logs);
 
-// Create a persistent VM
+// Create a sandbox (local disk)
 await mags.new('myproject');
 
+// Create a sandbox with S3 persistence
+await mags.new('myproject', { persistent: true });
+
 // Execute command on existing VM
 const { output } = await mags.exec('myproject', 'ls -la /root');
 console.log(output);

package/bin/mags.js

@@ -246,7 +246,8 @@ ${colors.bold}Cron Options:${colors.reset}
 
 ${colors.bold}Examples:${colors.reset}
   mags login
-  mags new myvm                     # Create VM, get ID
+  mags new myvm                     # Create VM (local disk only)
+  mags new myvm -p                   # Create VM with S3 persistence
   mags ssh myvm                     # SSH (auto-starts if needed)
   mags exec myvm 'ls -la'           # Run command on existing VM
   mags run 'echo Hello World'
@@ -407,9 +408,12 @@ async function newVM(args) {
   let name = null;
   let baseWorkspace = null;
   let diskGB = 0;
+  let persistent = false;
 
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--base' && args[i + 1]) {
+    if (args[i] === '-p' || args[i] === '--persistent') {
+      persistent = true;
+    } else if (args[i] === '--base' && args[i + 1]) {
       baseWorkspace = args[++i];
     } else if (args[i] === '--disk' && args[i + 1]) {
       diskGB = parseInt(args[++i]) || 0;
@@ -420,7 +424,8 @@ async function newVM(args) {
 
   if (!name) {
     log('red', 'Error: Name required');
-    console.log(`\nUsage: mags new <name> [--base <workspace>] [--disk <GB>]\n`);
+    console.log(`\nUsage: mags new <name> [-p] [--base <workspace>] [--disk <GB>]`);
+    console.log(`  -p, --persistent  Enable S3 data persistence\n`);
     process.exit(1);
   }
 
@@ -430,7 +435,8 @@ async function newVM(args) {
     persistent: true,
     name: name,
     workspace_id: name,
-    startup_command: 'sleep infinity'
+    startup_command: 'sleep infinity',
+    no_sync: !persistent
   };
   if (baseWorkspace) payload.base_workspace_id = baseWorkspace;
   if (diskGB) payload.disk_gb = diskGB;
@@ -451,9 +457,12 @@ async function newVM(args) {
     const status = await request('GET', `/api/v1/mags-jobs/${response.request_id}/status`);
 
     if (status.status === 'running') {
-      log('green', `VM '${name}' created successfully`);
+      log('green', `VM '${name}' created successfully${persistent ? ' (persistent)' : ' (local disk)'}`);
       console.log(`  ID:  ${response.request_id}`);
       console.log(`  SSH: mags ssh ${name}`);
+      if (!persistent) {
+        log('gray', `  Data is on local disk only. Use -p flag for S3 persistence.`);
+      }
       return;
     } else if (status.status === 'error') {
       log('red', `VM creation failed: ${status.error_message || 'Unknown error'}`);

package/index.js

@@ -123,6 +123,7 @@ class Mags {
     };
 
     if (options.noSleep) payload.no_sleep = true;
+    if (options.noSync) payload.no_sync = true;
     if (options.name) payload.name = options.name;
     if (!options.ephemeral && options.workspaceId) payload.workspace_id = options.workspaceId;
     if (options.baseWorkspaceId) payload.base_workspace_id = options.baseWorkspaceId;
@@ -262,9 +263,12 @@ class Mags {
   }
 
   /**
-   * Create a new persistent VM workspace and wait until it's running
+   * Create a new VM sandbox and wait until it's running.
+   * By default, data lives on local disk only (no S3 sync).
+   * Pass persistent: true to enable S3 data persistence.
    * @param {string} name - Workspace name
    * @param {object} options - Options
+   * @param {boolean} options.persistent - Enable S3 data persistence (default: false)
    * @param {string} options.baseWorkspaceId - Read-only base workspace to mount
    * @param {number} options.diskGb - Custom disk size in GB
    * @param {number} options.timeout - Timeout in ms (default: 30000)
@@ -278,6 +282,7 @@ class Mags {
     const result = await this.run('sleep infinity', {
       workspaceId: name,
       persistent: true,
+      noSync: !options.persistent,
       baseWorkspaceId: options.baseWorkspaceId,
       diskGb: options.diskGb,
     });
@@ -419,7 +424,7 @@ class Mags {
       await new Promise(resolve => setTimeout(resolve, 1000));
     }
 
-    return this.new(workspace, { diskGb, timeout: options.timeout, pollInterval: options.pollInterval });
+    return this.new(workspace, { persistent: true, diskGb, timeout: options.timeout, pollInterval: options.pollInterval });
   }
 
   /**

package/nodejs/README.md

@@ -18,10 +18,11 @@ mags login
 
 This will open your browser to create an API token. Paste the token when prompted, and it will be saved for future use.
 
-### 2. Create a persistent VM
+### 2. Create a sandbox
 
 ```bash
-mags new myproject
+mags new myproject              # Local disk only
+mags new myproject -p           # With S3 persistence
 mags ssh myproject
 ```
 
@@ -59,9 +60,12 @@ export MAGS_API_TOKEN="your-token-here"
 ## CLI Commands
 
 ```bash
-# Create a persistent VM
+# Create a sandbox (local disk)
 mags new myproject
 
+# Create with S3 persistence
+mags new myproject -p
+
 # SSH into it
 mags ssh myproject
 
@@ -135,11 +139,13 @@ Features:
 
 ## Workspaces & Persistence
 
-Your `/root` directory automatically syncs to S3:
+When using persistent mode (`-p`), your `/root` directory syncs to S3:
 - **Auto-sync**: Every 30 seconds while running
 - **On stop**: Full sync before VM terminates
 - **On wake**: Previous state restored
 
+Without `-p`, data lives on local disk only and is cleaned up when the VM is destroyed.
+
 ## Node.js SDK
 
 ```javascript

package/package.json

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

package/python/README.md

@@ -131,7 +131,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/python/pyproject.toml

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

package/python/src/mags/client.py

@@ -106,6 +106,7 @@ class Mags:
         environment: Dict[str, str] | None = None,
         file_ids: List[str] | None = None,
         disk_gb: int | None = None,
+        no_sync: bool = False,
     ) -> dict:
         """Submit a job for execution.
 
@@ -122,6 +123,7 @@ class Mags:
             environment: Key-value env vars injected into the VM.
             file_ids: File IDs to download into VM before script runs.
             disk_gb: Custom disk size in GB (default 2GB).
+            no_sync: Skip S3 sync, use local disk only.
 
         Returns ``{"request_id": ..., "status": "accepted"}``.
         """
@@ -139,6 +141,8 @@ class Mags:
         }
         if no_sleep:
             payload["no_sleep"] = True
+        if no_sync:
+            payload["no_sync"] = True
         if name:
             payload["name"] = name
         if not ephemeral and workspace_id:
@@ -262,20 +266,25 @@ class Mags:
             self._request("POST", f"/mags-jobs/{existing['request_id']}/stop")
             time.sleep(1)
 
-        return self.new(workspace, disk_gb=disk_gb, timeout=timeout, poll_interval=poll_interval)
+        return self.new(workspace, persistent=True, disk_gb=disk_gb,
+                        timeout=timeout, poll_interval=poll_interval)
 
     def new(
         self,
         name: str,
         *,
+        persistent: bool = False,
         base_workspace_id: str | None = None,
         disk_gb: int | None = None,
         timeout: float = 30.0,
         poll_interval: float = 1.0,
     ) -> dict:
-        """Create a new persistent VM workspace and wait until it's running.
+        """Create a new VM sandbox and wait until it's running.
+
+        By default, data lives on local disk only (no S3 sync).
+        Pass ``persistent=True`` to enable S3 data persistence.
 
-        Equivalent to ``mags new <name>``.
+        Equivalent to ``mags new <name>`` or ``mags new <name> -p``.
 
         Returns ``{"request_id": ..., "status": "running"}``.
         """
@@ -283,6 +292,7 @@ class Mags:
             "sleep infinity",
             workspace_id=name,
             persistent=True,
+            no_sync=not persistent,
             base_workspace_id=base_workspace_id,
             disk_gb=disk_gb,
         )

package/website/api.html

@@ -252,7 +252,7 @@ m = Mags(api_token="your-token")
                 <tr>
                   <td><code>"my-ws"</code></td>
                   <td><em>omit</em></td>
-                  <td>Read+write workspace. Changes persist across runs.</td>
+                  <td>Local workspace. Data stays on the VM only (not synced to S3). Add <code>persistent: true</code> to sync to S3.</td>
                 </tr>
                 <tr>
                   <td><em>omit</em></td>
@@ -322,7 +322,7 @@ m = Mags(api_token="your-token")
                   <td><code>workspace_id</code></td>
                   <td>string</td>
                   <td>no</td>
-                  <td>Persistent workspace name. Filesystem changes are synced to S3 and restored on next run. Omit for ephemeral.</td>
+                  <td>Workspace name. With <code>persistent: false</code>, data stays local to the VM only. With <code>persistent: true</code>, filesystem changes are synced to S3 and restored on next run. Omit for ephemeral.</td>
                 </tr>
                 <tr>
                   <td><code>base_workspace_id</code></td>
@@ -334,7 +334,7 @@ m = Mags(api_token="your-token")
                   <td><code>persistent</code></td>
                   <td>bool</td>
                   <td>no</td>
-                  <td>If <code>true</code>, VM stays alive after script finishes.</td>
+                  <td>If <code>true</code>, VM stays alive after script finishes and workspace is synced to S3. Required for cloud persistence.</td>
                 </tr>
                 <tr>
                   <td><code>no_sleep</code></td>

package/website/cookbook.html

@@ -61,7 +61,7 @@ mags ssh dev-env
 
 # inside the VM
 apk add git nodejs npm</code></pre>
-            <p class="card-note">Create a persistent dev environment with one command.</p>
+            <p class="card-note">Create a dev sandbox with one command. Add <code>-p</code> for S3 persistence.</p>
           </div>
         </div>
       </section>

package/website/index.html

@@ -60,9 +60,9 @@
             <div class="tab-content active" data-tab="hero-cli">
               <pre><code>mags run 'echo Hello World'
 
-mags run -w myproject 'pip install flask'
+mags run -w myproject -p 'pip install flask'
 mags ssh myproject</code></pre>
-              <p class="card-note">Run a script, keep your files, then jump in with SSH.</p>
+              <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 +112,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>
@@ -213,17 +213,18 @@ mags login</code></pre>
 
               <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>
                 <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>-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 cloud sync &mdash; fastest execution</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>-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>--disk &lt;GB&gt;</code></td><td>Custom disk size in GB (default: 2)</td></tr>
@@ -238,15 +239,19 @@ mags login</code></pre>
                 <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'
+# 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
+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
-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
+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
 
 # SSH into a workspace (auto-starts sandbox if needed)
 mags ssh myproject
@@ -265,7 +270,7 @@ 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)
+# Ephemeral (fastest &mdash; no workspace at all)
 mags run -e 'uname -a && df -h'
 
 # Cron job
@@ -290,7 +295,7 @@ 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>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>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>
@@ -318,11 +323,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 +344,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
 
@@ -414,11 +421,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,13 +442,16 @@ 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 });
 
 // SSH access
 const job = await mags.run('sleep 3600', { workspaceId: 'dev', persistent: true });
@@ -488,10 +498,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 +579,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,7 +593,7 @@ 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, persistent=True)</code> &mdash; create VM sandbox (add persistent for S3)</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>

package/website/llms.txt

@@ -1,8 +1,8 @@
 # Mags
 
-> Instant sandboxes and runtime environments
+> Secure cloud sandboxes for AI agents and developers
 
-Mags is a CLI, SDK, and API for running scripts on isolated microVMs with persistent workspaces, file upload, cron scheduling, and optional URL access.
+Mags is a CLI, SDK, and API for running scripts on isolated microVMs with workspaces, file upload, cron scheduling, and optional URL access.
 
 ## Quickstart
 
@@ -26,32 +26,55 @@ mags run 'echo Hello World'
 - `mags login` — Authenticate and save credentials
 - `mags logout` — Remove saved credentials
 - `mags whoami` — Check auth status
-- `mags new <workspace>` — Create a persistent VM workspace
+- `mags new <name> [-p]` — Create a VM sandbox (add -p for S3 data persistence)
 - `mags run <script>` — Execute a script on a microVM
-- `mags ssh <workspace>` — Open an SSH session into a workspace
-- `mags exec <workspace> <command>` — Run a command on an existing sandbox
-- `mags url <job-id>` — Enable public URL access for a running job
+- `mags ssh <name>` — Open an SSH session into a sandbox (auto-starts if needed)
+- `mags exec <name> <command>` — Run a command on an existing sandbox
 - `mags list` — List recent jobs
-- `mags logs <job-id>` — View job logs
-- `mags status <job-id>` — Check job status
-- `mags stop <job-id>` — Stop a running job
+- `mags logs <name|id>` — View job logs
+- `mags status <name|id>` — Check job status
+- `mags stop <name|id>` — Stop a running job
+- `mags sync <name|id>` — Sync workspace to S3 without stopping the VM
+- `mags resize <name> --disk <GB>` — Resize disk for a workspace
+- `mags url <name|id> [port]` — Enable public URL access for a running job
+- `mags url alias <subdomain> <name>` — Create a stable URL alias
+- `mags url alias list` — List URL aliases
+- `mags url alias remove <subdomain>` — Remove a URL alias
 - `mags set <name|id> --no-sleep` — Never auto-sleep this VM
 - `mags set <name|id> --sleep` — Re-enable auto-sleep
+- `mags workspace list` — List persistent workspaces
+- `mags workspace delete <id>` — Delete workspace and cloud data
+- `mags browser [name]` — Start a Chromium browser session (CDP access)
 
 ## Run Options
 
+`-w` and `-n` are aliases — both set the job name and workspace ID to the same value.
+
 | Flag | Description |
 |------|-------------|
-| `-w, --workspace <id>` | Persist files with a named workspace |
-| `-n, --name <name>` | Job name for easier reference |
-| `-p, --persistent` | Keep VM alive after script for URL or SSH |
+| `-w, --workspace <name>` | Name the job and workspace. Data stays local to the VM only (not synced to S3). Useful for data analysis where you don't need artifacts to persist. Combine with `-p` to sync to S3 and persist. |
+| `-n, --name <name>` | Alias for `-w` |
+| `-p, --persistent` | Keep VM alive after script and sync workspace to S3. Files persist across runs indefinitely. Required for URL, SSH, and cloud persistence. |
+| `--base <workspace>` | Mount an existing workspace read-only as a starting point (OverlayFS). Use with `-w` to fork into a new workspace. |
 | `--no-sleep` | Never auto-sleep this VM (requires -p) |
-| `-e, --ephemeral` | No workspace, no S3 sync (fastest). Cannot combine with -w or -p |
+| `-e, --ephemeral` | No workspace, no sync (fastest). Cannot combine with -w, -p, or --base |
 | `-f, --file <path>` | Upload a local file into /root/ in the VM (repeatable) |
 | `--url` | Enable public URL (requires -p) |
 | `--port <port>` | Port to expose (default: 8080) |
 | `--disk <GB>` | Custom disk size in GB (default: 2) |
-| `--startup-command <cmd>` | Command to run when a VM wakes |
+| `--startup-command <cmd>` | Command to run when a VM wakes from sleep |
+
+## Workspace Modes
+
+| Flags | Behavior |
+|-------|----------|
+| (none) | Ephemeral. No workspace, no persistence. |
+| `-w myproject` | Local workspace. Data stays on the VM only (~5 min warm cache after job completes). Not synced to S3. Good for data analysis and throwaway work. |
+| `-w myproject -p` | Persistent workspace. VM stays alive, data synced to S3. Files survive across runs indefinitely. |
+| `--base golden` | Read-only base image. Changes discarded after run. |
+| `--base golden -w fork-1` | Fork: starts from golden, saves changes to fork-1 (local only without -p). |
+| `--base golden -w fork-1 -p` | Fork with persistence: starts from golden, saves to fork-1 in S3. |
+| `-e` | Explicit ephemeral. Same as no flags but cannot accidentally combine with -w or -p. |
 
 ## File Upload
 
@@ -64,8 +87,8 @@ mags run -f script.py 'python3 script.py'
 # Multiple files
 mags run -f analyze.py -f data.csv 'python3 analyze.py'
 
-# With workspace persistence
-mags run -w my-project -f config.json -f app.js 'cp *.js *.json /root/ && cd /root && npm install'
+# With persistent workspace
+mags run -w my-project -p -f config.json -f app.js 'cp *.js *.json /root/ && cd /root && npm install'
 ```
 
 ## Cron Scheduling
@@ -96,24 +119,20 @@ mags cron disable <id>
 |------|-------------|
 | `-n, --name` | Cron job name (required) |
 | `-s, --schedule` | Cron expression, e.g. "0 */2 * * *" (required) |
-| `-w, --workspace` | Workspace ID for persistent storage |
+| `-w, --workspace` | Workspace ID for storage |
 | `-p, --persistent` | Keep VM alive after script |
 
-## Workspaces
-
-Workspaces persist files, installed packages, and configuration between runs. Running processes, in-memory state, and open ports reset between sessions.
-
 ## Complex Project Workflow
 
-For multi-file projects, the recommended pattern is: create files locally, upload them, then run.
+For multi-file projects, the recommended pattern is: create files locally, upload them, then run persistently.
 
 ```
-# Step 1: Upload files and install deps in a workspace
-mags run -w my-project -f server.js -f package.json \
+# Step 1: Upload files and install deps in a persistent workspace
+mags run -w my-project -p -f server.js -f package.json \
   'cp *.js *.json /root/ && cd /root && npm install'
 
-# Step 2: Test run
-mags run -w my-project 'cd /root && node server.js'
+# Step 2: Test run (reuses the persistent workspace)
+mags run -w my-project -p 'cd /root && node server.js'
 
 # Step 3: Run with public URL
 mags run -w my-project -p --url --port 3000 'cd /root && node server.js'
@@ -123,9 +142,27 @@ mags cron add --name "my-server" --schedule "0 */6 * * *" -w my-project \
   'cd /root && node server.js'
 ```
 
+## Data Analysis Workflow
+
+For throwaway analysis where you need a workspace but don't care about persisting artifacts:
+
+```
+# Upload data and analyze — workspace is local only, no S3 overhead
+mags run -w analysis -f data.csv 'python3 -c "
+import csv
+with open(\"/root/data.csv\") as f:
+    reader = csv.reader(f)
+    for row in reader:
+        print(row)
+"'
+
+# Results printed to stdout (use `mags logs` to retrieve)
+# VM and data cleaned up automatically after ~5 minutes
+```
+
 ## Ephemeral Mode
 
-For the fastest runs with no workspace or S3 sync overhead:
+For the fastest runs with no workspace at all:
 ```
 mags run -e 'uname -a && df -h'
 ```
@@ -150,12 +187,17 @@ Generate tokens at https://mags.run/tokens or via `mags login`.
 - `GET /mags-jobs/{id}/status` — Get job status
 - `GET /mags-jobs/{id}/logs` — Get job logs
 - `POST /mags-jobs/{id}/access` — Enable URL or SSH access
-- `PATCH /mags-jobs/{id}` — Update startup command
+- `PATCH /mags-jobs/{id}` — Update job settings (startup_command, no_sleep)
 
 ### File Endpoints
 
 - `POST /mags-files` — Upload file(s) via multipart/form-data (max 100MB)
 
+### Workspace Endpoints
+
+- `GET /mags-workspaces` — List workspaces
+- `DELETE /mags-workspaces/{id}` — Delete workspace and S3 data
+
 ### Cron Endpoints
 
 - `POST /mags-cron` — Create a cron job
@@ -193,9 +235,12 @@ mags = Mags()  # uses MAGS_API_TOKEN env var
 result = mags.run_and_wait('echo Hello World')
 print(result['logs'])
 
-# Create a persistent workspace
+# Create a sandbox (local disk)
 mags.new('my-project')
 
+# Create with S3 persistence
+mags.new('my-project', persistent=True)
+
 # Execute a command on an existing sandbox
 result = mags.exec('my-project', 'ls -la /root')
 print(result['output'])
@@ -265,8 +310,8 @@ Then use `/mags <description>` in Claude Code to run scripts in microVMs.
 
 - Alpine Linux base image
 - Hostname: `mags-vm`
-- Persistent home: `/root` (synced to S3 with workspaces)
-- JuiceFS mount: `/jfs`
+- Home directory: `/root`
+- JuiceFS mount: `/jfs` (persistent workspaces only)
 - Package manager: `apk`
 - Pre-installed: curl, wget, git, python3, node, vim, nano
 

package/website/mags.md

@@ -31,9 +31,10 @@ mags run -p --url '<script>'
 mags run -w <workspace> -p --url --port 3000 '<script>'
 ```
 
-### Create a new persistent VM (stays alive for SSH)
+### Create a new VM sandbox (stays alive for SSH)
 ```bash
-mags new <name>
+mags new <name>            # Local disk only
+mags new <name> -p         # With S3 data persistence
 ```
 
 ### Execute a command on an existing sandbox