# Mags - Instant VM Execution

Execute scripts instantly on Magpie's microVM infrastructure. VMs boot in <100ms from a warm pool.

## Installation

Add this skill to your Claude Code project:

```bash
# Copy to your project's .claude/commands folder
cp -r mags ~/.claude/commands/
```

Or add to a specific project:
```bash
cp -r mags /path/to/project/.claude/commands/
```

## Configuration

Set your API token:
```bash
export MAGS_API_TOKEN="your-token-here"
```

Or create a `.env` file:
```
MAGS_API_TOKEN=your-token-here
MAGS_API_URL=https://api.magpiecloud.com
```

## CLI Commands

### Basic Execution
```bash
# Run a simple command
mags run "echo Hello World"

# Run with persistent workspace (changes persist to S3)
mags run -w my-project "apk add nodejs npm && npm init -y"

# Run again - nodejs is already installed!
mags run -w my-project "node --version"
```

### Persistent VMs with URL Access
```bash
# Deploy a web server with public URL
mags run -w webapp -p --url "python3 -m http.server 8080"
# Returns: https://abc123.apps.magpiecloud.com

# With startup command (runs when VM wakes from sleep)
mags run -w webapp -p --url --startup-command "npm start" "npm install && npm start"

# Custom port
mags run -w webapp -p --url --port 3000 "npm start"
```

### Other Commands
```bash
# Check job status
mags status <request_id>

# View job logs
mags logs <request_id>

# List recent jobs
mags list

# Enable URL access for existing persistent job
mags url <request_id>
mags url <request_id> --port 3000
mags url <request_id> --startup "npm start"

# SSH into a workspace
mags ssh my-project
```

## CLI Flags

| Flag | Description |
|------|-------------|
| `-w, --workspace` | Workspace ID for persistent storage |
| `-p, --persistent` | Keep VM alive for URL/SSH access |
| `--url` | Enable public URL access (requires -p) |
| `--port` | Port to expose (default: 8080) |
| `--startup-command` | Command to run when VM wakes from sleep |
| `-e, --ephemeral` | Truly ephemeral (no S3 sync, faster) |
| `-t, --timeout` | Timeout in seconds (default: 300) |

## API Reference

Base URL: `https://api.magpiecloud.com/api/v1`

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/mags-jobs` | POST | Submit a new job |
| `/mags-jobs` | GET | List jobs |
| `/mags-jobs/{id}/status` | GET | Get job status |
| `/mags-jobs/{id}/logs` | GET | Get job logs |
| `/mags-jobs/{id}/access` | POST | Enable SSH/URL access |
| `/mags-jobs/{id}` | PATCH | Update job (startup command) |

### Submit Job
```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",
    "type": "inline",
    "workspace_id": "my-workspace",
    "persistent": true,
    "startup_command": "python3 -m http.server 8080"
  }'
```

### Enable URL Access
```bash
curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs/{id}/access \
  -H "Authorization: Bearer $MAGS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'
```

## Response Times

- **Warm start**: <100ms (VM from pool)
- **Cold start**: ~4 seconds (VM boot from scratch)
- **Script overhead**: ~50ms

## Examples

### Deploy a Python Web Server
```bash
mags run -w webserver -p --url \
  "echo '<h1>Hello from Mags!</h1>' > ~/index.html && python3 -m http.server 8080"
```

### Deploy Node.js App
```bash
mags run -w nodeapp -p --url --port 3000 --startup-command "npm start" \
  "apk add nodejs npm && npm install && npm start"
```

### Run Tests with Dependencies
```bash
# First run installs dependencies
mags run -w myproject "apk add python3 py3-pip && pip install pytest requests"

# Subsequent runs are instant
mags run -w myproject "pytest tests/"
```
