@magpiecloud/mags 1.8.12 → 1.8.14

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.6
 Summary: Mags SDK - Execute scripts on Magpie's instant VM infrastructure
 Author: Magpie Cloud
 License: MIT
@@ -156,19 +156,23 @@ 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 |
+| `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 |
@@ -179,4 +183,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/src/mags/client.py

@@ -3,8 +3,6 @@
 from __future__ import annotations
 
 import os
-import subprocess
-import tempfile
 import time
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -355,11 +353,11 @@ class Mags:
         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.
+        """Execute a command on an existing running/sleeping sandbox.
 
         Equivalent to ``mags exec <workspace> '<command>'``.
 
-        Returns ``{"exit_code": int, "output": str}``.
+        Returns ``{"exit_code": int, "output": str, "stderr": str}``.
         """
         job = self.find_job(name_or_id)
         if not job:
@@ -370,65 +368,17 @@ class Mags:
             )
 
         request_id = job.get("request_id") or job.get("id")
-
-        # Call /access directly — for sleeping VMs this triggers the wake
-        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"
+        resp = self._request(
+            "POST",
+            f"/mags-jobs/{request_id}/exec",
+            json={"command": command, "timeout": timeout},
+            timeout=timeout + 10,  # HTTP timeout > command timeout
         )
-
-        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
+        return {
+            "exit_code": resp.get("exit_code", -1),
+            "output": resp.get("stdout", ""),
+            "stderr": resp.get("stderr", ""),
+        }
 
     def usage(self, *, window_days: int = 30) -> dict:
         """Get aggregated usage summary."""

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=8" />
     <script src="env.js"></script>
     <style>
       .endpoint { margin-bottom: 2.5rem; }
@@ -30,10 +30,10 @@
         font-weight: 600;
         text-transform: uppercase;
       }
-      .method.post { background: rgba(47, 143, 99, 0.15); color: #237c52; }
-      .method.get { background: rgba(59, 130, 246, 0.15); color: #2563eb; }
-      .method.patch { background: rgba(245, 158, 11, 0.15); color: #b45309; }
-      .method.delete { background: rgba(239, 68, 68, 0.15); color: #dc2626; }
+      .method.post { background: rgba(47, 155, 102, 0.2); color: #3dbd7e; }
+      .method.get { background: rgba(59, 130, 246, 0.2); color: #60a5fa; }
+      .method.patch { background: rgba(245, 158, 11, 0.2); color: #fbbf24; }
+      .method.delete { background: rgba(239, 68, 68, 0.2); color: #f87171; }
       .url-path {
         font-family: var(--mono);
         font-size: 0.95rem;
@@ -109,7 +109,7 @@
         </div>
         <nav class="nav-links">
           <a href="index.html">Home</a>
-          <a href="index.html#quickstart">Docs</a>
+          <a href="docs.html">Docs</a>
           <a href="cookbook.html">Cookbook</a>
           <a href="claude-skill.html">Claude Skill</a>
           <a href="https://discord.gg/3avpC2nS" target="_blank" rel="noreferrer">Discord</a>
@@ -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/claude-skill.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=8" />
     <script src="env.js"></script>
   </head>
   <body>
@@ -24,7 +24,7 @@
         </div>
         <nav class="nav-links">
           <a href="index.html">Home</a>
-          <a href="index.html#quickstart">Docs</a>
+          <a href="docs.html">Docs</a>
           <a href="api.html">API</a>
           <a href="cookbook.html">Cookbook</a>
           <a href="https://discord.gg/3avpC2nS" target="_blank" rel="noreferrer">Discord</a>

package/website/cookbook/hn-marketing.html

@@ -69,7 +69,7 @@
         padding: 0.5rem 1rem;
         border-radius: 999px;
         border: 1px solid var(--border);
-        background: #ffffff;
+        background: var(--surface);
         color: var(--text-muted);
         font-size: 0.85rem;
         font-family: var(--sans);

package/website/cookbook.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=8" />
     <script src="env.js"></script>
   </head>
   <body>
@@ -24,14 +24,14 @@
         </div>
         <nav class="nav-links">
           <a href="index.html">Home</a>
-          <a href="index.html#quickstart">Docs</a>
+          <a href="docs.html">Docs</a>
           <a href="api.html">API</a>
           <a href="claude-skill.html">Claude Skill</a>
           <a href="https://discord.gg/3avpC2nS" target="_blank" rel="noreferrer">Discord</a>
           <a href="login.html">Login</a>
         </nav>
         <div class="nav-cta">
-          <a class="button ghost" href="index.html#quickstart">Get started</a>
+          <a class="button ghost" href="docs.html#quickstart">Get started</a>
         </div>
       </div>
     </header>