@magpiecloud/mags 1.8.13 → 1.8.15

package/README.md

@@ -1,17 +1,6 @@
-# Mags - Instant VM Execution
+# @magpiecloud/mags
 
-Execute scripts instantly on Magpie's microVM infrastructure. VMs boot in <100ms from a warm pool, giving you instant access to isolated compute environments.
-
-## What is Mags?
-
-Mags is a CLI and SDK for running scripts on ephemeral microVMs. Each execution gets its own isolated VM that:
-
-- Boots in ~300ms (from warm pool)
-- Supports optional S3-backed persistent workspaces (with `-p` flag)
-- Syncs /root directory automatically when persistence is enabled
-- Can expose public URLs for web services
-- Provides SSH access through secure proxy
-- Auto-sleeps when idle and wakes on request
+Execute scripts instantly on Magpie's microVM infrastructure. VMs boot in <100ms from a warm pool.
 
 ## Installation
 
@@ -19,411 +8,176 @@ Mags is a CLI and SDK for running scripts on ephemeral microVMs. Each execution
 npm install -g @magpiecloud/mags
 ```
 
-## Authentication
+## Quick Start
 
-### Interactive Login (Recommended)
+### 1. Login to Magpie
 
 ```bash
 mags login
 ```
 
-This opens your browser to the Magpie dashboard where you can create an API token. Paste the token when prompted, and it will be saved to `~/.mags/config.json` for all future commands.
+This will open your browser to create an API token. Paste the token when prompted, and it will be saved for future use.
 
-### Auth Commands
+### 2. Create a sandbox
 
 ```bash
-mags login     # Authenticate with Magpie
-mags whoami    # Check current authentication status
-mags logout    # Remove saved credentials
-```
-
-### Environment Variable (Alternative)
-
-```bash
-export MAGS_API_TOKEN="your-token-here"
+mags new myproject              # Local disk only
+mags new myproject -p           # With S3 persistence
+mags ssh myproject
 ```
 
-## Quick Start
-
-### Run a simple command
+### 3. Or run a script
 
 ```bash
 mags run 'echo Hello World'
 ```
 
-### Create a sandbox
-
-```bash
-# Create a new VM (local disk only)
-mags new myproject
-
-# Create with S3 data persistence
-mags new myproject -p
-
-# SSH into it
-mags ssh myproject
-```
-
-### Run with a persistent workspace
-
-Workspaces persist data between runs using S3 sync:
-
-```bash
-# First run - install dependencies
-mags run -w myproject 'apk add python3 py3-pip && pip install requests'
-
-# Second run - dependencies are still there
-mags run -w myproject 'python3 -c "import requests; print(requests.__version__)"'
-```
+## Authentication
 
-### Deploy a web service with public URL
+### Interactive Login (Recommended)
 
 ```bash
-mags run -p --url 'python3 -m http.server 8080'
-# Returns: https://abc123.apps.magpiecloud.com
+mags login
 ```
 
-## CLI Reference
-
-### Commands
-
-| Command | Description |
-|---------|-------------|
-| `mags login` | Authenticate with Magpie (saves token locally) |
-| `mags logout` | Remove saved credentials |
-| `mags whoami` | Show current authentication status |
-| `mags new <workspace> [-p]` | Create a VM sandbox (add `-p` for S3 persistence) |
-| `mags run [options] <script>` | Execute a script on a microVM |
-| `mags ssh <workspace>` | Open interactive SSH session to a VM |
-| `mags status <job-id>` | Get job status |
-| `mags logs <job-id>` | Get job logs |
-| `mags list` | List recent jobs |
-| `mags url <job-id> [port]` | Enable URL access for a job |
-| `mags stop <job-id>` | Stop a running job |
-| `mags set <name\|id> [options]` | Update VM settings (`--no-sleep`, `--sleep`) |
-
-### Run Options
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `-w, --workspace <id>` | Use persistent workspace (S3 sync) | auto-generated |
-| `-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
+Opens the Magpie dashboard in your browser where you can create an API token. The token is saved to `~/.mags/config.json` and used automatically for all future commands.
 
-Connect to any running VM via SSH:
+### Other Auth Commands
 
 ```bash
-mags ssh myproject
+mags whoami    # Check current authentication status
+mags logout    # Remove saved credentials
 ```
 
-### SSH Features
-
-- **Secure proxy**: Connect via `api.magpiecloud.com:PORT` (agent IPs are hidden)
-- **PTY support**: Full interactive terminal with colors and editors
-- **Key-based auth**: Automatic SSH key management
-- **Hostname**: VMs use `mags-vm` as hostname
+### Environment Variable
 
-### SSH Session Example
+You can also set the token via environment variable (overrides saved config):
 
 ```bash
-$ mags ssh myproject
-Connecting to api.magpiecloud.com:40006...
-(Use Ctrl+D or 'exit' to disconnect)
-
-mags-vm:~# ls
-index.html  test.txt
-
-mags-vm:~# python3 --version
-Python 3.11.6
-
-mags-vm:~# exit
+export MAGS_API_TOKEN="your-token-here"
 ```
 
-## Workspaces & Persistence
-
-### How It Works
+## CLI Commands
 
-When you use a workspace, Mags:
+```bash
+# Create a sandbox (local disk)
+mags new myproject
 
-1. Mounts a JuiceFS filesystem backed by S3
-2. Creates an OverlayFS to capture all filesystem changes
-3. Syncs your `/root` directory to S3 every 30 seconds
-4. Restores your files when you reconnect
+# Create with S3 persistence
+mags new myproject -p
 
-### What Gets Persisted
+# SSH into it
+mags ssh myproject
 
-- `/root` - Your home directory (synced every 30 seconds)
-- `/jfs` - Direct JuiceFS mount (instant S3 sync)
-- Installed packages and dependencies
-- Configuration files and dotfiles
+# Run a simple command
+mags run 'echo Hello'
 
-### Sync Behavior
+# With persistent workspace (S3 sync)
+mags run -w my-project 'apk add nodejs && node --version'
 
-| Event | Behavior |
-|-------|----------|
-| While running | Auto-sync every 30 seconds |
-| On stop | Full sync before VM terminates |
-| On wake | Previous state restored instantly |
+# Persistent VM with public URL
+mags run -w webapp -p --url 'python3 -m http.server 8080'
 
-## Usage Examples
+# With startup command (for auto-wake)
+mags run -w webapp -p --url --startup-command 'npm start' 'npm install && npm start'
 
-### Basic Execution
+# Custom port
+mags run -w webapp -p --url --port 3000 'npm start'
 
-```bash
-# Simple command
-mags run 'echo Hello World'
+# Enable URL for existing job
+mags url <job-id>
+mags url <job-id> 8080
 
-# Multi-line script
-mags run 'apk add curl && curl -s https://api.github.com/users/octocat | head -5'
+# Other commands
+mags status <job-id>
+mags logs <job-id>
+mags list
+mags stop <job-id>
 
-# With environment info
-mags run 'uname -a && cat /etc/os-release'
+# Install Claude Code skill
+mags setup-claude
 ```
 
-### Persistent Workspaces
+## Claude Code Integration
 
-```bash
-# Create a workspace with dependencies
-mags run -w ml-project 'apk add python3 py3-pip && pip install numpy pandas scikit-learn'
-
-# Run scripts using the workspace
-mags run -w ml-project 'python3 train.py'
+Install the Mags skill for Claude Code to run scripts directly from Claude:
 
-# All files in /root are persisted
-mags run -w ml-project 'ls -la /root'
+```bash
+mags setup-claude
 ```
 
-### Web Services
-
-```bash
-# Simple static server
-mags run -p --url 'python3 -m http.server 8080'
+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`
 
-# Node.js app
-mags run -w myapp -p --url --port 3000 'npm install && npm start'
+See [mags.run/claude-skill.html](https://mags.run/claude-skill.html) for full documentation.
 
-# Flask app
-mags run -w flask-app -p --url 'pip install flask && python app.py'
+## CLI Flags
 
-# Custom startup command for auto-wake
-mags run -w api -p --url --startup-command 'python server.py' 'pip install -r requirements.txt && python server.py'
-```
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-w, --workspace` | Workspace ID for persistent storage | auto |
+| `-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 |
+| `--startup-command` | Command when VM wakes from sleep | none |
 
-### Always-On VMs
+## SSH Access
 
-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:
+Connect to any running VM:
 
 ```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'
+mags ssh myproject
 ```
 
-If an always-on VM's host becomes unhealthy, the orchestrator automatically re-provisions it on a healthy agent within ~60 seconds.
-
-### Interactive Development
+Features:
+- Connects via secure proxy (`api.magpiecloud.com:PORT`)
+- Full PTY support for interactive terminals
+- Automatic SSH key management
+- Hostname: `mags-vm`
 
-```bash
-# Create a dev environment (local disk)
-mags new dev-env
+## Workspaces & Persistence
 
-# SSH in and work
-mags ssh dev-env
+When using persistent mode (`-p`), your `/root` directory syncs to S3:
+- **Auto-sync**: Every 30 seconds while running
+- **On stop**: Full sync before VM terminates
+- **On wake**: Previous state restored
 
-# Inside the VM:
-mags-vm:~# apk add git nodejs npm
-mags-vm:~# git clone https://github.com/user/repo
-mags-vm:~# cd repo && npm install
-mags-vm:~# npm run dev
-```
+Without `-p`, data lives on local disk only and is cleaned up when the VM is destroyed.
 
 ## Node.js SDK
 
-For programmatic access, use the SDK:
-
 ```javascript
 const Mags = require('@magpiecloud/mags');
 
 const mags = new Mags({
   apiToken: process.env.MAGS_API_TOKEN
 });
-```
-
-### SDK Methods
-
-#### Jobs
-
-| Method | Description |
-|--------|-------------|
-| `run(script, options)` | Submit a job. Options: `name`, `workspaceId`, `baseWorkspaceId`, `persistent`, `noSleep`, `ephemeral`, `startupCommand`, `environment`, `fileIds`, `diskGb` |
-| `runAndWait(script, options)` | Submit and block until done. Extra options: `timeout`, `pollInterval` |
-| `new(name, options)` | Create a VM sandbox and wait until running. Options: `persistent`, `baseWorkspaceId`, `diskGb`, `timeout` |
-| `status(requestId)` | Get job status |
-| `logs(requestId)` | Get job logs |
-| `list({page, pageSize})` | List recent jobs (paginated) |
-| `findJob(nameOrId)` | Find job by name, workspace ID, or request ID |
-| `updateJob(requestId, {startupCommand, noSleep})` | Update job settings |
-| `stop(nameOrId)` | Stop a job (accepts name, workspace ID, or request ID) |
-| `exec(nameOrId, command, {timeout})` | Execute a command on a running/sleeping VM via SSH |
-| `sync(requestId)` | Sync workspace to S3 without stopping |
-| `resize(workspace, diskGb)` | Resize workspace disk (stops VM, creates new one) |
-| `usage({windowDays})` | Get aggregated usage summary |
-
-#### URL & Access
-
-| Method | Description |
-|--------|-------------|
-| `enableAccess(requestId, port)` | Enable SSH (port 22) or HTTP access (default 8080) |
-| `url(nameOrId, port)` | Enable public URL and return the full URL |
-| `urlAliasCreate(subdomain, workspaceId, domain)` | Create a stable URL alias for a workspace |
-| `urlAliasList()` | List all URL aliases |
-| `urlAliasDelete(subdomain)` | Delete a URL alias |
-
-#### Workspaces
-
-| Method | Description |
-|--------|-------------|
-| `listWorkspaces()` | List all workspaces |
-| `deleteWorkspace(workspaceId)` | Delete a workspace and its S3 data |
-
-#### Files
-
-| Method | Description |
-|--------|-------------|
-| `uploadFiles(filePaths)` | Upload local files, returns array of file IDs |
-
-#### Cron Jobs
-
-| Method | Description |
-|--------|-------------|
-| `cronCreate({name, cronExpression, script, workspaceId, environment, persistent})` | Create a scheduled job |
-| `cronList()` | List all cron jobs |
-| `cronGet(id)` | Get a cron job |
-| `cronUpdate(id, updates)` | Update a cron job |
-| `cronDelete(id)` | Delete a cron job |
-
-### SDK Examples
 
-```javascript
 // Run and wait for completion
 const result = await mags.runAndWait('echo Hello World');
 console.log(result.logs);
 
-// Create a sandbox (local disk)
-await mags.new('myproject');
-
-// Create a sandbox with S3 persistence
-await mags.new('myproject', { persistent: true });
-
-// Execute command on existing VM
-const { output } = await mags.exec('myproject', 'ls -la /root');
-console.log(output);
-
-// Run with workspace and options
-const job = await mags.run('python script.py', {
+// Run with workspace
+const { requestId } = await mags.run('python script.py', {
   workspaceId: 'myproject',
-  persistent: true,
-  diskGb: 5,
-  startupCommand: 'python server.py'
-});
-
-// Always-on VM (never auto-sleeps)
-await mags.run('node server.js', {
-  workspaceId: 'my-api',
-  persistent: true,
-  noSleep: true
+  persistent: true
 });
 
-// Enable public URL
-const { url } = await mags.url('my-api', 3000);
-console.log(url); // https://abc123.apps.magpiecloud.com
-
-// Create stable URL alias
-await mags.urlAliasCreate('my-app', 'my-api');
-
-// Resize workspace disk
-await mags.resize('myproject', 10); // 10GB
-
-// Stop a job by name
-await mags.stop('myproject');
-```
-
-## API Endpoints
-
-For direct API access:
+// Get status
+const status = await mags.status(requestId);
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/v1/mags-jobs` | POST | Submit a new job |
-| `/api/v1/mags-jobs` | GET | List jobs (paginated) |
-| `/api/v1/mags-jobs/{id}/status` | GET | Get job status |
-| `/api/v1/mags-jobs/{id}/logs` | GET | Get job logs |
-| `/api/v1/mags-jobs/{id}/access` | POST | Enable SSH/URL access |
-| `/api/v1/mags-jobs/{id}` | PATCH | Update job settings |
+// Enable URL access
+await mags.enableUrl(requestId, 8080);
 
-### Example API Request
+// List jobs
+const jobs = await mags.list({ page: 1, pageSize: 10 });
 
-```bash
-curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
-  -H "Authorization: Bearer $MAGS_API_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "script": "echo Hello World",
-    "type": "inline",
-    "workspace_id": "myproject",
-    "persistent": true,
-    "no_sleep": true
-  }'
+// Stop a job
+await mags.stop(requestId);
 ```
 
-## Job Status Values
-
-| Status | Description |
-|--------|-------------|
-| `pending` | Job queued, waiting for VM |
-| `running` | Script executing |
-| `sleeping` | Persistent VM idle (wakes on request) |
-| `completed` | Script finished successfully |
-| `error` | Script failed |
-
-## VM Environment
-
-Each VM runs Alpine Linux with hostname `mags-vm` and includes:
-
-- `/root` - Persistent home directory (synced to S3)
-- `/jfs` - Direct JuiceFS mount
-- Common tools: curl, wget, git, python3, nodejs
-- Package manager: `apk add <package>`
-
-### Installing Packages
-
-```bash
-# Python packages
-mags run 'apk add python3 py3-pip && pip install requests flask pandas'
-
-# Node.js packages
-mags run 'apk add nodejs npm && npm install -g express'
-
-# System packages
-mags run 'apk add ffmpeg imagemagick'
-```
-
-## Performance
-
-| Metric | Value |
-|--------|-------|
-| Warm start | ~300ms |
-| Cold start | ~4 seconds |
-| Script overhead | ~50ms |
-| Workspace sync | Every 30 seconds |
-
 ## Environment Variables
 
 | Variable | Description | Default |
@@ -431,49 +185,12 @@ mags run 'apk add ffmpeg imagemagick'
 | `MAGS_API_TOKEN` | Your API token (required) | - |
 | `MAGS_API_URL` | API endpoint | https://api.magpiecloud.com |
 
-## Troubleshooting
-
-### "API token required"
-
-Set your API token:
-```bash
-mags login
-# or
-export MAGS_API_TOKEN="your-token-here"
-```
-
-### "Job timed out"
-
-Increase the timeout or check if your script is hanging:
-```bash
-mags run --timeout 600 'long-running-script.sh'
-```
-
-### "Workspace not found"
-
-Workspace IDs are case-sensitive. Check with:
-```bash
-mags list
-```
-
-### URL not accessible
-
-Make sure you're using both `-p` (persistent) and `--url` flags, and your app is listening on the correct port:
-```bash
-mags run -p --url --port 3000 'node server.js'
-```
-
-### SSH connection issues
-
-SSH connects through our proxy. If you have issues:
-1. Ensure the job is running: `mags status <id>`
-2. Try reconnecting: `mags ssh <workspace>`
-
-## Support
+## Performance
 
-- Documentation: https://mags.run
-- API Reference: https://mags.run/api.html
-- Dashboard: https://mags.run/tokens.html
+- **Warm start**: <100ms (VM from pool)
+- **Cold start**: ~4 seconds (new VM boot)
+- **Script overhead**: ~50ms
+- **Workspace sync**: Every 30 seconds
 
 ## License