@magpiecloud/mags 1.8.13 → 1.8.15

package/Mags-API.postman_collection.json

@@ -1,374 +0,0 @@
-{
-  "info": {
-    "_postman_id": "mags-api-collection",
-    "name": "Mags API",
-    "description": "Magpie's instant VM execution API. Execute scripts on microVMs with <100ms warm start times.",
-    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
-  },
-  "auth": {
-    "type": "bearer",
-    "bearer": [
-      {
-        "key": "token",
-        "value": "{{MAGS_API_TOKEN}}",
-        "type": "string"
-      }
-    ]
-  },
-  "variable": [
-    {
-      "key": "BASE_URL",
-      "value": "https://api.magpiecloud.com",
-      "type": "string"
-    },
-    {
-      "key": "MAGS_API_TOKEN",
-      "value": "e1e90cc27dfe6a50cc28699cdcb937ef8c443567b62cf064a063f9b34af0b91b",
-      "type": "string"
-    },
-    {
-      "key": "REQUEST_ID",
-      "value": "",
-      "type": "string"
-    }
-  ],
-  "item": [
-    {
-      "name": "Jobs",
-      "item": [
-        {
-          "name": "Submit Job",
-          "event": [
-            {
-              "listen": "test",
-              "script": {
-                "exec": [
-                  "var jsonData = pm.response.json();",
-                  "if (jsonData.request_id) {",
-                  "    pm.collectionVariables.set('REQUEST_ID', jsonData.request_id);",
-                  "    console.log('Saved REQUEST_ID:', jsonData.request_id);",
-                  "}",
-                  "",
-                  "pm.test('Job submitted successfully', function () {",
-                  "    pm.response.to.have.status(202);",
-                  "    pm.expect(jsonData.status).to.eql('accepted');",
-                  "});"
-                ],
-                "type": "text/javascript"
-              }
-            }
-          ],
-          "request": {
-            "method": "POST",
-            "header": [
-              {
-                "key": "Content-Type",
-                "value": "application/json"
-              }
-            ],
-            "body": {
-              "mode": "raw",
-              "raw": "{\n    \"script\": \"echo 'Hello from Mags!'\\necho 'Current time:' $(date)\\necho 'Hostname:' $(hostname)\",\n    \"type\": \"inline\",\n    \"name\": \"hello-world\"\n}"
-            },
-            "url": {
-              "raw": "{{BASE_URL}}/api/v1/mags-jobs",
-              "host": ["{{BASE_URL}}"],
-              "path": ["api", "v1", "mags-jobs"]
-            },
-            "description": "Submit a new mags job for execution."
-          },
-          "response": []
-        },
-        {
-          "name": "Submit Job with Environment",
-          "event": [
-            {
-              "listen": "test",
-              "script": {
-                "exec": [
-                  "var jsonData = pm.response.json();",
-                  "if (jsonData.request_id) {",
-                  "    pm.collectionVariables.set('REQUEST_ID', jsonData.request_id);",
-                  "}",
-                  "",
-                  "pm.test('Job submitted successfully', function () {",
-                  "    pm.response.to.have.status(202);",
-                  "});"
-                ],
-                "type": "text/javascript"
-              }
-            }
-          ],
-          "request": {
-            "method": "POST",
-            "header": [
-              {
-                "key": "Content-Type",
-                "value": "application/json"
-              }
-            ],
-            "body": {
-              "mode": "raw",
-              "raw": "{\n    \"script\": \"echo \\\"MY_VAR = $MY_VAR\\\"\\necho \\\"GREETING = $GREETING\\\"\",\n    \"type\": \"inline\",\n    \"name\": \"env-vars-test\",\n    \"environment\": {\n        \"MY_VAR\": \"hello-mags\",\n        \"GREETING\": \"Welcome to fast execution!\"\n    }\n}"
-            },
-            "url": {
-              "raw": "{{BASE_URL}}/api/v1/mags-jobs",
-              "host": ["{{BASE_URL}}"],
-              "path": ["api", "v1", "mags-jobs"]
-            },
-            "description": "Submit a job with custom environment variables."
-          },
-          "response": []
-        },
-        {
-          "name": "Submit Persistent Job (Web Server)",
-          "event": [
-            {
-              "listen": "test",
-              "script": {
-                "exec": [
-                  "var jsonData = pm.response.json();",
-                  "if (jsonData.request_id) {",
-                  "    pm.collectionVariables.set('REQUEST_ID', jsonData.request_id);",
-                  "}",
-                  "",
-                  "pm.test('Persistent job submitted', function () {",
-                  "    pm.response.to.have.status(202);",
-                  "});"
-                ],
-                "type": "text/javascript"
-              }
-            }
-          ],
-          "request": {
-            "method": "POST",
-            "header": [
-              {
-                "key": "Content-Type",
-                "value": "application/json"
-              }
-            ],
-            "body": {
-              "mode": "raw",
-              "raw": "{\n    \"script\": \"cd /tmp && echo '<h1>Hello from Mags!</h1>' > index.html && python3 -m http.server 8080\",\n    \"type\": \"inline\",\n    \"name\": \"web-server\",\n    \"persistent\": true\n}"
-            },
-            "url": {
-              "raw": "{{BASE_URL}}/api/v1/mags-jobs",
-              "host": ["{{BASE_URL}}"],
-              "path": ["api", "v1", "mags-jobs"]
-            },
-            "description": "Submit a persistent job that keeps the VM alive. Returns a URL for web access."
-          },
-          "response": []
-        },
-        {
-          "name": "Get Job Status",
-          "event": [
-            {
-              "listen": "test",
-              "script": {
-                "exec": [
-                  "pm.test('Status retrieved', function () {",
-                  "    pm.response.to.have.status(200);",
-                  "    var jsonData = pm.response.json();",
-                  "    pm.expect(jsonData.request_id).to.exist;",
-                  "    pm.expect(jsonData.status).to.be.oneOf(['pending', 'running', 'sleeping', 'completed', 'error']);",
-                  "});"
-                ],
-                "type": "text/javascript"
-              }
-            }
-          ],
-          "request": {
-            "method": "GET",
-            "header": [],
-            "url": {
-              "raw": "{{BASE_URL}}/api/v1/mags-jobs/{{REQUEST_ID}}/status",
-              "host": ["{{BASE_URL}}"],
-              "path": ["api", "v1", "mags-jobs", "{{REQUEST_ID}}", "status"]
-            },
-            "description": "Get the current status of a mags job."
-          },
-          "response": []
-        },
-        {
-          "name": "Get Job Logs",
-          "event": [
-            {
-              "listen": "test",
-              "script": {
-                "exec": [
-                  "pm.test('Logs retrieved', function () {",
-                  "    pm.response.to.have.status(200);",
-                  "    var jsonData = pm.response.json();",
-                  "    pm.expect(jsonData.logs).to.be.an('array');",
-                  "});"
-                ],
-                "type": "text/javascript"
-              }
-            }
-          ],
-          "request": {
-            "method": "GET",
-            "header": [],
-            "url": {
-              "raw": "{{BASE_URL}}/api/v1/mags-jobs/{{REQUEST_ID}}/logs",
-              "host": ["{{BASE_URL}}"],
-              "path": ["api", "v1", "mags-jobs", "{{REQUEST_ID}}", "logs"]
-            },
-            "description": "Get logs from a mags job execution."
-          },
-          "response": []
-        },
-        {
-          "name": "List Jobs",
-          "event": [
-            {
-              "listen": "test",
-              "script": {
-                "exec": [
-                  "pm.test('Jobs listed', function () {",
-                  "    pm.response.to.have.status(200);",
-                  "    var jsonData = pm.response.json();",
-                  "    pm.expect(jsonData.jobs).to.be.an('array');",
-                  "    pm.expect(jsonData.total).to.be.a('number');",
-                  "});"
-                ],
-                "type": "text/javascript"
-              }
-            }
-          ],
-          "request": {
-            "method": "GET",
-            "header": [],
-            "url": {
-              "raw": "{{BASE_URL}}/api/v1/mags-jobs?page=1&page_size=10",
-              "host": ["{{BASE_URL}}"],
-              "path": ["api", "v1", "mags-jobs"],
-              "query": [
-                {
-                  "key": "page",
-                  "value": "1"
-                },
-                {
-                  "key": "page_size",
-                  "value": "10"
-                }
-              ]
-            },
-            "description": "List mags jobs with pagination."
-          },
-          "response": []
-        },
-        {
-          "name": "Update Job",
-          "request": {
-            "method": "PATCH",
-            "header": [
-              {
-                "key": "Content-Type",
-                "value": "application/json"
-              }
-            ],
-            "body": {
-              "mode": "raw",
-              "raw": "{\n    \"name\": \"updated-job-name\"\n}"
-            },
-            "url": {
-              "raw": "{{BASE_URL}}/api/v1/mags-jobs/{{REQUEST_ID}}",
-              "host": ["{{BASE_URL}}"],
-              "path": ["api", "v1", "mags-jobs", "{{REQUEST_ID}}"]
-            },
-            "description": "Update a mags job's properties."
-          },
-          "response": []
-        }
-      ]
-    },
-    {
-      "name": "Access",
-      "item": [
-        {
-          "name": "Enable SSH Access",
-          "request": {
-            "method": "POST",
-            "header": [
-              {
-                "key": "Content-Type",
-                "value": "application/json"
-              }
-            ],
-            "body": {
-              "mode": "raw",
-              "raw": "{\n    \"access_type\": \"ssh\"\n}"
-            },
-            "url": {
-              "raw": "{{BASE_URL}}/api/v1/mags-jobs/{{REQUEST_ID}}/access",
-              "host": ["{{BASE_URL}}"],
-              "path": ["api", "v1", "mags-jobs", "{{REQUEST_ID}}", "access"]
-            },
-            "description": "Enable SSH proxy access to a running mags VM."
-          },
-          "response": []
-        },
-        {
-          "name": "Enable URL Access",
-          "request": {
-            "method": "POST",
-            "header": [
-              {
-                "key": "Content-Type",
-                "value": "application/json"
-              }
-            ],
-            "body": {
-              "mode": "raw",
-              "raw": "{\n    \"access_type\": \"url\",\n    \"port\": 8080\n}"
-            },
-            "url": {
-              "raw": "{{BASE_URL}}/api/v1/mags-jobs/{{REQUEST_ID}}/access",
-              "host": ["{{BASE_URL}}"],
-              "path": ["api", "v1", "mags-jobs", "{{REQUEST_ID}}", "access"]
-            },
-            "description": "Enable URL access to a running mags VM on a specific port."
-          },
-          "response": []
-        }
-      ]
-    },
-    {
-      "name": "Health",
-      "item": [
-        {
-          "name": "Health Check",
-          "event": [
-            {
-              "listen": "test",
-              "script": {
-                "exec": [
-                  "pm.test('API is healthy', function () {",
-                  "    pm.response.to.have.status(200);",
-                  "    var jsonData = pm.response.json();",
-                  "    pm.expect(jsonData.status).to.eql('ok');",
-                  "});"
-                ],
-                "type": "text/javascript"
-              }
-            }
-          ],
-          "request": {
-            "method": "GET",
-            "header": [],
-            "url": {
-              "raw": "{{BASE_URL}}/api/v1/health",
-              "host": ["{{BASE_URL}}"],
-              "path": ["api", "v1", "health"]
-            },
-            "description": "Check API health status."
-          },
-          "response": []
-        }
-      ]
-    }
-  ]
-}

package/QUICKSTART.md

@@ -1,295 +0,0 @@
-# Mags Quickstart Guide
-
-Mags lets you run code in ephemeral VMs with persistent filesystems. Your files, packages, and configs persist across runs - but processes don't.
-
-## Getting Access
-
-### 1. Get an API Token
-
-Contact your admin or generate a token from the Magpie dashboard:
-```
-https://magpiecloud.com/dashboard/tokens
-```
-
-### 2. Set Environment Variable
-
-```bash
-export MAGS_API_TOKEN="your-api-token-here"
-```
-
-Add to your shell profile (`~/.bashrc`, `~/.zshrc`) to persist:
-```bash
-echo 'export MAGS_API_TOKEN="your-api-token-here"' >> ~/.zshrc
-```
-
-## Installing the CLI
-
-### Option 1: Download Binary
-
-```bash
-# macOS (Apple Silicon)
-curl -L https://releases.magpiecloud.com/mags/latest/mags-darwin-arm64 -o mags
-chmod +x mags
-sudo mv mags /usr/local/bin/
-
-# macOS (Intel)
-curl -L https://releases.magpiecloud.com/mags/latest/mags-darwin-amd64 -o mags
-chmod +x mags
-sudo mv mags /usr/local/bin/
-
-# Linux
-curl -L https://releases.magpiecloud.com/mags/latest/mags-linux-amd64 -o mags
-chmod +x mags
-sudo mv mags /usr/local/bin/
-```
-
-### Option 2: Build from Source
-
-```bash
-git clone https://github.com/magpie/magpie-api-layer.git
-cd magpie-api-layer
-go build -o mags ./cmd/mags/
-sudo mv mags /usr/local/bin/
-```
-
-### Verify Installation
-
-```bash
-mags --help
-```
-
-## Quick Examples
-
-### Run a Simple Command
-
-```bash
-mags run "echo hello world"
-```
-
-### Use a Persistent Workspace
-
-```bash
-# First run - install Node.js (persists!)
-mags run -w my-project "apk add nodejs npm"
-
-# Second run - Node.js is already there
-mags run -w my-project "node --version"
-```
-
-### Deploy a Web Server with Public URL
-
-```bash
-# Deploy with --url flag to get a public URL
-mags run -w webapp -p --url "python3 -m http.server 8080"
-# Output: 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"
-```
-
-### SSH into a VM
-
-```bash
-mags ssh my-project
-# Now you're in an interactive shell
-# All changes persist to 'my-project' workspace
-```
-
-### List Recent Jobs
-
-```bash
-mags list
-```
-
-## Workspaces
-
-A **workspace** is a persistent filesystem stored in S3. Everything you do in a workspace persists:
-
-| Persists | Does NOT Persist |
-|----------|------------------|
-| Files & directories | Running processes |
-| Installed packages | In-memory state |
-| Config files | Network connections |
-| Environment customizations | Open ports |
-
-### Workspace Naming
-
-```bash
-# Good workspace names
-mags run -w my-project "..."
-mags run -w user-123-dev "..."
-mags run -w webapp-prod "..."
-
-# Workspace names should be:
-# - Lowercase alphanumeric with hyphens
-# - Unique per user/project
-# - Descriptive
-```
-
-## Command Reference
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `mags run` | Run a script | `mags run "npm test"` |
-| `mags run -w NAME` | Run with workspace | `mags run -w proj "npm test"` |
-| `mags run -p --url` | Run with public URL | `mags run -w app -p --url "python3 -m http.server 8080"` |
-| `mags exec` | Quick command in workspace | `mags exec proj "ls -la"` |
-| `mags ssh` | Interactive SSH | `mags ssh proj` |
-| `mags url ID` | Enable URL for job | `mags url abc123 --port 3000` |
-| `mags list` | List jobs | `mags list -n 20` |
-| `mags logs ID` | View job logs | `mags logs abc123` |
-| `mags status ID` | Job status | `mags status abc123` |
-| `mags set ID` | Update VM settings | `mags set myvm --no-sleep` |
-
-## CLI Flags
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `-w, --workspace` | Workspace ID for persistent storage | auto-generated |
-| `-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 |
-
-## Common Workflows
-
-### Web Development
-
-```bash
-# Set up project with public URL
-mags run -w webapp -p --url "apk add nodejs npm && npm init -y && npm install express"
-
-# Your app is now at https://xyz123.apps.magpiecloud.com
-
-# Update code and restart
-mags run -w webapp -p --url "npm start"
-```
-
-### Python Development
-
-```bash
-# Set up Python environment
-mags run -w pyproject "apk add python3 py3-pip"
-
-# Install packages (persists!)
-mags run -w pyproject "pip install flask requests"
-
-# Run script
-mags run -w pyproject "python app.py"
-
-# Deploy with URL
-mags run -w pyproject -p --url "flask run --host=0.0.0.0 --port=8080"
-```
-
-### CI/CD Jobs
-
-```bash
-# Run tests with timeout
-mags run -w myapp -t 600 "npm ci && npm test"
-
-# Build project
-mags run -w myapp -t 600 "npm run build"
-
-# Check results
-mags logs <job-id>
-```
-
-### Deploy a Persistent Web App
-
-```bash
-# Deploy with auto-wake (VM sleeps when idle, wakes on request)
-mags run -w myapp -p --url --startup-command "npm start" "npm install && npm start"
-
-# Get a URL like: https://abc123.apps.magpiecloud.com
-# 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 |
-|---------|---------|-----|------|
-| `run` | 5 min | configurable | `-t 600` |
-| `exec` | 1 min | configurable | `-t 120` |
-| `ssh` | 1 hour | 1 hour | - |
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `MAGS_API_TOKEN` | API token (required) |
-| `MAGS_API_URL` | Custom API URL (optional) |
-
-## API Access
-
-You can also use the REST API directly:
-
-```bash
-# Submit a job
-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
-  }'
-
-# Check status
-curl https://api.magpiecloud.com/api/v1/mags-jobs/{job-id}/status \
-  -H "Authorization: Bearer $MAGS_API_TOKEN"
-
-# Get logs
-curl https://api.magpiecloud.com/api/v1/mags-jobs/{job-id}/logs \
-  -H "Authorization: Bearer $MAGS_API_TOKEN"
-
-# Enable URL access
-curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs/{job-id}/access \
-  -H "Authorization: Bearer $MAGS_API_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"port": 8080}'
-```
-
-## Troubleshooting
-
-### "API token required"
-```bash
-export MAGS_API_TOKEN="your-token"
-```
-
-### "invalid or expired token"
-Get a new token from the dashboard.
-
-### Job timeout
-Increase timeout: `mags run -t 600 -w proj "long-command"`
-
-### Workspace not persisting
-Ensure you use the same `-w` name across runs.
-
-### URL not working
-Make sure you used `--url` flag: `mags run -w app -p --url "..."`
-
-Or enable it after: `mags url <job-id>`
-
-## Getting Help
-
-```bash
-mags --help
-mags run --help
-mags url --help
-```
-
-For issues: https://github.com/magpie/magpie-api-layer/issues