@magpiecloud/mags 1.8.3 → 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,11 +202,15 @@ ${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
   list                            List recent jobs
   url <name|id> [port]            Enable URL access for a job
+  url alias <sub> <workspace>    Create a stable URL alias for a workspace
+  url alias list                 List your URL aliases
+  url alias remove <subdomain>   Delete a URL alias
   stop <name|id>                  Stop a running job
   resize <workspace> --disk <GB>  Resize a workspace's disk (restarts VM)
   sync <workspace|id>             Sync workspace to S3 (without stopping)
@@ -215,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
@@ -237,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}
@@ -248,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/'
@@ -260,6 +264,10 @@ ${colors.bold}Examples:${colors.reset}
   mags status myvm
   mags logs myvm
   mags url myvm 8080
+  mags url alias my-api myvm          # Stable URL: my-api.apps.magpiecloud.com
+  mags url alias my-api myvm --lfg    # Stable URL: my-api.app.lfg.run
+  mags url alias list                 # List all aliases
+  mags url alias remove my-api        # Remove alias
   mags setup-claude                 # Install Claude Code skill
 `);
   process.exit(1);
@@ -460,7 +468,6 @@ async function newVM(args) {
 
 async function runJob(args) {
   let script = '';
-  let workspace = '';
   let baseWorkspace = '';
   let name = '';
   let persistent = false;
@@ -477,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];
@@ -525,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) {
@@ -566,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;
@@ -585,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');
 
@@ -668,6 +674,98 @@ async function enableUrlAccess(nameOrId, port = 8080) {
   }
 }
 
+async function urlAliasCommand(args) {
+  if (args.length === 0) {
+    log('red', 'Error: URL alias subcommand required');
+    console.log('\nUsage:');
+    console.log('  mags url alias <subdomain> <workspace> [--lfg]');
+    console.log('  mags url alias list');
+    console.log('  mags url alias remove <subdomain>');
+    process.exit(1);
+  }
+
+  const subcommand = args[0];
+
+  switch (subcommand) {
+    case 'list':
+    case 'ls':
+      await urlAliasList();
+      break;
+    case 'remove':
+    case 'rm':
+    case 'delete':
+      if (!args[1]) {
+        log('red', 'Error: Subdomain required');
+        console.log('\nUsage: mags url alias remove <subdomain>');
+        process.exit(1);
+      }
+      await urlAliasRemove(args[1]);
+      break;
+    default:
+      // mags url alias <subdomain> <workspace> [--lfg]
+      const subdomain = args[0];
+      const workspace = args[1];
+      if (!workspace) {
+        log('red', 'Error: Workspace required');
+        console.log('\nUsage: mags url alias <subdomain> <workspace> [--lfg]');
+        process.exit(1);
+      }
+      const useLfg = args.includes('--lfg');
+      await urlAliasCreate(subdomain, workspace, useLfg);
+      break;
+  }
+}
+
+async function urlAliasCreate(subdomain, workspaceId, useLfg) {
+  const domain = useLfg ? 'app.lfg.run' : 'apps.magpiecloud.com';
+  log('blue', `Creating URL alias: ${subdomain}.${domain} → workspace '${workspaceId}'...`);
+
+  const resp = await request('POST', '/api/v1/mags-url-aliases', {
+    subdomain,
+    workspace_id: workspaceId,
+    domain,
+  });
+
+  if (resp.error) {
+    log('red', `Error: ${resp.error}`);
+    process.exit(1);
+  }
+
+  if (resp.url) {
+    log('green', `URL alias created: ${resp.url}`);
+  } else {
+    log('green', `URL alias created: https://${subdomain}.${domain}`);
+  }
+}
+
+async function urlAliasList() {
+  const resp = await request('GET', '/api/v1/mags-url-aliases');
+  const aliases = resp.aliases || [];
+
+  if (aliases.length > 0) {
+    log('cyan', 'URL Aliases:\n');
+    aliases.forEach(a => {
+      console.log(`  ${colors.bold}${a.subdomain}${colors.reset}`);
+      console.log(`    URL: ${colors.green}${a.url}${colors.reset}`);
+      console.log(`    Workspace: ${a.workspace_id}  Domain: ${a.domain}`);
+      console.log('');
+    });
+    log('gray', `Total: ${aliases.length} alias(es)`);
+  } else {
+    log('yellow', 'No URL aliases found');
+  }
+}
+
+async function urlAliasRemove(subdomain) {
+  log('blue', `Removing URL alias '${subdomain}'...`);
+  const resp = await request('DELETE', `/api/v1/mags-url-aliases/${subdomain}`);
+  if (resp.error) {
+    log('red', `Error: ${resp.error}`);
+    process.exit(1);
+  }
+  log('green', resp.message || `URL alias '${subdomain}' removed`);
+}
+
 async function getStatus(nameOrId) {
   if (!nameOrId) {
     log('red', 'Error: Job name or ID required');
@@ -1190,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');
@@ -1236,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);
@@ -1422,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':
@@ -1437,13 +1643,21 @@ 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(' '));
         break;
       case 'url':
         await requireAuth();
-        await enableUrlAccess(args[1], parseInt(args[2]) || 8080);
+        if (args[1] === 'alias') {
+          await urlAliasCommand(args.slice(2));
+        } else {
+          await enableUrlAccess(args[1], parseInt(args[2]) || 8080);
+        }
         break;
       case 'status':
         await requireAuth();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpiecloud/mags",
-  "version": "1.8.3",
+  "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.0"
+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"):
@@ -507,3 +513,36 @@ class Mags:
     def cron_delete(self, cron_id: str) -> dict:
         """Delete a cron job."""
         return self._request("DELETE", f"/mags-cron/{cron_id}")
+
+    # ── URL aliases ──────────────────────────────────────────────────
+
+    def url_alias_create(
+        self,
+        subdomain: str,
+        workspace_id: str,
+        domain: str = "apps.magpiecloud.com",
+    ) -> dict:
+        """Create a stable URL alias for a workspace.
+
+        The alias maps ``subdomain.<domain>`` to the active job in the workspace.
+        Use ``domain="app.lfg.run"`` for the LFG domain.
+
+        Returns ``{"id": ..., "subdomain": ..., "url": ...}``.
+        """
+        return self._request(
+            "POST",
+            "/mags-url-aliases",
+            json={
+                "subdomain": subdomain,
+                "workspace_id": workspace_id,
+                "domain": domain,
+            },
+        )
+
+    def url_alias_list(self) -> dict:
+        """List all URL aliases. Returns ``{"aliases": [...], "total": N}``."""
+        return self._request("GET", "/mags-url-aliases")
+
+    def url_alias_delete(self, subdomain: str) -> dict:
+        """Delete a URL alias by subdomain."""
+        return self._request("DELETE", f"/mags-url-aliases/{subdomain}")