@magpiecloud/mags 1.7.5 → 1.8.1

package/bin/mags.js

@@ -217,6 +217,7 @@ ${colors.bold}Run Options:${colors.reset}
   -w, --workspace <id>            Use persistent workspace (S3 sync)
   -n, --name <name>               Set job name (for easier reference)
   -p, --persistent                Keep VM alive after script completes
+  --no-sleep                      Never auto-sleep this VM (requires -p)
   --base <workspace>              Mount workspace read-only as base image
   -e, --ephemeral                 No workspace/S3 sync (fastest execution)
   -f, --file <path>               Upload file(s) to VM (repeatable)
@@ -457,6 +458,7 @@ async function runJob(args) {
   let baseWorkspace = '';
   let name = '';
   let persistent = false;
+  let noSleep = false;
   let ephemeral = false;
   let enableUrl = false;
   let port = 8080;
@@ -481,6 +483,9 @@ async function runJob(args) {
       case '--persistent':
         persistent = true;
         break;
+      case '--no-sleep':
+        noSleep = true;
+        break;
       case '-e':
       case '--ephemeral':
         ephemeral = true;
@@ -522,6 +527,10 @@ async function runJob(args) {
     log('red', 'Error: Cannot use --ephemeral with --base; ephemeral VMs have no workspace support');
     process.exit(1);
   }
+  if (noSleep && !persistent) {
+    log('red', 'Error: --no-sleep requires --persistent (-p)');
+    process.exit(1);
+  }
 
   // Upload files if any
   let fileIds = [];
@@ -546,6 +555,7 @@ async function runJob(args) {
     type: 'inline',
     persistent
   };
+  if (noSleep) payload.no_sleep = true;
   // Only set workspace_id if not ephemeral
   if (!ephemeral && workspace) payload.workspace_id = workspace;
   if (name) payload.name = name;
@@ -579,6 +589,14 @@ async function runJob(args) {
       log('green', `Completed in ${status.script_duration_ms}ms`);
       break;
     } else if (status.status === 'running' && persistent) {
+      // If --url requested, wait until VM is actually assigned (vm_id populated)
+      if (enableUrl && !status.vm_id) {
+        process.stdout.write('.');
+        await sleep(1000);
+        attempt++;
+        continue;
+      }
+
       log('green', 'VM running');
 
       if (enableUrl && status.subdomain) {
@@ -587,7 +605,7 @@ async function runJob(args) {
         if (accessResp.success) {
           log('green', `URL: https://${status.subdomain}.apps.magpiecloud.com`);
         } else {
-          log('yellow', 'Warning: Could not enable URL access');
+          log('yellow', `Warning: Could not enable URL access${accessResp.error ? ': ' + accessResp.error : ''}`);
         }
       }
       return;
@@ -1338,7 +1356,7 @@ async function main() {
         break;
       case '--version':
       case '-v':
-        console.log('mags v1.7.0');
+        console.log('mags v1.8.1');
         process.exit(0);
         break;
       case 'new':

package/package.json

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

package/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "magpie-mags"
-version = "1.0.0"
+version = "1.1.0"
 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.0.0
+Version: 1.1.0
 Summary: Mags SDK - Execute scripts on Magpie's instant VM infrastructure
 Author: Magpie Cloud
 License: MIT

package/python/src/mags/__init__.py

@@ -3,4 +3,4 @@
 from .client import Mags
 
 __all__ = ["Mags"]
-__version__ = "1.0.0"
+__version__ = "1.1.0"

package/python/src/mags/client.py

@@ -98,6 +98,7 @@ class Mags:
         workspace_id: str | None = None,
         base_workspace_id: str | None = None,
         persistent: bool = False,
+        no_sleep: bool = False,
         ephemeral: bool = False,
         startup_command: str | None = None,
         environment: Dict[str, str] | None = None,
@@ -111,12 +112,16 @@ class Mags:
             raise MagsError("Cannot use ephemeral with workspace_id")
         if ephemeral and persistent:
             raise MagsError("Cannot use ephemeral with persistent")
+        if no_sleep and not persistent:
+            raise MagsError("no_sleep requires persistent=True")
 
         payload = {
             "script": script,
             "type": "inline",
             "persistent": persistent,
         }
+        if no_sleep:
+            payload["no_sleep"] = True
         if name:
             payload["name"] = name
         if not ephemeral and workspace_id:

package/website/api.html

@@ -336,6 +336,12 @@ m = Mags(api_token="your-token")
                   <td>no</td>
                   <td>If <code>true</code>, VM stays alive after script finishes.</td>
                 </tr>
+                <tr>
+                  <td><code>no_sleep</code></td>
+                  <td>bool</td>
+                  <td>no</td>
+                  <td>If <code>true</code>, VM will never be auto-slept by the idle timeout. Requires <code>persistent: true</code>.</td>
+                </tr>
                 <tr>
                   <td><code>startup_command</code></td>
                   <td>string</td>

package/website/index.html

@@ -3,14 +3,14 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Mags - Instant Sandboxes and Runtime Environments</title>
+    <title>Mags - Secure Cloud Sandboxes for AI Agents and Developers</title>
     <meta
       name="description"
-      content="Mags is a CLI, Python SDK, and Node.js SDK for running scripts on isolated microVMs with persistent workspaces and optional URL access."
+      content="Mags gives AI agents and developers secure, isolated sandboxes that boot in milliseconds. Workspaces persist automatically to the cloud. Run code, schedule jobs, and let agents work safely."
     />
     <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=3" />
+    <link rel="stylesheet" href="styles.css?v=5" />
     <script src="env.js"></script>
   </head>
   <body>
@@ -20,7 +20,7 @@
       <div class="container nav">
         <div class="brand">
           <span class="logo">Mags</span>
-          <span class="tag">Instant sandboxes and runtime environments</span>
+          <span class="tag">Secure cloud sandboxes for the AI age</span>
         </div>
         <nav class="nav-links">
           <a href="#overview">Overview</a>
@@ -42,11 +42,12 @@
         <div class="container hero-grid">
           <div class="hero-copy">
             <span class="pill">New: Python SDK</span>
-            <h1>Run scripts in clean microVMs with persistent workspaces.</h1>
+            <h1>Secure sandboxes that boot in milliseconds. Your data stays.</h1>
             <p class="lead">
-              Mags gives developers a CLI, Python SDK, and Node.js SDK for running
-              code in isolated microVMs. Keep files and packages between runs, and
-              expose a URL or SSH session when you need it.
+              Give your AI agents and scripts a safe place to run. Every sandbox is
+              completely isolated, boots instantly, and syncs your files to the cloud
+              automatically. Perfect for agents, scheduled jobs, and anything that
+              needs to run without risk.
             </p>
             <div class="hero-actions">
               <a class="button" href="#quickstart">Quickstart</a>
@@ -54,7 +55,7 @@
             </div>
             <div class="hero-meta">
               <span>CLI, Python, and Node.js &mdash; pick your tool.</span>
-              <span>VMs boot in ~300ms. Workspaces persist to S3.</span>
+              <span>Sandboxes in ~300ms. Files persist to the cloud between runs.</span>
             </div>
           </div>
           <div class="hero-card tab-group" aria-label="Mags example">
@@ -68,7 +69,7 @@
 
 mags run -w myproject 'pip install flask'
 mags ssh myproject</code></pre>
-              <p class="card-note">Run a script, persist a workspace, then jump in with SSH.</p>
+              <p class="card-note">Run a script, keep your files, then jump in with SSH.</p>
             </div>
             <div class="tab-content" data-tab="hero-python">
               <pre><code>from mags import Mags
@@ -95,7 +96,7 @@ console.log(result.logs);</code></pre>
         <div class="container">
           <div class="section-title">
             <p>Quickstart</p>
-            <h2>Get from zero to your first run.</h2>
+            <h2>Three steps. Your first sandbox in under a minute.</h2>
           </div>
           <div class="tab-group">
             <div class="tab-bar">
@@ -118,7 +119,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 persist files between runs.</p>
+                  <p>Add <code>-w myproject</code> to keep files between runs, synced to the cloud.</p>
                 </article>
               </div>
             </div>
@@ -174,7 +175,7 @@ console.log(result.status); // "completed"</code></pre>
         <div class="container">
           <div class="section-title">
             <p>Usage Patterns</p>
-            <h2>Everything you can do with Mags.</h2>
+            <h2>Run agents. Schedule jobs. Deploy apps. All sandboxed.</h2>
           </div>
           <div class="tab-group">
             <div class="tab-bar">
@@ -197,16 +198,16 @@ mags login</code></pre>
                   <table class="ref-table">
                     <thead><tr><th>Command</th><th>Description</th></tr></thead>
                     <tbody>
-                      <tr><td><code>mags run &lt;script&gt;</code></td><td>Execute a script in a fresh microVM</td></tr>
-                      <tr><td><code>mags ssh &lt;workspace&gt;</code></td><td>SSH into a VM (auto-starts if needed)</td></tr>
+                      <tr><td><code>mags 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 list</code></td><td>List recent jobs</td></tr>
                       <tr><td><code>mags status &lt;id&gt;</code></td><td>Get job status</td></tr>
                       <tr><td><code>mags logs &lt;id&gt;</code></td><td>Get job output</td></tr>
                       <tr><td><code>mags stop &lt;id&gt;</code></td><td>Stop a running job</td></tr>
-                      <tr><td><code>mags sync &lt;workspace&gt;</code></td><td>Sync workspace to S3 (without stopping VM)</td></tr>
+                      <tr><td><code>mags 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 workspace list</code></td><td>List persistent workspaces</td></tr>
-                      <tr><td><code>mags workspace delete &lt;id&gt;</code></td><td>Delete workspace + S3 data</td></tr>
+                      <tr><td><code>mags workspace delete &lt;id&gt;</code></td><td>Delete workspace + cloud data</td></tr>
                       <tr><td><code>mags cron add [opts] &lt;script&gt;</code></td><td>Create a scheduled cron job</td></tr>
                       <tr><td><code>mags cron list</code></td><td>List cron jobs</td></tr>
                       <tr><td><code>mags cron remove &lt;id&gt;</code></td><td>Delete a cron job</td></tr>
@@ -221,15 +222,16 @@ mags login</code></pre>
                   <table class="ref-table">
                     <thead><tr><th>Flag</th><th>Description</th></tr></thead>
                     <tbody>
-                      <tr><td><code>-w, --workspace &lt;id&gt;</code></td><td>Persist files to S3 across runs</td></tr>
-                      <tr><td><code>--base &lt;workspace&gt;</code></td><td>Mount a workspace read-only as a base image</td></tr>
-                      <tr><td><code>-p, --persistent</code></td><td>Keep VM alive after script (sleeps when idle)</td></tr>
-                      <tr><td><code>-e, --ephemeral</code></td><td>No S3 sync &mdash; fastest execution</td></tr>
-                      <tr><td><code>-f, --file &lt;path&gt;</code></td><td>Upload file(s) to VM (repeatable)</td></tr>
+                      <tr><td><code>-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>--startup-command &lt;cmd&gt;</code></td><td>Command to run when VM wakes from sleep</td></tr>
+                      <tr><td><code>--startup-command &lt;cmd&gt;</code></td><td>Command to run when sandbox wakes from sleep</td></tr>
                     </tbody>
                   </table>
                 </div>
@@ -246,22 +248,25 @@ mags run -w myproject 'python3 app.py'
 
 # Base image &mdash; create a golden image, sync it, then reuse
 mags run -w golden -p 'apt install -y nodejs && npm install -g typescript'
-mags sync golden                                # persist to S3
+mags 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 VM if needed)
+# SSH into a workspace (auto-starts sandbox if needed)
 mags ssh myproject
 
-# Persistent VM with public URL
+# Persistent sandbox with public URL
 mags run -w webapp -p --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 S3 sync)
+# Ephemeral (fastest &mdash; no cloud sync)
 mags run -e 'uname -a && df -h'
 
 # Cron job
@@ -292,7 +297,7 @@ export MAGS_API_TOKEN="your-token"</code></pre>
                       <tr><td><code>enable_access(id, port)</code></td><td>Enable URL or SSH access</td></tr>
                       <tr><td><code>upload_files(paths)</code></td><td>Upload files, returns file IDs</td></tr>
                       <tr><td><code>list_workspaces()</code></td><td>List persistent workspaces</td></tr>
-                      <tr><td><code>delete_workspace(id)</code></td><td>Delete workspace + S3 data</td></tr>
+                      <tr><td><code>delete_workspace(id)</code></td><td>Delete workspace + cloud data</td></tr>
                       <tr><td><code>cron_create(**opts)</code></td><td>Create a cron job</td></tr>
                       <tr><td><code>cron_list()</code></td><td>List cron jobs</td></tr>
                       <tr><td><code>cron_delete(id)</code></td><td>Delete a cron job</td></tr>
@@ -308,12 +313,13 @@ 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>Persist files to S3 across runs</td></tr>
+                      <tr><td><code>workspace_id</code></td><td>Keep files across runs (synced to the cloud)</td></tr>
                       <tr><td><code>base_workspace_id</code></td><td>Mount a workspace read-only as base image</td></tr>
-                      <tr><td><code>persistent</code></td><td>Keep VM alive after script completes</td></tr>
-                      <tr><td><code>ephemeral</code></td><td>No S3 sync (fastest)</td></tr>
+                      <tr><td><code>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>file_ids</code></td><td>List of uploaded file IDs to include</td></tr>
-                      <tr><td><code>startup_command</code></td><td>Command to run when VM wakes</td></tr>
+                      <tr><td><code>startup_command</code></td><td>Command to run when sandbox wakes</td></tr>
                     </tbody>
                   </table>
                 </div>
@@ -347,6 +353,10 @@ job = m.run("python3 -m http.server 8080",
     startup_command="python3 -m http.server 8080")
 access = m.enable_access(job["request_id"], port=8080)
 
+# Always-on sandbox (never auto-sleeps)
+job = m.run("python3 worker.py",
+    workspace_id="worker", persistent=True, no_sleep=True)
+
 # Upload files
 file_ids = m.upload_files(["script.py", "data.csv"])
 m.run_and_wait("python3 /uploads/script.py", file_ids=file_ids)
@@ -398,12 +408,13 @@ 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>Persist files to S3 across runs</td></tr>
+                      <tr><td><code>workspaceId</code></td><td>Keep files across runs (synced to the cloud)</td></tr>
                       <tr><td><code>baseWorkspaceId</code></td><td>Mount a workspace read-only as base image</td></tr>
-                      <tr><td><code>persistent</code></td><td>Keep VM alive after script completes</td></tr>
-                      <tr><td><code>ephemeral</code></td><td>No S3 sync (fastest)</td></tr>
+                      <tr><td><code>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>fileIds</code></td><td>Array of uploaded file IDs to include</td></tr>
-                      <tr><td><code>startupCommand</code></td><td>Command to run when VM wakes</td></tr>
+                      <tr><td><code>startupCommand</code></td><td>Command to run when sandbox wakes</td></tr>
                     </tbody>
                   </table>
                 </div>
@@ -439,6 +450,11 @@ const webJob = await mags.run('python3 -m http.server 8080', {
 const access = await mags.enableAccess(webJob.requestId, { port: 8080 });
 console.log(access.url);
 
+// Always-on sandbox (never auto-sleeps)
+await mags.run('python3 worker.py', {
+  workspaceId: 'worker', persistent: true, noSleep: true,
+});
+
 // Upload files
 const fileId = await mags.uploadFile('script.py');
 await mags.runAndWait('python3 /uploads/script.py', { fileIds: [fileId] });
@@ -459,24 +475,26 @@ await mags.cronCreate({
       <section class="section" id="workspaces">
         <div class="container">
           <div class="section-title">
-            <p>Workspaces</p>
-            <h2>Persist what matters, reset the rest.</h2>
+            <p>Persistent Workspaces</p>
+            <h2>Your files survive. Every sandbox starts clean.</h2>
           </div>
           <div class="grid split">
             <article class="panel" data-reveal>
-              <h3>What stays</h3>
+              <h3>Backed up to object storage</h3>
               <ul class="list">
-                <li>Files and directories in your workspace</li>
-                <li>Installed packages and dependencies</li>
-                <li>Configuration and dotfiles</li>
+                <li>Files, packages, and configs persist automatically</li>
+                <li>Optional backup to S3-compatible object storage</li>
+                <li>Clone a workspace as a read-only base for new sandboxes</li>
+                <li>Survives reboots, sleep, and agent restarts</li>
               </ul>
             </article>
             <article class="panel" data-reveal>
-              <h3>What resets</h3>
+              <h3>Fully isolated</h3>
               <ul class="list">
-                <li>Running processes</li>
-                <li>In-memory state</li>
-                <li>Open ports</li>
+                <li>Every sandbox runs in its own isolated environment</li>
+                <li>No cross-user access &mdash; workspaces are private</li>
+                <li>Processes, memory, and ports reset between runs</li>
+                <li>Agents can't escape or affect the host</li>
               </ul>
             </article>
           </div>
@@ -488,7 +506,7 @@ await mags.cronCreate({
         <div class="container">
           <div class="section-title">
             <p>SDKs + API</p>
-            <h2>Automate runs with Python, Node.js, or REST.</h2>
+            <h2>Let your agents spin up sandboxes programmatically.</h2>
           </div>
           <div class="tab-group">
             <div class="tab-bar">
@@ -508,7 +526,7 @@ m = Mags()  # reads MAGS_API_TOKEN from env
 
 # Run and wait
 result = m.run_and_wait(
-    "echo Hello from a VM!",
+    "echo Hello from a sandbox!",
     workspace_id="demo",
 )
 print(result["status"])
@@ -611,7 +629,7 @@ console.log(result.logs);</code></pre>
         <div class="container">
           <div class="section-title">
             <p>Resources</p>
-            <h2>Extra pages for day-to-day work.</h2>
+            <h2>Everything you need to get started.</h2>
           </div>
           <div class="grid cards">
             <article class="card" data-reveal>
@@ -631,7 +649,7 @@ console.log(result.logs);</code></pre>
             </article>
             <article class="card" data-reveal>
               <h3>Claude skill</h3>
-              <p>Install the Claude Code skill for microVM runs.</p>
+              <p>Install the Claude Code skill to run sandboxes from Claude.</p>
               <a class="text-link" href="claude-skill.html">Open Claude skill</a>
             </article>
             <article class="card" data-reveal>
@@ -649,9 +667,9 @@ console.log(result.logs);</code></pre>
         <div>
           <div class="brand">
             <span class="logo">Mags</span>
-            <span class="tag">Instant sandboxes and runtime environments</span>
+            <span class="tag">Secure cloud sandboxes for the AI age</span>
           </div>
-          <p>Build, test, and run from clean microVMs whenever you need them.</p>
+          <p>Secure, instant sandboxes for AI agents, developers, and automation.</p>
         </div>
         <div class="footer-links">
           <a href="login.html">Login</a>
@@ -667,7 +685,7 @@ console.log(result.logs);</code></pre>
       </div>
     </footer>
 
-    <script src="script.js?v=3"></script>
+    <script src="script.js?v=5"></script>
     <script>
     (function() {
       var token = localStorage.getItem('microvm-access-token');