@magpiecloud/mags 1.5.0 → 1.6.0

package/python/src/mags/client.py

@@ -0,0 +1,283 @@
+"""Mags client for interacting with the Magpie VM infrastructure API."""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import requests
+
+
+class MagsError(Exception):
+    """Raised when the Mags API returns an error."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class Mags:
+    """Client for the Mags API.
+
+    Args:
+        api_token: API token. Falls back to ``MAGS_API_TOKEN`` or ``MAGS_TOKEN`` env vars.
+        api_url: API base URL. Falls back to ``MAGS_API_URL`` env var or
+            ``https://api.magpiecloud.com``.
+        timeout: Default request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_token: str | None = None,
+        api_url: str | None = None,
+        timeout: int = 30,
+    ):
+        self.api_url = (
+            api_url
+            or os.environ.get("MAGS_API_URL")
+            or "https://api.magpiecloud.com"
+        ).rstrip("/")
+
+        self.api_token = (
+            api_token
+            or os.environ.get("MAGS_API_TOKEN")
+            or os.environ.get("MAGS_TOKEN")
+        )
+        if not self.api_token:
+            raise MagsError(
+                "API token required. Set MAGS_API_TOKEN env var or pass api_token."
+            )
+
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {self.api_token}",
+                "Content-Type": "application/json",
+            }
+        )
+
+    # ── helpers ──────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: Any = None,
+        params: dict | None = None,
+        timeout: int | None = None,
+    ) -> Any:
+        url = f"{self.api_url}/api/v1{path}"
+        resp = self._session.request(
+            method,
+            url,
+            json=json,
+            params=params,
+            timeout=timeout or self.timeout,
+        )
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                msg = body.get("error") or body.get("message") or resp.text
+            except Exception:
+                msg = resp.text
+            raise MagsError(msg, status_code=resp.status_code)
+        if not resp.content:
+            return {}
+        return resp.json()
+
+    # ── jobs ─────────────────────────────────────────────────────────
+
+    def run(
+        self,
+        script: str,
+        *,
+        name: str | None = None,
+        workspace_id: str | None = None,
+        base_workspace_id: str | None = None,
+        persistent: bool = False,
+        ephemeral: bool = False,
+        startup_command: str | None = None,
+        environment: Dict[str, str] | None = None,
+        file_ids: List[str] | None = None,
+    ) -> dict:
+        """Submit a job for execution.
+
+        Returns ``{"request_id": ..., "status": "accepted"}``.
+        """
+        if ephemeral and workspace_id:
+            raise MagsError("Cannot use ephemeral with workspace_id")
+        if ephemeral and persistent:
+            raise MagsError("Cannot use ephemeral with persistent")
+
+        payload = {
+            "script": script,
+            "type": "inline",
+            "persistent": persistent,
+        }
+        if name:
+            payload["name"] = name
+        if not ephemeral and workspace_id:
+            payload["workspace_id"] = workspace_id
+        if base_workspace_id:
+            payload["base_workspace_id"] = base_workspace_id
+        if startup_command:
+            payload["startup_command"] = startup_command
+        if environment:
+            payload["environment"] = environment
+        if file_ids:
+            payload["file_ids"] = file_ids
+
+        return self._request("POST", "/mags-jobs", json=payload)
+
+    def run_and_wait(
+        self,
+        script: str,
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 1.0,
+        **run_kwargs: Any,
+    ) -> dict:
+        """Submit a job and block until it completes or times out.
+
+        Returns a dict with ``request_id``, ``status``, ``exit_code``,
+        ``duration_ms``, and ``logs``.
+        """
+        result = self.run(script, **run_kwargs)
+        request_id = result["request_id"]
+
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            status = self.status(request_id)
+            if status["status"] in ("completed", "error"):
+                logs_resp = self.logs(request_id)
+                return {
+                    "request_id": request_id,
+                    "status": status["status"],
+                    "exit_code": status.get("exit_code", 0),
+                    "duration_ms": status.get("script_duration_ms", 0),
+                    "logs": logs_resp.get("logs", []),
+                }
+            time.sleep(poll_interval)
+
+        raise MagsError(f"Job {request_id} timed out after {timeout}s")
+
+    def status(self, request_id: str) -> dict:
+        """Get the status of a job."""
+        return self._request("GET", f"/mags-jobs/{request_id}/status")
+
+    def logs(self, request_id: str) -> dict:
+        """Get logs for a job. Returns ``{"logs": [...]}`."""
+        return self._request("GET", f"/mags-jobs/{request_id}/logs")
+
+    def list_jobs(self, *, page: int = 1, page_size: int = 20) -> dict:
+        """List recent jobs. Returns ``{"jobs": [...], "total": N, ...}``."""
+        return self._request(
+            "GET", "/mags-jobs", params={"page": page, "page_size": page_size}
+        )
+
+    def update_job(self, request_id: str, *, startup_command: str) -> dict:
+        """Update a job (e.g. set startup command for wake-from-sleep)."""
+        return self._request(
+            "PATCH", f"/mags-jobs/{request_id}", json={"startup_command": startup_command}
+        )
+
+    def enable_access(self, request_id: str, *, port: int = 8080) -> dict:
+        """Enable external access (URL or SSH) for a persistent job's VM.
+
+        Use ``port=22`` for SSH access, or ``port=8080`` (default) for HTTP/URL access.
+        """
+        return self._request(
+            "POST", f"/mags-jobs/{request_id}/access", json={"port": port}
+        )
+
+    def usage(self, *, window_days: int = 30) -> dict:
+        """Get aggregated usage summary."""
+        return self._request(
+            "GET", "/mags-jobs/usage", params={"window_days": window_days}
+        )
+
+    # ── file uploads ─────────────────────────────────────────────────
+
+    def upload_file(self, file_path: str) -> str:
+        """Upload a single file. Returns the file ID."""
+        p = Path(file_path)
+        if not p.exists():
+            raise MagsError(f"File not found: {file_path}")
+
+        url = f"{self.api_url}/api/v1/mags-files"
+        # Use a fresh request without the JSON content-type
+        resp = requests.post(
+            url,
+            files={"file": (p.name, p.read_bytes(), "application/octet-stream")},
+            headers={"Authorization": f"Bearer {self.api_token}"},
+            timeout=self.timeout,
+        )
+        if resp.status_code >= 400:
+            raise MagsError(resp.text, status_code=resp.status_code)
+        data = resp.json()
+        file_id = data.get("file_id")
+        if not file_id:
+            raise MagsError(f"Upload failed for {p.name}: {data}")
+        return file_id
+
+    def upload_files(self, file_paths: List[str]) -> List[str]:
+        """Upload multiple files. Returns a list of file IDs."""
+        return [self.upload_file(fp) for fp in file_paths]
+
+    # ── workspaces ────────────────────────────────────────────────────
+
+    def list_workspaces(self) -> dict:
+        """List all workspaces. Returns ``{"workspaces": [...], "total": N}``."""
+        return self._request("GET", "/mags-workspaces")
+
+    def delete_workspace(self, workspace_id: str) -> dict:
+        """Delete a workspace and all its stored data.
+
+        This permanently removes the workspace filesystem from S3.
+        Active jobs using the workspace must be stopped first.
+        """
+        return self._request("DELETE", f"/mags-workspaces/{workspace_id}")
+
+    # ── cron jobs ────────────────────────────────────────────────────
+
+    def cron_create(
+        self,
+        *,
+        name: str,
+        cron_expression: str,
+        script: str,
+        workspace_id: str | None = None,
+        environment: Dict[str, str] | None = None,
+        persistent: bool = False,
+    ) -> dict:
+        """Create a scheduled cron job."""
+        payload = {
+            "name": name,
+            "cron_expression": cron_expression,
+            "script": script,
+            "persistent": persistent,
+        }
+        if workspace_id:
+            payload["workspace_id"] = workspace_id
+        if environment:
+            payload["environment"] = environment
+        return self._request("POST", "/mags-cron", json=payload)
+
+    def cron_list(self) -> dict:
+        """List all cron jobs."""
+        return self._request("GET", "/mags-cron")
+
+    def cron_get(self, cron_id: str) -> dict:
+        """Get a cron job by ID."""
+        return self._request("GET", f"/mags-cron/{cron_id}")
+
+    def cron_update(self, cron_id: str, **updates: Any) -> dict:
+        """Update a cron job. Pass fields as keyword arguments."""
+        return self._request("PATCH", f"/mags-cron/{cron_id}", json=updates)
+
+    def cron_delete(self, cron_id: str) -> dict:
+        """Delete a cron job."""
+        return self._request("DELETE", f"/mags-cron/{cron_id}")

package/skill.md

@@ -0,0 +1,153 @@
+# 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/"
+```