@magpiecloud/mags 1.8.0 → 1.8.2

package/bin/mags.js

@@ -221,6 +221,7 @@ ${colors.bold}Run Options:${colors.reset}
   --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)
+  --disk <GB>                     Custom disk size in GB (default: 2)
   --url                           Enable public URL access (requires -p)
   --port <port>                   Port to expose for URL (default: 8080)
   --startup-command <cmd>         Command to run when VM wakes from sleep
@@ -395,10 +396,13 @@ To use Mags, you need to authenticate first.
 async function newVM(args) {
   let name = null;
   let baseWorkspace = null;
+  let diskGB = 0;
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--base' && args[i + 1]) {
       baseWorkspace = args[++i];
+    } else if (args[i] === '--disk' && args[i + 1]) {
+      diskGB = parseInt(args[++i]) || 0;
     } else if (!name) {
       name = args[i];
     }
@@ -406,7 +410,7 @@ async function newVM(args) {
 
   if (!name) {
     log('red', 'Error: Name required');
-    console.log(`\nUsage: mags new <name> [--base <workspace>]\n`);
+    console.log(`\nUsage: mags new <name> [--base <workspace>] [--disk <GB>]\n`);
     process.exit(1);
   }
 
@@ -419,6 +423,7 @@ async function newVM(args) {
     startup_command: 'sleep infinity'
   };
   if (baseWorkspace) payload.base_workspace_id = baseWorkspace;
+  if (diskGB) payload.disk_gb = diskGB;
 
   const response = await request('POST', '/api/v1/mags-jobs', payload);
 
@@ -463,6 +468,7 @@ async function runJob(args) {
   let enableUrl = false;
   let port = 8080;
   let startupCommand = '';
+  let diskGB = 0;
   let fileArgs = [];
 
   // Parse flags
@@ -500,6 +506,9 @@ async function runJob(args) {
       case '--port':
         port = parseInt(args[++i]) || 8080;
         break;
+      case '--disk':
+        diskGB = parseInt(args[++i]) || 0;
+        break;
       case '--startup-command':
         startupCommand = args[++i];
         break;
@@ -562,6 +571,7 @@ async function runJob(args) {
   if (baseWorkspace) payload.base_workspace_id = baseWorkspace;
   if (startupCommand) payload.startup_command = startupCommand;
   if (fileIds.length > 0) payload.file_ids = fileIds;
+  if (diskGB) payload.disk_gb = diskGB;
 
   const response = await request('POST', '/api/v1/mags-jobs', payload);
 
@@ -589,6 +599,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) {
@@ -597,7 +615,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;
@@ -1348,7 +1366,7 @@ async function main() {
         break;
       case '--version':
       case '-v':
-        console.log('mags v1.8.0');
+        console.log('mags v1.8.2');
         process.exit(0);
         break;
       case 'new':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpiecloud/mags",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "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.1.0"
+version = "1.3.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.3.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.1.0"
+__version__ = "1.3.0"

package/python/src/mags/client.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import os
+import subprocess
+import tempfile
 import time
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -103,6 +105,7 @@ class Mags:
         startup_command: str | None = None,
         environment: Dict[str, str] | None = None,
         file_ids: List[str] | None = None,
+        disk_gb: int | None = None,
     ) -> dict:
         """Submit a job for execution.
 
@@ -134,6 +137,8 @@ class Mags:
             payload["environment"] = environment
         if file_ids:
             payload["file_ids"] = file_ids
+        if disk_gb:
+            payload["disk_gb"] = disk_gb
 
         return self._request("POST", "/mags-jobs", json=payload)
 
@@ -198,12 +203,196 @@ class Mags:
             "POST", f"/mags-jobs/{request_id}/access", json={"port": port}
         )
 
+    def stop(self, name_or_id: str) -> dict:
+        """Stop a running job.
+
+        Accepts a job ID, job name, or workspace ID.
+        """
+        request_id = self._resolve_job_id(name_or_id)
+        return self._request("POST", f"/mags-jobs/{request_id}/stop")
+
+    def new(
+        self,
+        name: str,
+        *,
+        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.
+
+        Equivalent to ``mags new <name>``.
+
+        Returns ``{"request_id": ..., "status": "running"}``.
+        """
+        result = self.run(
+            "sleep infinity",
+            workspace_id=name,
+            persistent=True,
+            base_workspace_id=base_workspace_id,
+            disk_gb=disk_gb,
+        )
+        request_id = result["request_id"]
+
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            st = self.status(request_id)
+            if st["status"] == "running" and st.get("vm_id"):
+                return {"request_id": request_id, "status": "running"}
+            if st["status"] in ("completed", "error"):
+                raise MagsError(f"Job {request_id} ended unexpectedly: {st['status']}")
+            time.sleep(poll_interval)
+
+        raise MagsError(f"Job {request_id} did not start within {timeout}s")
+
+    def find_job(self, name_or_id: str) -> dict | None:
+        """Find a running or sleeping job by name, workspace ID, or job ID.
+
+        Uses the same resolution priority as the CLI:
+        running/sleeping exact name → workspace ID → any status exact name.
+        Returns the job dict or ``None``.
+        """
+        jobs = self.list_jobs(page_size=50).get("jobs", [])
+
+        # Priority 1: exact name match, running/sleeping
+        for j in jobs:
+            if j.get("name") == name_or_id and j.get("status") in ("running", "sleeping"):
+                return j
+
+        # Priority 2: workspace_id match, running/sleeping
+        for j in jobs:
+            if j.get("workspace_id") == name_or_id and j.get("status") in ("running", "sleeping"):
+                return j
+
+        # Priority 3: exact name match, any status
+        for j in jobs:
+            if j.get("name") == name_or_id:
+                return j
+
+        # Priority 4: workspace_id match, any status
+        for j in jobs:
+            if j.get("workspace_id") == name_or_id:
+                return j
+
+        return None
+
+    def url(self, name_or_id: str, *, port: int = 8080) -> dict:
+        """Enable public URL access for a job's VM.
+
+        Accepts a job ID, job name, or workspace ID.
+        Returns dict with ``url`` and access details.
+        """
+        request_id = self._resolve_job_id(name_or_id)
+        st = self.status(request_id)
+        resp = self.enable_access(request_id, port=port)
+        subdomain = st.get("subdomain") or resp.get("subdomain")
+        if subdomain:
+            resp["url"] = f"https://{subdomain}.apps.magpiecloud.com"
+        return resp
+
+    def exec(self, name_or_id: str, command: str, *, timeout: int = 30) -> dict:
+        """Execute a command on an existing running/sleeping sandbox via SSH.
+
+        Equivalent to ``mags exec <workspace> '<command>'``.
+
+        Returns ``{"exit_code": int, "output": str}``.
+        """
+        job = self.find_job(name_or_id)
+        if not job:
+            raise MagsError(f"No running or sleeping VM found for '{name_or_id}'")
+        if job["status"] not in ("running", "sleeping"):
+            raise MagsError(
+                f"VM for '{name_or_id}' is {job['status']}, needs to be running or sleeping"
+            )
+
+        request_id = job.get("request_id") or job.get("id")
+
+        # Wait for VM to be assigned (status=running doesn't guarantee vm_id yet)
+        for _ in range(15):
+            st = self.status(request_id)
+            if st.get("vm_id"):
+                break
+            time.sleep(1)
+        else:
+            raise MagsError(f"VM for '{name_or_id}' has no vm_id after 15s")
+
+        access = self.enable_access(request_id, port=22)
+
+        if not access.get("success") or not access.get("ssh_host"):
+            raise MagsError(
+                f"Failed to enable SSH access: {access.get('error', 'unknown error')}"
+            )
+
+        ssh_host = access["ssh_host"]
+        ssh_port = str(access["ssh_port"])
+        ssh_key = access.get("ssh_private_key", "")
+
+        # Wrap command to handle chroot overlay, same as CLI
+        escaped = command.replace("'", "'\\''")
+        wrapped = (
+            f"if [ -d /overlay/bin ]; then "
+            f"chroot /overlay /bin/sh -l -c 'cd /root 2>/dev/null; {escaped}'; "
+            f"else cd /root 2>/dev/null; {escaped}; fi"
+        )
+
+        key_file = None
+        try:
+            ssh_args = [
+                "ssh",
+                "-o", "StrictHostKeyChecking=no",
+                "-o", "UserKnownHostsFile=/dev/null",
+                "-o", "LogLevel=ERROR",
+                "-p", ssh_port,
+            ]
+            if ssh_key:
+                fd, key_file = tempfile.mkstemp(prefix="mags_ssh_")
+                os.write(fd, ssh_key.encode())
+                os.close(fd)
+                os.chmod(key_file, 0o600)
+                ssh_args.extend(["-i", key_file])
+
+            ssh_args.append(f"root@{ssh_host}")
+            ssh_args.append(wrapped)
+
+            proc = subprocess.run(
+                ssh_args,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+            return {
+                "exit_code": proc.returncode,
+                "output": proc.stdout,
+                "stderr": proc.stderr,
+            }
+        except subprocess.TimeoutExpired:
+            raise MagsError(f"Command timed out after {timeout}s")
+        finally:
+            if key_file:
+                try:
+                    os.unlink(key_file)
+                except OSError:
+                    pass
+
     def usage(self, *, window_days: int = 30) -> dict:
         """Get aggregated usage summary."""
         return self._request(
             "GET", "/mags-jobs/usage", params={"window_days": window_days}
         )
 
+    # ── internal helpers ─────────────────────────────────────────────
+
+    def _resolve_job_id(self, name_or_id: str) -> str:
+        """Resolve a job name, workspace ID, or UUID to a request_id."""
+        # If it looks like a UUID, use directly
+        if len(name_or_id) >= 32 and "-" in name_or_id:
+            return name_or_id
+        job = self.find_job(name_or_id)
+        if not job:
+            raise MagsError(f"No job found for '{name_or_id}'")
+        return job.get("request_id") or job.get("id")
+
     # ── file uploads ─────────────────────────────────────────────────
 
     def upload_file(self, file_path: str) -> str:

package/python/test_sdk.py

@@ -0,0 +1,78 @@
+"""Test the Mags Python SDK: new, exec, url."""
+
+import os
+import sys
+import time
+
+os.environ["MAGS_API_TOKEN"] = "da214df72c164bda47970491fd839247a864c2599305ce90b38512d43ed034ea"
+
+# Use local src/ instead of installed package
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src"))
+
+from mags import Mags
+
+m = Mags()
+WS = "sdk-test-" + str(int(time.time()))
+
+print(f"=== Test 1: Create new VM ({WS}) ===")
+result = m.new(WS)
+print(f"  request_id: {result['request_id']}")
+print(f"  status:     {result['status']}")
+assert result["status"] == "running"
+print("  PASS\n")
+
+print("=== Test 2: find_job ===")
+job = m.find_job(WS)
+print(f"  found: workspace={job.get('workspace_id')} status={job.get('status')}")
+assert job is not None
+assert job["status"] == "running"
+print("  PASS\n")
+
+print("=== Test 3: exec - simple command ===")
+try:
+    result = m.exec(WS, "echo HELLO_FROM_SDK && uname -a", timeout=15)
+    print(f"  exit_code: {result['exit_code']}")
+    print(f"  output:    {result['output'].strip()}")
+    if result["stderr"]:
+        print(f"  stderr:    {result['stderr'].strip()}")
+    assert "HELLO_FROM_SDK" in result["output"]
+    print("  PASS\n")
+except Exception as e:
+    print(f"  FAIL: {e}\n")
+
+print("=== Test 4: exec - create HTML file ===")
+html = "<html><body><h1>Mags SDK Test</h1><p>Served from a microVM!</p></body></html>"
+try:
+    result = m.exec(WS, f"echo '{html}' > /root/index.html", timeout=15)
+    print(f"  exit_code: {result['exit_code']}")
+    result = m.exec(WS, "cat /root/index.html", timeout=15)
+    print(f"  content: {result['output'].strip()[:80]}...")
+    print("  PASS\n")
+except Exception as e:
+    print(f"  FAIL: {e}\n")
+
+print("=== Test 5: exec - start python HTTP server ===")
+try:
+    result = m.exec(WS, "nohup python3 -m http.server 8080 --directory /root > /tmp/srv.log 2>&1 & echo PID=$!", timeout=15)
+    print(f"  output: {result['output'].strip()}")
+    time.sleep(1)
+    # Verify it's running
+    result = m.exec(WS, "curl -s http://localhost:8080/index.html | head -1", timeout=15)
+    print(f"  curl:   {result['output'].strip()[:80]}")
+    print("  PASS\n")
+except Exception as e:
+    print(f"  FAIL: {e}\n")
+
+print("=== Test 6: url - enable public URL ===")
+try:
+    info = m.url(WS, port=8080)
+    print(f"  success: {info.get('success')}")
+    print(f"  url:     {info.get('url', 'N/A')}")
+    if info.get("url"):
+        print(f"\n  >>> Visit: {info['url']} <<<")
+    print("  PASS\n")
+except Exception as e:
+    print(f"  FAIL: {e}\n")
+
+print("=== All tests complete ===")
+print(f"Workspace: {WS}")

package/website/api.html

@@ -360,6 +360,12 @@ m = Mags(api_token="your-token")
                   <td>no</td>
                   <td>File IDs from the upload endpoint. Files are downloaded into <code>/root/</code> before script runs.</td>
                 </tr>
+                <tr>
+                  <td><code>disk_gb</code></td>
+                  <td>int</td>
+                  <td>no</td>
+                  <td>Custom disk size in GB. Default is 2GB. The rootfs is resized on-the-fly after VM boot.</td>
+                </tr>
               </tbody>
             </table>
 

package/website/index.html

@@ -200,6 +200,7 @@ mags login</code></pre>
                     <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>
@@ -231,6 +232,7 @@ mags login</code></pre>
                       <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>
                       <tr><td><code>--startup-command &lt;cmd&gt;</code></td><td>Command to run when sandbox wakes from sleep</td></tr>
                     </tbody>
                   </table>
@@ -255,6 +257,9 @@ mags run --base golden -w fork-1 'npm test'     # fork: load golden, save to for
 # SSH into a workspace (auto-starts sandbox if needed)
 mags ssh myproject
 
+# Run a command on an existing sandbox
+mags exec myproject 'node --version'
+
 # Persistent sandbox with public URL
 mags run -w webapp -p --url --port 8080 \
   --startup-command 'python3 -m http.server 8080' \
@@ -291,13 +296,19 @@ export MAGS_API_TOKEN="your-token"</code></pre>
                     <tbody>
                       <tr><td><code>run(script, **opts)</code></td><td>Submit a job (returns immediately)</td></tr>
                       <tr><td><code>run_and_wait(script, **opts)</code></td><td>Submit + block until complete</td></tr>
+                      <tr><td><code>new(name)</code></td><td>Create persistent VM workspace</td></tr>
+                      <tr><td><code>exec(name, command)</code></td><td>Run command on existing sandbox</td></tr>
+                      <tr><td><code>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>status(request_id)</code></td><td>Get job status</td></tr>
                       <tr><td><code>logs(request_id)</code></td><td>Get job logs</td></tr>
                       <tr><td><code>list_jobs()</code></td><td>List recent jobs</td></tr>
-                      <tr><td><code>enable_access(id, port)</code></td><td>Enable URL or SSH access</td></tr>
+                      <tr><td><code>enable_access(id, port)</code></td><td>Enable URL or SSH access (low-level)</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>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>
@@ -334,27 +345,28 @@ m = Mags()  # reads MAGS_API_TOKEN from env
 result = m.run_and_wait("echo Hello World")
 print(result["status"])    # "completed"
 
-# Persistent workspace
-m.run_and_wait("pip install flask", workspace_id="myproject")
-m.run_and_wait("python3 app.py", workspace_id="myproject")
+# Create a persistent workspace
+m.new("my-project")
+
+# Execute commands on existing sandbox
+result = m.exec("my-project", "ls -la /root")
+print(result["output"])
+m.exec("my-project", "pip install flask")
 
-# Base image
-m.run_and_wait("npm test", base_workspace_id="golden")
-m.run_and_wait("npm test", base_workspace_id="golden", workspace_id="fork-1")
+# Stop a job
+m.stop("my-project")
 
-# SSH access
-job = m.run("sleep 3600", workspace_id="dev", persistent=True)
-ssh = m.enable_access(job["request_id"], port=22)
-print(f"ssh root@{ssh['ssh_host']} -p {ssh['ssh_port']}")
+# Find a job by name or workspace
+job = m.find_job("my-project")
+print(job["status"])  # "running", "sleeping", etc.
 
 # Public URL
-job = m.run("python3 -m http.server 8080",
-    workspace_id="webapp", persistent=True,
-    startup_command="python3 -m http.server 8080")
-access = m.enable_access(job["request_id"], port=8080)
+m.new("webapp")
+info = m.url("webapp", port=3000)
+print(info["url"])  # https://xyz.apps.magpiecloud.com
 
 # Always-on sandbox (never auto-sleeps)
-job = m.run("python3 worker.py",
+m.run("python3 worker.py",
     workspace_id="worker", persistent=True, no_sleep=True)
 
 # Upload files
@@ -524,30 +536,30 @@ await mags.cronCreate({
 
 m = Mags()  # reads MAGS_API_TOKEN from env
 
-# Run and wait
-result = m.run_and_wait(
-    "echo Hello from a sandbox!",
-    workspace_id="demo",
-)
-print(result["status"])
-for log in result["logs"]:
-    print(log["message"])</code></pre>
+# Create a workspace, run commands on it
+m.new("demo")
+result = m.exec("demo", "uname -a")
+print(result["output"])
+
+# Or run a one-shot script
+result = m.run_and_wait("echo Hello!")
+print(result["status"])  # "completed"</code></pre>
                 </article>
                 <article class="panel" data-reveal>
                   <h3>Available methods</h3>
                   <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>status(request_id)</code> &mdash; get job status</li>
-                    <li><code>logs(request_id)</code> &mdash; get job logs</li>
-                    <li><code>list_jobs()</code> &mdash; list recent jobs</li>
-                    <li><code>enable_access(id, port)</code> &mdash; URL or SSH</li>
+                    <li><code>new(name)</code> &mdash; create persistent VM</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>status(id)</code> / <code>logs(id)</code> / <code>list_jobs()</code></li>
                     <li><code>upload_files(paths)</code> &mdash; upload files</li>
-                    <li><code>list_workspaces()</code> &mdash; list workspaces</li>
-                    <li><code>delete_workspace(id)</code> &mdash; delete workspace</li>
-                    <li><code>cron_create(**opts)</code> &mdash; create cron</li>
-                    <li><code>cron_list()</code> / <code>cron_delete(id)</code></li>
-                    <li><code>usage(window_days)</code> &mdash; usage stats</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>
                   </ul>
                   <p style="margin-top:1rem"><a class="text-link" href="https://pypi.org/project/magpie-mags/" rel="noreferrer">PyPI &rarr;</a></p>
                 </article>

package/website/llms.txt

@@ -29,6 +29,7 @@ mags run 'echo Hello World'
 - `mags new <workspace>` — Create a persistent VM workspace
 - `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 list` — List recent jobs
 - `mags logs <job-id>` — View job logs
@@ -42,10 +43,12 @@ mags run 'echo Hello World'
 | `-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 |
+| `--no-sleep` | Never auto-sleep this VM (requires -p) |
 | `-e, --ephemeral` | No workspace, no S3 sync (fastest). Cannot combine with -w or -p |
 | `-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 |
 
 ## File Upload
@@ -173,6 +176,48 @@ curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
   }'
 ```
 
+## Python SDK
+
+```
+pip install magpie-mags
+```
+
+```python
+from mags import Mags
+
+mags = Mags()  # uses MAGS_API_TOKEN env var
+
+# Run a script and wait for result
+result = mags.run_and_wait('echo Hello World')
+print(result['logs'])
+
+# Create a persistent workspace
+mags.new('my-project')
+
+# Execute a command on an existing sandbox
+result = mags.exec('my-project', 'ls -la /root')
+print(result['output'])
+
+# Stop a running job
+mags.stop('my-project')
+
+# Enable public URL
+info = mags.url('my-project', port=3000)
+print(info['url'])
+
+# Find a job by name or workspace
+job = mags.find_job('my-project')
+
+# Upload files and run
+file_ids = mags.upload_files(['script.py', 'data.csv'])
+mags.run('python3 script.py', file_ids=file_ids)
+
+# Cron jobs
+mags.cron_create(name='daily-backup', cron_expression='0 0 * * *',
+                 script='tar czf backup.tar.gz /data', workspace_id='my-ws')
+mags.cron_delete(cron_id)
+```
+
 ## Node.js SDK
 
 ```

package/website/mags.md

@@ -36,6 +36,11 @@ mags run -w <workspace> -p --url --port 3000 '<script>'
 mags new <name>
 ```
 
+### Execute a command on an existing sandbox
+```bash
+mags exec <name-or-id> '<command>'
+```
+
 ### SSH into a running VM
 ```bash
 mags ssh <name-or-id>
@@ -92,10 +97,12 @@ mags cron disable <id>
 | `-w, --workspace <id>` | Persistent workspace (S3 sync) |
 | `-n, --name <name>` | Job name for easier reference |
 | `-p, --persistent` | Keep VM alive after script |
+| `--no-sleep` | Never auto-sleep this VM (requires -p) |
 | `-e, --ephemeral` | No workspace, no S3 sync (fastest). Cannot combine with -w or -p |
 | `-f, --file <path>` | Upload a 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 VM wakes |
 
 ## Workflow
@@ -129,7 +136,19 @@ mags run -p --url 'python3 -m http.server 8080'
 ### Persistent workspace
 User: `/mags set up a node project in my-app workspace`
 ```bash
-mags run -w my-app 'apk add nodejs npm && mkdir -p /workspace/my-app && cd /workspace/my-app && npm init -y'
+mags run -w my-app 'cd /root && npm init -y && npm install express'
+```
+
+### Run more commands on existing workspace
+User: `/mags run my server in the my-app workspace`
+```bash
+mags run -w my-app -p --url --port 3000 'cd /root && node index.js'
+```
+
+### Exec into existing workspace sandbox
+User: `/mags install lodash in my-app`
+```bash
+mags exec my-app 'cd /root && npm install lodash'
 ```
 
 ### Ephemeral (no workspace, fastest)
@@ -150,6 +169,18 @@ User: `/mags run my analysis with the data file`
 mags run -f analyze.py -f data.csv 'python3 analyze.py'
 ```
 
+### Run a command on an existing sandbox
+User: `/mags check what's running on my-app`
+```bash
+mags exec my-app 'ps aux'
+```
+
+### Keep a VM always running (never auto-sleep)
+User: `/mags start a persistent server that never sleeps`
+```bash
+mags run -w my-server -p --no-sleep --url --port 3000 'cd /root && node server.js'
+```
+
 ### Schedule a cron job
 User: `/mags schedule a health check every hour`
 ```bash
@@ -169,3 +200,4 @@ Do NOT hardcode tokens or use environment variables for auth.
 3. The CLI handles job submission, polling, and log retrieval automatically
 4. For multi-line scripts, use semicolons or `&&` to chain commands
 5. If the user wants to create a VM and SSH in, use `mags new <name>` then `mags ssh <name>`
+6. To run a command on an already-running sandbox, use `mags exec <name> '<command>'` instead of starting a new run