@magpiecloud/mags 1.5.0 → 1.6.0

package/README.md

@@ -1,34 +1,30 @@
-# @magpiecloud/mags
+# Mags - Instant VM Execution
 
-Execute scripts instantly on Magpie's microVM infrastructure. VMs boot in <100ms from a warm pool.
+Execute scripts instantly on Magpie's microVM infrastructure. VMs boot in <100ms from a warm pool, giving you instant access to isolated compute environments.
 
-## Installation
-
-```bash
-npm install -g @magpiecloud/mags
-```
+## What is Mags?
 
-## Quick Start
+Mags is a CLI and SDK for running scripts on ephemeral microVMs. Each execution gets its own isolated VM that:
 
-### 1. Login to Magpie
+- Boots in <100ms (from warm pool)
+- Has persistent workspaces synced to S3
+- Syncs /root directory automatically every 30 seconds
+- Can expose public URLs for web services
+- Provides SSH access through secure proxy
+- Auto-sleeps when idle and wakes on request
 
-```bash
-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.
+## Installation
 
-### 2. Create a persistent VM
+### npm (recommended)
 
 ```bash
-mags new myproject
-mags ssh myproject
+npm install -g @magpiecloud/mags
 ```
 
-### 3. Or run a script
+### Go CLI
 
 ```bash
-mags run 'echo Hello World'
+go install github.com/magpiecloud/mags/cmd/mags@latest
 ```
 
 ## Authentication
@@ -39,109 +35,210 @@ mags run 'echo Hello World'
 mags login
 ```
 
-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.
+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.
 
-### Other Auth Commands
+### Auth Commands
 
 ```bash
+mags login     # Authenticate with Magpie
 mags whoami    # Check current authentication status
 mags logout    # Remove saved credentials
 ```
 
-### Environment Variable
-
-You can also set the token via environment variable (overrides saved config):
+### Environment Variable (Alternative)
 
 ```bash
 export MAGS_API_TOKEN="your-token-here"
 ```
 
-## CLI Commands
+## Quick Start
+
+### Run a simple command
+
+```bash
+mags run 'echo Hello World'
+```
+
+### Create a persistent VM
 
 ```bash
-# Create a persistent VM
+# Create a new VM with workspace "myproject"
 mags new myproject
 
 # SSH into it
 mags ssh myproject
 
-# Run a simple command
-mags run 'echo Hello'
-
-# With persistent workspace (S3 sync)
-mags run -w my-project 'apk add nodejs && node --version'
-
-# Persistent VM with public URL
-mags run -w webapp -p --url 'python3 -m http.server 8080'
-
-# With startup command (for auto-wake)
-mags run -w webapp -p --url --startup-command 'npm start' 'npm install && npm start'
+# Your /root directory persists to S3 automatically
+```
 
-# Custom port
-mags run -w webapp -p --url --port 3000 'npm start'
+### Run with a persistent workspace
 
-# Enable URL for existing job
-mags url <job-id>
-mags url <job-id> 8080
+Workspaces persist data between runs using S3 sync:
 
-# Other commands
-mags status <job-id>
-mags logs <job-id>
-mags list
-mags stop <job-id>
+```bash
+# First run - install dependencies
+mags run -w myproject 'apk add python3 py3-pip && pip install requests'
 
-# Install Claude Code skill
-mags setup-claude
+# Second run - dependencies are still there
+mags run -w myproject 'python3 -c "import requests; print(requests.__version__)"'
 ```
 
-## Claude Code Integration
-
-Install the Mags skill for Claude Code to run scripts directly from Claude:
+### Deploy a web service with public URL
 
 ```bash
-mags setup-claude
+mags run -p --url 'python3 -m http.server 8080'
+# Returns: https://abc123.apps.magpiecloud.com
 ```
 
-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`
+## CLI Reference
 
-See [mags.run/claude-skill.html](https://mags.run/claude-skill.html) for full documentation.
+### Commands
 
-## CLI Flags
+| Command | Description |
+|---------|-------------|
+| `mags login` | Authenticate with Magpie (saves token locally) |
+| `mags logout` | Remove saved credentials |
+| `mags whoami` | Show current authentication status |
+| `mags new <workspace>` | Create a persistent VM with workspace |
+| `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 |
+
+### Run Options
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `-w, --workspace` | Workspace ID for persistent storage | auto |
-| `-p, --persistent` | Keep VM alive for URL/SSH access | false |
+| `-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 to expose for URL access | 8080 |
-| `--startup-command` | Command when VM wakes from sleep | none |
+| `--port <port>` | Port to expose for URL access | 8080 |
+| `--startup-command <cmd>` | Command to run when VM wakes from sleep | none |
 
 ## SSH Access
 
-Connect to any running VM:
+Connect to any running VM via SSH:
 
 ```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`
+### 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
+
+### SSH Session Example
+
+```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
+```
 
 ## 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
+### How It Works
+
+When you use a workspace, Mags:
+
+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
+
+### What Gets Persisted
+
+- `/root` - Your home directory (synced every 30 seconds)
+- `/jfs` - Direct JuiceFS mount (instant S3 sync)
+- Installed packages and dependencies
+- Configuration files and dotfiles
+
+### Sync Behavior
+
+| Event | Behavior |
+|-------|----------|
+| While running | Auto-sync every 30 seconds |
+| On stop | Full sync before VM terminates |
+| On wake | Previous state restored instantly |
+
+## Usage Examples
+
+### Basic Execution
+
+```bash
+# Simple command
+mags run 'echo Hello World'
+
+# Multi-line script
+mags run 'apk add curl && curl -s https://api.github.com/users/octocat | head -5'
+
+# With environment info
+mags run 'uname -a && cat /etc/os-release'
+```
+
+### Persistent Workspaces
+
+```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'
+
+# All files in /root are persisted
+mags run -w ml-project 'ls -la /root'
+```
+
+### Web Services
+
+```bash
+# Simple static server
+mags run -p --url 'python3 -m http.server 8080'
+
+# Node.js app
+mags run -w myapp -p --url --port 3000 'npm install && npm start'
+
+# Flask app
+mags run -w flask-app -p --url 'pip install flask && python app.py'
+
+# 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'
+```
+
+### Interactive Development
+
+```bash
+# Create a persistent dev environment
+mags new dev-env
+
+# SSH in and work
+mags ssh dev-env
+
+# 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
+```
 
 ## Node.js SDK
 
+For programmatic access, use the SDK:
+
 ```javascript
 const Mags = require('@magpiecloud/mags');
 
@@ -156,11 +253,17 @@ console.log(result.logs);
 // Run with workspace
 const { requestId } = await mags.run('python script.py', {
   workspaceId: 'myproject',
-  persistent: true
+  persistent: true,
+  startupCommand: 'python server.py'
 });
 
 // Get status
 const status = await mags.status(requestId);
+console.log(status);
+
+// Get logs
+const logs = await mags.logs(requestId);
+logs.logs.forEach(l => console.log(l.message));
 
 // Enable URL access
 await mags.enableUrl(requestId, 8080);
@@ -172,6 +275,74 @@ const jobs = await mags.list({ page: 1, pageSize: 10 });
 await mags.stop(requestId);
 ```
 
+## API Endpoints
+
+For direct API access:
+
+| 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 |
+
+### Example API Request
+
+```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
+  }'
+```
+
+## 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 | <100ms |
+| Cold start | ~4 seconds |
+| Script overhead | ~50ms |
+| Workspace sync | Every 30 seconds |
+
 ## Environment Variables
 
 | Variable | Description | Default |
@@ -179,12 +350,49 @@ await mags.stop(requestId);
 | `MAGS_API_TOKEN` | Your API token (required) | - |
 | `MAGS_API_URL` | API endpoint | https://api.magpiecloud.com |
 
-## Performance
+## 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
 
-- **Warm start**: <100ms (VM from pool)
-- **Cold start**: ~4 seconds (new VM boot)
-- **Script overhead**: ~50ms
-- **Workspace sync**: Every 30 seconds
+- Documentation: https://magpiecloud.com/docs/mags
+- Issues: https://github.com/magpiecloud/mags/issues
+- Dashboard: https://magpiecloud.com/mags
 
 ## License