@magpiecloud/mags 1.5.0 → 1.6.0

package/python/README.md

@@ -0,0 +1,139 @@
+# Mags Python SDK
+
+Execute scripts on [Magpie's](https://mags.run) instant VM infrastructure from Python.
+
+## Install
+
+```bash
+pip install magpie-mags
+```
+
+## Quick Start
+
+```python
+from mags import Mags
+
+m = Mags(api_token="your-token")
+
+# Run a script and wait for the result
+result = m.run_and_wait("echo 'Hello from a VM!'")
+print(result["status"])    # "completed"
+print(result["exit_code"]) # 0
+for log in result["logs"]:
+    print(log["message"])
+```
+
+## Authentication
+
+Pass `api_token` directly, or set one of these environment variables:
+
+```bash
+export MAGS_API_TOKEN="your-token"
+# or
+export MAGS_TOKEN="your-token"
+```
+
+## Usage
+
+### Run a Script
+
+```python
+# Fire-and-forget
+job = m.run("apt install -y ffmpeg && ffmpeg -version")
+print(job["request_id"])
+
+# Run and wait for completion
+result = m.run_and_wait(
+    "python3 -c 'print(sum(range(100)))'",
+    timeout=30,
+)
+```
+
+### Persistent Workspaces
+
+```python
+# First run: creates the workspace
+m.run_and_wait(
+    "pip install pandas && echo 'setup done'",
+    workspace_id="my-project",
+    persistent=True,
+)
+
+# Second run: reuses the workspace (pandas is already installed)
+m.run_and_wait(
+    "python3 -c 'import pandas; print(pandas.__version__)'",
+    workspace_id="my-project",
+)
+```
+
+### Enable URL / SSH Access
+
+```python
+job = m.run("python3 -m http.server 8080", persistent=True)
+
+# HTTP access
+access = m.enable_access(job["request_id"], port=8080)
+print(access["url"])
+
+# SSH access
+ssh = m.enable_access(job["request_id"], port=22)
+print(f"ssh root@{ssh['ssh_host']} -p {ssh['ssh_port']}")
+```
+
+### Upload Files
+
+```python
+file_ids = m.upload_files(["data.csv", "config.json"])
+result = m.run_and_wait(
+    "ls /uploads && wc -l /uploads/data.csv",
+    file_ids=file_ids,
+)
+```
+
+### Cron Jobs
+
+```python
+cron = m.cron_create(
+    name="nightly-backup",
+    cron_expression="0 0 * * *",
+    script="tar czf /workspace/backup.tar.gz /data",
+    workspace_id="backups",
+)
+
+jobs = m.cron_list()
+m.cron_update(cron["id"], enabled=False)
+m.cron_delete(cron["id"])
+```
+
+### Check Usage
+
+```python
+usage = m.usage(window_days=7)
+print(f"Jobs: {usage['total_jobs']}, VM seconds: {usage['vm_seconds']:.0f}")
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `run(script, **opts)` | Submit a job (returns immediately) |
+| `run_and_wait(script, **opts)` | Submit and block until done |
+| `status(request_id)` | Get job status |
+| `logs(request_id)` | Get job logs |
+| `list_jobs(page, page_size)` | List recent jobs |
+| `update_job(request_id, startup_command)` | Update job config |
+| `enable_access(request_id, port)` | Enable URL or SSH access |
+| `usage(window_days)` | Get usage summary |
+| `upload_file(path)` | Upload a file, returns file ID |
+| `upload_files(paths)` | Upload multiple files |
+| `cron_create(**opts)` | Create a cron job |
+| `cron_list()` | List cron jobs |
+| `cron_get(id)` | Get a cron job |
+| `cron_update(id, **updates)` | Update a cron job |
+| `cron_delete(id)` | Delete a cron job |
+
+## Links
+
+- Website: [mags.run](https://mags.run)
+- Node.js SDK: `npm install @magpiecloud/mags`
+- CLI: `go install` or download from releases

package/python/examples/demo.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""
+Mags Python SDK - Usage Examples
+
+Set your API token before running:
+    export MAGS_API_TOKEN="your-token-here"
+
+Then:
+    pip install -e ../          # install the SDK locally
+    python demo.py              # run all examples
+    python demo.py quick        # run just the quick example
+    python demo.py workspace    # run the workspace example
+    python demo.py url          # run the URL access example
+    python demo.py cron         # run the cron example
+    python demo.py usage        # check usage stats
+"""
+
+import sys
+import time
+
+from mags import Mags
+
+
+def quick_run(m: Mags):
+    """Run a simple script and get the output."""
+    print("=== Quick Run ===")
+    result = m.run_and_wait(
+        "echo 'Hello from Mags!' && uname -a && python3 --version",
+        timeout=30,
+    )
+    print(f"Status: {result['status']}")
+    print(f"Exit code: {result['exit_code']}")
+    print(f"Duration: {result['duration_ms']}ms")
+    print("Logs:")
+    for log in result["logs"]:
+        print(f"  [{log['source']}] {log['message']}")
+    print()
+
+
+def workspace_example(m: Mags):
+    """Demonstrate persistent workspaces."""
+    print("=== Persistent Workspace ===")
+    ws = "python-sdk-demo"
+
+    # First run: install something
+    print(f"1. Setting up workspace '{ws}'...")
+    result = m.run_and_wait(
+        "pip install cowsay && echo 'setup done'",
+        workspace_id=ws,
+        persistent=True,
+        timeout=60,
+    )
+    print(f"   Setup: {result['status']} (exit={result['exit_code']})")
+
+    # Second run: use what we installed (it persists!)
+    print(f"2. Running in existing workspace '{ws}'...")
+    result = m.run_and_wait(
+        "python3 -c \"import cowsay; cowsay.cow('Mags Python SDK!')\"",
+        workspace_id=ws,
+        timeout=30,
+    )
+    print(f"   Result: {result['status']} (exit={result['exit_code']})")
+    for log in result["logs"]:
+        if log["source"] == "stdout":
+            print(f"   {log['message']}")
+    print()
+
+
+def url_access_example(m: Mags):
+    """Start a web server and get its public URL."""
+    print("=== URL Access ===")
+
+    # Start a persistent job with a web server
+    job = m.run(
+        "echo '<h1>Hello from Mags!</h1>' > /tmp/index.html && "
+        "cd /tmp && python3 -m http.server 8080",
+        persistent=True,
+        name="python-sdk-webserver",
+    )
+    request_id = job["request_id"]
+    print(f"Job submitted: {request_id}")
+
+    # Wait for it to start running
+    print("Waiting for VM to start...")
+    for _ in range(20):
+        s = m.status(request_id)
+        if s["status"] == "running":
+            break
+        time.sleep(1)
+
+    # Enable URL access
+    access = m.enable_access(request_id, port=8080)
+    print(f"URL: {access.get('url', 'N/A')}")
+    print(f"Access type: {access['access_type']}")
+
+    # Enable SSH access
+    ssh = m.enable_access(request_id, port=22)
+    print(f"SSH: ssh root@{ssh['ssh_host']} -p {ssh['ssh_port']}")
+    print()
+
+
+def cron_example(m: Mags):
+    """Create, list, and clean up a cron job."""
+    print("=== Cron Jobs ===")
+
+    # Create a cron job
+    cron = m.cron_create(
+        name="sdk-test-cron",
+        cron_expression="0 * * * *",  # every hour
+        script="echo 'cron tick' && date",
+    )
+    print(f"Created cron job: {cron['id']} ({cron['name']})")
+
+    # List cron jobs
+    all_crons = m.cron_list()
+    print(f"Total cron jobs: {all_crons.get('total', len(all_crons.get('cron_jobs', [])))}")
+
+    # Disable it
+    m.cron_update(cron["id"], enabled=False)
+    print(f"Disabled cron job: {cron['id']}")
+
+    # Delete it
+    m.cron_delete(cron["id"])
+    print(f"Deleted cron job: {cron['id']}")
+    print()
+
+
+def usage_example(m: Mags):
+    """Show account usage stats."""
+    print("=== Usage Stats ===")
+    u = m.usage(window_days=30)
+    print(f"Window: {u['window_days']} days")
+    print(f"Total jobs: {u['total_jobs']}")
+    print(f"VM seconds: {u['vm_seconds']:.1f}")
+    print(f"CPU seconds: {u['cpu_seconds']:.1f}")
+    print(f"Memory (GB-seconds): {u['memory_gb_seconds']:.1f}")
+    print(f"Storage (GB-seconds): {u['storage_gb_seconds']:.1f}")
+    print(f"VM config: {u['vcpus']} vCPU, {u['memory_mb']}MB RAM, {u['disk_gb']}GB disk")
+    print()
+
+
+def list_jobs(m: Mags):
+    """List recent jobs."""
+    print("=== Recent Jobs ===")
+    resp = m.list_jobs(page=1, page_size=5)
+    for job in resp["jobs"]:
+        print(
+            f"  {job['request_id'][:8]}.. "
+            f"{job['status']:>10}  "
+            f"{job.get('name', 'unnamed')}"
+        )
+    print(f"Total: {resp['total']}")
+    print()
+
+
+EXAMPLES = {
+    "quick": quick_run,
+    "workspace": workspace_example,
+    "url": url_access_example,
+    "cron": cron_example,
+    "usage": usage_example,
+    "list": list_jobs,
+}
+
+if __name__ == "__main__":
+    m = Mags()  # reads MAGS_API_TOKEN from env
+
+    which = sys.argv[1] if len(sys.argv) > 1 else None
+
+    if which and which in EXAMPLES:
+        EXAMPLES[which](m)
+    elif which:
+        print(f"Unknown example: {which}")
+        print(f"Available: {', '.join(EXAMPLES)}")
+        sys.exit(1)
+    else:
+        # Run all examples
+        quick_run(m)
+        list_jobs(m)
+        usage_example(m)
+        print("(Run with 'workspace', 'url', or 'cron' arg for more examples)")

package/python/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "magpie-mags"
+version = "1.0.0"
+description = "Mags SDK - Execute scripts on Magpie's instant VM infrastructure"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "Magpie Cloud"}
+]
+keywords = ["magpie", "mags", "vm", "microvm", "cloud", "serverless", "sandbox"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "requests>=2.25.0",
+]
+
+[project.urls]
+Homepage = "https://mags.run"
+Repository = "https://github.com/magpiecloud/mags"
+Issues = "https://github.com/magpiecloud/mags/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

package/python/src/magpie_mags.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: magpie-mags
+Version: 1.0.0
+Summary: Mags SDK - Execute scripts on Magpie's instant VM infrastructure
+Author: Magpie Cloud
+License: MIT
+Project-URL: Homepage, https://mags.run
+Project-URL: Repository, https://github.com/magpiecloud/mags
+Project-URL: Issues, https://github.com/magpiecloud/mags/issues
+Keywords: magpie,mags,vm,microvm,cloud,serverless,sandbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+
+# Mags Python SDK
+
+Execute scripts on [Magpie's](https://mags.run) instant VM infrastructure from Python.
+
+## Install
+
+```bash
+pip install magpie-mags
+```
+
+## Quick Start
+
+```python
+from mags import Mags
+
+m = Mags(api_token="your-token")
+
+# Run a script and wait for the result
+result = m.run_and_wait("echo 'Hello from a VM!'")
+print(result["status"])    # "completed"
+print(result["exit_code"]) # 0
+for log in result["logs"]:
+    print(log["message"])
+```
+
+## Authentication
+
+Pass `api_token` directly, or set one of these environment variables:
+
+```bash
+export MAGS_API_TOKEN="your-token"
+# or
+export MAGS_TOKEN="your-token"
+```
+
+## Usage
+
+### Run a Script
+
+```python
+# Fire-and-forget
+job = m.run("apt install -y ffmpeg && ffmpeg -version")
+print(job["request_id"])
+
+# Run and wait for completion
+result = m.run_and_wait(
+    "python3 -c 'print(sum(range(100)))'",
+    timeout=30,
+)
+```
+
+### Persistent Workspaces
+
+```python
+# First run: creates the workspace
+m.run_and_wait(
+    "pip install pandas && echo 'setup done'",
+    workspace_id="my-project",
+    persistent=True,
+)
+
+# Second run: reuses the workspace (pandas is already installed)
+m.run_and_wait(
+    "python3 -c 'import pandas; print(pandas.__version__)'",
+    workspace_id="my-project",
+)
+```
+
+### Enable URL / SSH Access
+
+```python
+job = m.run("python3 -m http.server 8080", persistent=True)
+
+# HTTP access
+access = m.enable_access(job["request_id"], port=8080)
+print(access["url"])
+
+# SSH access
+ssh = m.enable_access(job["request_id"], port=22)
+print(f"ssh root@{ssh['ssh_host']} -p {ssh['ssh_port']}")
+```
+
+### Upload Files
+
+```python
+file_ids = m.upload_files(["data.csv", "config.json"])
+result = m.run_and_wait(
+    "ls /uploads && wc -l /uploads/data.csv",
+    file_ids=file_ids,
+)
+```
+
+### Cron Jobs
+
+```python
+cron = m.cron_create(
+    name="nightly-backup",
+    cron_expression="0 0 * * *",
+    script="tar czf /workspace/backup.tar.gz /data",
+    workspace_id="backups",
+)
+
+jobs = m.cron_list()
+m.cron_update(cron["id"], enabled=False)
+m.cron_delete(cron["id"])
+```
+
+### Check Usage
+
+```python
+usage = m.usage(window_days=7)
+print(f"Jobs: {usage['total_jobs']}, VM seconds: {usage['vm_seconds']:.0f}")
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `run(script, **opts)` | Submit a job (returns immediately) |
+| `run_and_wait(script, **opts)` | Submit and block until done |
+| `status(request_id)` | Get job status |
+| `logs(request_id)` | Get job logs |
+| `list_jobs(page, page_size)` | List recent jobs |
+| `update_job(request_id, startup_command)` | Update job config |
+| `enable_access(request_id, port)` | Enable URL or SSH access |
+| `usage(window_days)` | Get usage summary |
+| `upload_file(path)` | Upload a file, returns file ID |
+| `upload_files(paths)` | Upload multiple files |
+| `cron_create(**opts)` | Create a cron job |
+| `cron_list()` | List cron jobs |
+| `cron_get(id)` | Get a cron job |
+| `cron_update(id, **updates)` | Update a cron job |
+| `cron_delete(id)` | Delete a cron job |
+
+## Links
+
+- Website: [mags.run](https://mags.run)
+- Node.js SDK: `npm install @magpiecloud/mags`
+- CLI: `go install` or download from releases

package/python/src/magpie_mags.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/magpie_mags.egg-info/PKG-INFO
+src/magpie_mags.egg-info/SOURCES.txt
+src/magpie_mags.egg-info/dependency_links.txt
+src/magpie_mags.egg-info/requires.txt
+src/magpie_mags.egg-info/top_level.txt
+src/mags/__init__.py
+src/mags/client.py

package/python/src/magpie_mags.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

package/python/src/magpie_mags.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.25.0

package/python/src/magpie_mags.egg-info/top_level.txt

@@ -0,0 +1 @@
+mags

package/python/src/mags/__init__.py

@@ -0,0 +1,6 @@
+"""Mags SDK - Execute scripts on Magpie's instant VM infrastructure."""
+
+from .client import Mags
+
+__all__ = ["Mags"]
+__version__ = "1.0.0"