@magpiecloud/mags 1.8.4 → 1.8.5

package/API.md

@@ -39,6 +39,7 @@ Creates a VM, runs a script, and returns. The VM boots in ~300ms from a pool.
   "workspace_id": "my-project",
   "base_workspace_id": "my-base",
   "persistent": false,
+  "no_sleep": false,
   "startup_command": "python3 -m http.server 8080",
   "environment": { "FOO": "bar" },
   "file_ids": ["file-uuid-1", "file-uuid-2"]
@@ -52,6 +53,7 @@ Creates a VM, runs a script, and returns. The VM boots in ~300ms from a pool.
 | `workspace_id` | string | no | Persistent workspace name. Filesystem changes (apt install, files, configs) are synced to S3 and restored on next run. Omit for truly ephemeral (no sync). |
 | `base_workspace_id` | string | no | Mount an existing workspace **read-only** as the starting filesystem. Changes are discarded unless `workspace_id` is also set (fork pattern). |
 | `persistent` | bool | no | If `true`, VM stays alive after script finishes. Use for long-running servers, SSH access, or URL-exposed services. |
+| `no_sleep` | bool | no | If `true` with `persistent`, VM never auto-sleeps. Stays running 24/7 and auto-recovers if the host goes down. |
 | `startup_command` | string | no | Command to run when a sleeping persistent VM wakes up (on URL access). |
 | `environment` | object | no | Key-value env vars injected into the VM. |
 | `file_ids` | string[] | no | File IDs from the upload endpoint. Files are downloaded into `/root/` before script runs. |

package/QUICKSTART.md

@@ -148,6 +148,7 @@ mags run -w webapp-prod "..."
 | `-p, --persistent` | Keep VM alive for URL/SSH access | false |
 | `--url` | Enable public URL access (requires -p) | false |
 | `--port` | Port to expose for URL access | 8080 |
+| `--no-sleep` | Keep VM always running, never auto-sleep (requires -p) | false |
 | `--startup-command` | Command when VM wakes from sleep | none |
 | `-e, --ephemeral` | No S3 sync (faster, truly ephemeral) | false |
 | `-t, --timeout` | Timeout in seconds | 300 |
@@ -205,6 +206,16 @@ mags run -w myapp -p --url --startup-command "npm start" "npm install && npm sta
 # The app wakes automatically when someone visits the URL!
 ```
 
+### Always-On Server (Never Sleeps)
+
+```bash
+# Deploy a server that stays running 24/7
+mags run -w my-api -p --no-sleep --url --port 3000 "npm start"
+
+# VM never auto-sleeps, even when idle
+# Auto-recovers if the host goes down
+```
+
 ## Timeouts
 
 | Command | Default | Max | Flag |

package/README.md

@@ -116,6 +116,7 @@ mags run -p --url 'python3 -m http.server 8080'
 | `-p, --persistent` | Keep VM alive after script completes | false |
 | `--url` | Enable public URL access (requires -p) | false |
 | `--port <port>` | Port to expose for URL access | 8080 |
+| `--no-sleep` | Keep VM always running, never auto-sleep (requires -p) | false |
 | `--startup-command <cmd>` | Command to run when VM wakes from sleep | none |
 
 ## SSH Access
@@ -219,6 +220,20 @@ mags run -w flask-app -p --url 'pip install flask && python app.py'
 mags run -w api -p --url --startup-command 'python server.py' 'pip install -r requirements.txt && python server.py'
 ```
 
+### Always-On VMs
+
+By default, persistent VMs auto-sleep after 10 minutes of inactivity and wake on the next request. Use `--no-sleep` to keep a VM running 24/7:
+
+```bash
+# Always-on API server (never auto-sleeps)
+mags run -w my-api -p --no-sleep --url --port 3000 'npm start'
+
+# Always-on background worker
+mags run -w worker -p --no-sleep 'python worker.py'
+```
+
+If an always-on VM's host becomes unhealthy, the orchestrator automatically re-provisions it on a healthy agent within ~60 seconds.
+
 ### Interactive Development
 
 ```bash
@@ -257,6 +272,13 @@ const { requestId } = await mags.run('python script.py', {
   startupCommand: 'python server.py'
 });
 
+// Always-on VM (never auto-sleeps)
+await mags.run('node server.js', {
+  workspaceId: 'my-api',
+  persistent: true,
+  noSleep: true
+});
+
 // Get status
 const status = await mags.status(requestId);
 console.log(status);
@@ -298,7 +320,8 @@ curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
     "script": "echo Hello World",
     "type": "inline",
     "workspace_id": "myproject",
-    "persistent": true
+    "persistent": true,
+    "no_sleep": true
   }'
 ```
 

package/bin/mags.js

@@ -202,6 +202,7 @@ ${colors.bold}Commands:${colors.reset}
   new <name>                      Create a new persistent VM (returns ID only)
   run [options] <script>          Execute a script on a microVM
   ssh <workspace|name|id>         Open SSH session (auto-starts VM if needed)
+  browser [workspace]             Start a Chromium browser session (CDP access)
   exec <workspace> <command>      Run a command on an existing VM
   status <name|id>                Get job status
   logs <name|id>                  Get job logs
@@ -218,8 +219,7 @@ ${colors.bold}Commands:${colors.reset}
   setup-claude                    Install Mags skill for Claude Code
 
 ${colors.bold}Run Options:${colors.reset}
-  -w, --workspace <id>            Use persistent workspace (S3 sync)
-  -n, --name <name>               Set job name (for easier reference)
+  -n, --name <name>               Set job/workspace name (used as both)
   -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
@@ -240,7 +240,7 @@ ${colors.bold}Cron Commands:${colors.reset}
 ${colors.bold}Cron Options:${colors.reset}
   --name <name>                   Cron job name (required)
   --schedule <expr>               Cron expression (required, e.g. "0 * * * *")
-  -w, --workspace <id>            Workspace for cron jobs
+  -w, --workspace <id>            Workspace for cron jobs (alias for --name)
   -p, --persistent                Keep VM alive after cron script
 
 ${colors.bold}Examples:${colors.reset}
@@ -251,11 +251,12 @@ ${colors.bold}Examples:${colors.reset}
   mags run 'echo Hello World'
   mags run -e 'echo fast'           # Ephemeral (no S3 sync)
   mags run -f script.py 'python3 script.py'  # Upload + run file
-  mags run -w myproject 'python3 script.py'
+  mags run -n myproject 'python3 script.py'
   mags run --base golden 'npm test'           # Use golden as read-only base
-  mags run --base golden -w fork-1 'npm test' # Base + save changes to fork-1
+  mags run --base golden -n fork-1 'npm test' # Base + save changes to fork-1
   mags run -p --url 'python3 -m http.server 8080'
-  mags run -n webapp -w webapp -p --url --port 3000 'npm start'
+  mags run -n webapp -p --url --port 3000 'npm start'
+  mags browser myproject            # Start browser with workspace
   mags workspace list               # List workspaces
   mags workspace delete myproject   # Delete workspace
   mags cron add --name backup --schedule "0 0 * * *" 'tar czf backup.tar.gz data/'
@@ -467,7 +468,6 @@ async function newVM(args) {
 
 async function runJob(args) {
   let script = '';
-  let workspace = '';
   let baseWorkspace = '';
   let name = '';
   let persistent = false;
@@ -484,8 +484,6 @@ async function runJob(args) {
     switch (args[i]) {
       case '-w':
       case '--workspace':
-        workspace = args[++i];
-        break;
       case '-n':
       case '--name':
         name = args[++i];
@@ -532,8 +530,8 @@ async function runJob(args) {
   }
 
   // Validate flag combinations
-  if (ephemeral && workspace) {
-    log('red', 'Error: Cannot use --ephemeral with --workspace; ephemeral VMs have no persistent storage');
+  if (ephemeral && name) {
+    log('red', 'Error: Cannot use --ephemeral with --name; ephemeral VMs have no persistent storage');
     process.exit(1);
   }
   if (ephemeral && persistent) {
@@ -573,9 +571,11 @@ async function runJob(args) {
     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;
+  // name and workspace_id are always the same
+  if (name) {
+    payload.name = name;
+    if (!ephemeral) payload.workspace_id = name;
+  }
   if (baseWorkspace) payload.base_workspace_id = baseWorkspace;
   if (startupCommand) payload.startup_command = startupCommand;
   if (fileIds.length > 0) payload.file_ids = fileIds;
@@ -592,7 +592,6 @@ async function runJob(args) {
   const requestId = response.request_id;
   log('green', `Job submitted: ${requestId}`);
   if (name) log('blue', `Name: ${name}`);
-  if (workspace) log('blue', `Workspace: ${workspace}`);
   if (baseWorkspace) log('blue', `Base workspace: ${baseWorkspace} (read-only)`);
   if (persistent) log('yellow', 'Persistent: VM will stay alive');
 
@@ -1289,6 +1288,114 @@ async function workspaceDelete(workspaceId) {
   }
 }
 
+async function browserSession(args) {
+  let workspace = '';
+  let name = '';
+
+  // Parse args: mags browser [workspace] [--name <n>]
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === '-n' || args[i] === '--name') && args[i + 1]) {
+      name = args[++i];
+    } else if (!workspace) {
+      workspace = args[i];
+    }
+  }
+
+  // Check for existing running/sleeping browser session with this workspace
+  if (workspace) {
+    const existingJob = await findWorkspaceJob(workspace);
+
+    if (existingJob && existingJob.status === 'running') {
+      // Check if it's already a browser session
+      const status = await request('GET', `/api/v1/mags-jobs/${existingJob.request_id}/status`);
+      if (status.browser_mode && status.debug_ws_url) {
+        log('green', 'Found existing browser session');
+        console.log('');
+        log('cyan', `CDP Endpoint: ${status.debug_ws_url}`);
+        console.log('');
+        log('gray', 'Connect with Playwright:');
+        console.log(`  const browser = await chromium.connectOverCDP('${status.debug_ws_url}');`);
+        console.log('');
+        log('gray', 'Connect with Puppeteer:');
+        console.log(`  const browser = await puppeteer.connect({ browserWSEndpoint: '${status.debug_ws_url}' });`);
+        return;
+      }
+    }
+  }
+
+  log('blue', 'Starting browser session...');
+
+  const payload = {
+    script: 'echo "Browser session ready"',
+    type: 'inline',
+    browser_mode: true,
+    persistent: true
+  };
+  if (workspace) payload.workspace_id = workspace;
+  if (name) payload.name = name;
+  if (!name && workspace) payload.name = `browser-${workspace}`;
+
+  const response = await request('POST', '/api/v1/mags-jobs', payload);
+
+  if (!response.request_id) {
+    log('red', 'Failed to start browser session:');
+    console.log(JSON.stringify(response, null, 2));
+    process.exit(1);
+  }
+
+  const requestId = response.request_id;
+  log('gray', `Job: ${requestId}`);
+
+  // Wait for VM + Chromium to be ready
+  log('blue', 'Waiting for Chromium to start...');
+  let status;
+  for (let i = 0; i < 90; i++) {
+    status = await request('GET', `/api/v1/mags-jobs/${requestId}/status`);
+    if (status.status === 'running' && status.debug_ws_url) {
+      break;
+    }
+    if (status.status === 'error') {
+      log('red', `Browser session failed: ${status.error_message || 'Unknown error'}`);
+      process.exit(1);
+    }
+    process.stdout.write('.');
+    await sleep(1000);
+  }
+  console.log('');
+
+  if (!status || !status.debug_ws_url) {
+    // VM is running but no CDP URL yet - it may still be initializing
+    if (status && status.status === 'running' && status.subdomain) {
+      const wsUrl = `wss://${status.subdomain}.apps.magpiecloud.com`;
+      log('green', 'Browser session ready!');
+      console.log('');
+      log('cyan', `CDP Endpoint: ${wsUrl}`);
+      console.log('');
+      log('gray', 'Connect with Playwright:');
+      console.log(`  const browser = await chromium.connectOverCDP('${wsUrl}');`);
+      console.log('');
+      log('gray', 'Connect with Puppeteer:');
+      console.log(`  const browser = await puppeteer.connect({ browserWSEndpoint: '${wsUrl}' });`);
+    } else {
+      log('yellow', 'Browser session started but CDP URL not yet available.');
+      log('yellow', `Check status with: mags status ${requestId}`);
+    }
+    return;
+  }
+
+  log('green', 'Browser session ready!');
+  console.log('');
+  log('cyan', `CDP Endpoint: ${status.debug_ws_url}`);
+  console.log('');
+  log('gray', 'Connect with Playwright:');
+  console.log(`  const browser = await chromium.connectOverCDP('${status.debug_ws_url}');`);
+  console.log('');
+  log('gray', 'Connect with Puppeteer:');
+  console.log(`  const browser = await puppeteer.connect({ browserWSEndpoint: '${status.debug_ws_url}' });`);
+  console.log('');
+  log('gray', `Stop with: mags stop ${workspace || requestId}`);
+}
+
 async function sshToJob(nameOrId) {
   if (!nameOrId) {
     log('red', 'Error: Workspace, job name, or job ID required');
@@ -1335,11 +1442,11 @@ async function sshToJob(nameOrId) {
     jobID = response.request_id;
     log('gray', `Job: ${jobID}`);
 
-    // Wait for VM to be ready
+    // Wait for VM to be ready (status=running AND vm_id assigned)
     log('blue', 'Waiting for VM...');
-    for (let i = 0; i < 30; i++) {
+    for (let i = 0; i < 60; i++) {
       const status = await request('GET', `/api/v1/mags-jobs/${jobID}/status`);
-      if (status.status === 'running') break;
+      if (status.status === 'running' && status.vm_id) break;
       if (status.status === 'error') {
         log('red', 'VM failed to start');
         process.exit(1);
@@ -1521,7 +1628,7 @@ async function main() {
         break;
       case '--version':
       case '-v':
-        console.log('mags v1.8.3');
+        console.log('mags v1.8.5');
         process.exit(0);
         break;
       case 'new':
@@ -1536,6 +1643,10 @@ async function main() {
         await requireAuth();
         await sshToJob(args[1]);
         break;
+      case 'browser':
+        await requireAuth();
+        await browserSession(args.slice(1));
+        break;
       case 'exec':
         await requireAuth();
         await execOnJob(args[1], args.slice(2).join(' '));

package/package.json

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

package/python/README.md

@@ -66,6 +66,19 @@ m.run_and_wait(
 )
 ```
 
+### Always-On VMs
+
+```python
+# VM that never auto-sleeps — stays running 24/7
+job = m.run(
+    "python3 server.py",
+    workspace_id="my-api",
+    persistent=True,
+    no_sleep=True,
+)
+# Auto-recovers if the host goes down
+```
+
 ### Enable URL / SSH Access
 
 ```python
@@ -116,8 +129,13 @@ print(f"Jobs: {usage['total_jobs']}, VM seconds: {usage['vm_seconds']:.0f}")
 
 | Method | Description |
 |--------|-------------|
-| `run(script, **opts)` | Submit a job (returns immediately) |
+| `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 |
+| `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 |
+| `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 |

package/python/pyproject.toml

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: magpie-mags
-Version: 1.3.0
+Version: 1.3.2
 Summary: Mags SDK - Execute scripts on Magpie's instant VM infrastructure
 Author: Magpie Cloud
 License: MIT

package/python/src/mags/client.py

@@ -109,6 +109,20 @@ class Mags:
     ) -> dict:
         """Submit a job for execution.
 
+        Args:
+            script: Shell script to execute inside the VM.
+            name: Optional job name.
+            workspace_id: Persistent workspace name (synced to S3).
+            base_workspace_id: Read-only base workspace to mount.
+            persistent: Keep VM alive after script finishes.
+            no_sleep: Never auto-sleep this VM (requires persistent=True).
+                The VM stays running 24/7 and auto-recovers if its host goes down.
+            ephemeral: No S3 sync (faster, truly ephemeral).
+            startup_command: Command to run when VM wakes from sleep.
+            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).
+
         Returns ``{"request_id": ..., "status": "accepted"}``.
         """
         if ephemeral and workspace_id:
@@ -332,15 +346,7 @@ class Mags:
 
         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")
-
+        # 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"):