@magpiecloud/mags 1.3.0 → 1.4.0

package/README.md

@@ -18,7 +18,14 @@ mags login
 
 This will open your browser to create an API token. Paste the token when prompted, and it will be saved for future use.
 
-### 2. Run a script
+### 2. Create a persistent VM
+
+```bash
+mags new myproject
+mags ssh myproject
+```
+
+### 3. Or run a script
 
 ```bash
 mags run 'echo Hello World'
@@ -26,8 +33,6 @@ mags run 'echo Hello World'
 
 ## Authentication
 
-The CLI supports multiple authentication methods:
-
 ### Interactive Login (Recommended)
 
 ```bash
@@ -54,7 +59,13 @@ export MAGS_API_TOKEN="your-token-here"
 ## CLI Commands
 
 ```bash
-# Simple command
+# Create a persistent VM
+mags new myproject
+
+# SSH into it
+mags ssh myproject
+
+# Run a simple command
 mags run 'echo Hello'
 
 # With persistent workspace (S3 sync)
@@ -78,8 +89,26 @@ mags status <job-id>
 mags logs <job-id>
 mags list
 mags stop <job-id>
+
+# Install Claude Code skill
+mags setup-claude
 ```
 
+## Claude Code Integration
+
+Install the Mags skill for Claude Code to run scripts directly from Claude:
+
+```bash
+mags setup-claude
+```
+
+This lets you use natural language commands like:
+- `/mags run echo Hello World`
+- `/mags create a python environment with numpy and pandas`
+- `/mags run a flask server and give me the public URL`
+
+See [mags.run/claude-skill.html](https://mags.run/claude-skill.html) for full documentation.
+
 ## CLI Flags
 
 | Flag | Description | Default |
@@ -90,6 +119,27 @@ mags stop <job-id>
 | `--port` | Port to expose for URL access | 8080 |
 | `--startup-command` | Command when VM wakes from sleep | none |
 
+## SSH Access
+
+Connect to any running VM:
+
+```bash
+mags ssh myproject
+```
+
+Features:
+- Connects via secure proxy (`api.magpiecloud.com:PORT`)
+- Full PTY support for interactive terminals
+- Automatic SSH key management
+- Hostname: `mags-vm`
+
+## Workspaces & Persistence
+
+Your `/root` directory automatically syncs to S3:
+- **Auto-sync**: Every 30 seconds while running
+- **On stop**: Full sync before VM terminates
+- **On wake**: Previous state restored
+
 ## Node.js SDK
 
 ```javascript
@@ -134,6 +184,7 @@ await mags.stop(requestId);
 - **Warm start**: <100ms (VM from pool)
 - **Cold start**: ~4 seconds (new VM boot)
 - **Script overhead**: ~50ms
+- **Workspace sync**: Every 30 seconds
 
 ## License
 

package/bin/mags.js

@@ -14,6 +14,10 @@ const CONFIG_DIR = path.join(process.env.HOME || process.env.USERPROFILE, '.mags
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 const SSH_KEY_FILE = path.join(CONFIG_DIR, 'ssh_key');
 
+// Claude skill paths
+const CLAUDE_GLOBAL_DIR = path.join(process.env.HOME || process.env.USERPROFILE, '.claude', 'commands');
+const SKILL_URL = 'https://mags.run/mags.md';
+
 // Load saved config
 function loadConfig() {
   try {
@@ -182,6 +186,7 @@ ${colors.bold}Commands:${colors.reset}
   list                            List recent jobs
   url <name|id> [port]            Enable URL access for a job
   stop <name|id>                  Stop a running job
+  setup-claude                    Install Mags skill for Claude Code
 
 ${colors.bold}Run Options:${colors.reset}
   -w, --workspace <id>            Use persistent workspace (S3 sync)
@@ -202,6 +207,7 @@ ${colors.bold}Examples:${colors.reset}
   mags status myvm
   mags logs myvm
   mags url myvm 8080
+  mags setup-claude                 # Install Claude Code skill
 `);
   process.exit(1);
 }
@@ -586,6 +592,95 @@ async function stopJob(nameOrId) {
   }
 }
 
+// Download a file from URL
+function downloadFile(url) {
+  return new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    const lib = urlObj.protocol === 'https:' ? https : http;
+
+    lib.get(url, (res) => {
+      // Handle redirects
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        downloadFile(res.headers.location).then(resolve).catch(reject);
+        return;
+      }
+
+      if (res.statusCode !== 200) {
+        reject(new Error(`Failed to download: HTTP ${res.statusCode}`));
+        return;
+      }
+
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve(data));
+    }).on('error', reject);
+  });
+}
+
+async function setupClaude() {
+  console.log(`
+${colors.cyan}${colors.bold}Mags Claude Code Skill Setup${colors.reset}
+
+This will install the Mags skill for Claude Code, allowing you to run
+scripts on instant VMs directly from Claude.
+`);
+
+  // Ask where to install
+  console.log(`${colors.bold}Installation options:${colors.reset}`);
+  console.log(`  1. Global (all projects) - ~/.claude/commands/`);
+  console.log(`  2. Current project only - ./.claude/commands/`);
+  console.log('');
+
+  const choice = await prompt(`${colors.bold}Choose installation type [1/2]: ${colors.reset}`);
+
+  let targetDir;
+  if (choice === '2') {
+    targetDir = path.join(process.cwd(), '.claude', 'commands');
+    log('blue', 'Installing to current project...');
+  } else {
+    targetDir = CLAUDE_GLOBAL_DIR;
+    log('blue', 'Installing globally...');
+  }
+
+  // Create directory if it doesn't exist
+  try {
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+  } catch (err) {
+    log('red', `Failed to create directory: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Download skill file
+  log('blue', `Downloading skill from ${SKILL_URL}...`);
+
+  try {
+    const skillContent = await downloadFile(SKILL_URL);
+
+    const targetFile = path.join(targetDir, 'mags.md');
+    fs.writeFileSync(targetFile, skillContent);
+
+    console.log('');
+    log('green', 'Mags skill installed successfully!');
+    log('gray', `Location: ${targetFile}`);
+    console.log('');
+    log('cyan', 'Next steps:');
+    console.log(`  1. Make sure you're logged in: ${colors.bold}mags login${colors.reset}`);
+    console.log(`  2. In Claude Code, use: ${colors.bold}/mags <your request>${colors.reset}`);
+    console.log('');
+    log('cyan', 'Example prompts:');
+    console.log('  /mags run echo Hello World');
+    console.log('  /mags create a python environment with numpy');
+    console.log('  /mags run a flask server and give me the URL');
+
+  } catch (err) {
+    log('red', `Failed to download skill: ${err.message}`);
+    log('gray', `You can manually download from: ${SKILL_URL}`);
+    process.exit(1);
+  }
+}
+
 async function sshToJob(nameOrId) {
   if (!nameOrId) {
     log('red', 'Error: Job name or ID required');
@@ -643,6 +738,7 @@ async function sshToJob(nameOrId) {
 
   // Build SSH arguments
   const sshArgs = [
+    '-tt',  // Force TTY allocation even when stdin isn't a terminal
     '-o', 'StrictHostKeyChecking=no',
     '-o', 'UserKnownHostsFile=/dev/null',
     '-o', 'LogLevel=ERROR',
@@ -715,7 +811,7 @@ async function main() {
         break;
       case '--version':
       case '-v':
-        console.log('mags v1.3.0');
+        console.log('mags v1.4.0');
         process.exit(0);
         break;
       case 'new':
@@ -750,6 +846,9 @@ async function main() {
         await requireAuth();
         await stopJob(args[1]);
         break;
+      case 'setup-claude':
+        await setupClaude();
+        break;
       default:
         if (!command) {
           // No command - check if logged in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpiecloud/mags",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Mags CLI - Execute scripts on Magpie's instant VM infrastructure",
   "main": "index.js",
   "bin": {
@@ -17,7 +17,9 @@
     "cloud",
     "serverless",
     "execution",
-    "cli"
+    "cli",
+    "claude",
+    "claude-code"
   ],
   "author": "Magpie Cloud",
   "license": "MIT",
@@ -25,7 +27,7 @@
     "type": "git",
     "url": "https://github.com/magpiecloud/mags"
   },
-  "homepage": "https://magpiecloud.com/docs/mags",
+  "homepage": "https://mags.run",
   "bugs": {
     "url": "https://github.com/magpiecloud/mags/issues"
   },