@magpiecloud/mags 1.8.13 → 1.8.15

package/website/llms.txt

@@ -1,334 +0,0 @@
-# Mags
-
-> Secure cloud sandboxes for AI agents and developers
-
-Mags is a CLI, SDK, and API for running scripts on isolated microVMs with workspaces, file upload, cron scheduling, and optional URL access.
-
-## Quickstart
-
-Install the CLI:
-```
-npm install -g @magpiecloud/mags
-```
-
-Authenticate:
-```
-mags login
-```
-
-Run your first script:
-```
-mags run 'echo Hello World'
-```
-
-## Core CLI Commands
-
-- `mags login` — Authenticate and save credentials
-- `mags logout` — Remove saved credentials
-- `mags whoami` — Check auth status
-- `mags new <name> [-p]` — Create a VM sandbox (add -p for S3 data persistence)
-- `mags run <script>` — Execute a script on a microVM
-- `mags ssh <name>` — Open an SSH session into a sandbox (auto-starts if needed)
-- `mags exec <name> <command>` — Run a command on an existing sandbox
-- `mags list` — List recent jobs
-- `mags logs <name|id>` — View job logs
-- `mags status <name|id>` — Check job status
-- `mags stop <name|id>` — Stop a running job
-- `mags sync <name|id>` — Sync workspace to S3 without stopping the VM
-- `mags resize <name> --disk <GB>` — Resize disk for a workspace
-- `mags url <name|id> [port]` — Enable public URL access for a running job
-- `mags url alias <subdomain> <name>` — Create a stable URL alias
-- `mags url alias list` — List URL aliases
-- `mags url alias remove <subdomain>` — Remove a URL alias
-- `mags set <name|id> --no-sleep` — Never auto-sleep this VM
-- `mags set <name|id> --sleep` — Re-enable auto-sleep
-- `mags workspace list` — List persistent workspaces
-- `mags workspace delete <id>` — Delete workspace and cloud data
-- `mags browser [name]` — Start a Chromium browser session (CDP access)
-
-## Run Options
-
-`-w` and `-n` are aliases — both set the job name and workspace ID to the same value.
-
-| Flag | Description |
-|------|-------------|
-| `-w, --workspace <name>` | Name the job and workspace. Data stays local to the VM only (not synced to S3). Useful for data analysis where you don't need artifacts to persist. Combine with `-p` to sync to S3 and persist. |
-| `-n, --name <name>` | Alias for `-w` |
-| `-p, --persistent` | Keep VM alive after script and sync workspace to S3. Files persist across runs indefinitely. Required for URL, SSH, and cloud persistence. |
-| `--base <workspace>` | Mount an existing workspace read-only as a starting point (OverlayFS). Use with `-w` to fork into a new workspace. |
-| `--no-sleep` | Never auto-sleep this VM (requires -p) |
-| `-e, --ephemeral` | No workspace, no sync (fastest). Cannot combine with -w, -p, or --base |
-| `-f, --file <path>` | Upload a local file into /root/ in the VM (repeatable) |
-| `--url` | Enable public URL (requires -p) |
-| `--port <port>` | Port to expose (default: 8080) |
-| `--disk <GB>` | Custom disk size in GB (default: 2) |
-| `--startup-command <cmd>` | Command to run when a VM wakes from sleep |
-
-## Workspace Modes
-
-| Flags | Behavior |
-|-------|----------|
-| (none) | Ephemeral. No workspace, no persistence. |
-| `-w myproject` | Local workspace. Data stays on the VM only (~5 min warm cache after job completes). Not synced to S3. Good for data analysis and throwaway work. |
-| `-w myproject -p` | Persistent workspace. VM stays alive, data synced to S3. Files survive across runs indefinitely. |
-| `--base golden` | Read-only base image. Changes discarded after run. |
-| `--base golden -w fork-1` | Fork: starts from golden, saves changes to fork-1 (local only without -p). |
-| `--base golden -w fork-1 -p` | Fork with persistence: starts from golden, saves to fork-1 in S3. |
-| `-e` | Explicit ephemeral. Same as no flags but cannot accidentally combine with -w or -p. |
-
-## File Upload
-
-Upload local files into the VM before your script runs. Files appear at `/root/<filename>`.
-
-```
-# Single file
-mags run -f script.py 'python3 script.py'
-
-# Multiple files
-mags run -f analyze.py -f data.csv 'python3 analyze.py'
-
-# With persistent workspace
-mags run -w my-project -p -f config.json -f app.js 'cp *.js *.json /root/ && cd /root && npm install'
-```
-
-## Cron Scheduling
-
-Schedule recurring jobs with standard cron expressions.
-
-```
-# Create a cron job
-mags cron add --name "daily-backup" --schedule "0 0 * * *" 'tar czf /root/backup.tar.gz /root/data'
-
-# Create with workspace
-mags cron add --name "health-check" --schedule "*/5 * * * *" -w monitors 'curl -sf https://myapp.com/health'
-
-# List cron jobs
-mags cron list
-
-# Remove a cron job
-mags cron remove <id>
-
-# Enable / disable
-mags cron enable <id>
-mags cron disable <id>
-```
-
-### Cron flags for `add`
-
-| Flag | Description |
-|------|-------------|
-| `-n, --name` | Cron job name (required) |
-| `-s, --schedule` | Cron expression, e.g. "0 */2 * * *" (required) |
-| `-w, --workspace` | Workspace ID for storage |
-| `-p, --persistent` | Keep VM alive after script |
-
-## Complex Project Workflow
-
-For multi-file projects, the recommended pattern is: create files locally, upload them, then run persistently.
-
-```
-# Step 1: Upload files and install deps in a persistent workspace
-mags run -w my-project -p -f server.js -f package.json \
-  'cp *.js *.json /root/ && cd /root && npm install'
-
-# Step 2: Test run (reuses the persistent workspace)
-mags run -w my-project -p 'cd /root && node server.js'
-
-# Step 3: Run with public URL
-mags run -w my-project -p --url --port 3000 'cd /root && node server.js'
-
-# Step 4: Schedule recurring run with cron
-mags cron add --name "my-server" --schedule "0 */6 * * *" -w my-project \
-  'cd /root && node server.js'
-```
-
-## Data Analysis Workflow
-
-For throwaway analysis where you need a workspace but don't care about persisting artifacts:
-
-```
-# Upload data and analyze — workspace is local only, no S3 overhead
-mags run -w analysis -f data.csv 'python3 -c "
-import csv
-with open(\"/root/data.csv\") as f:
-    reader = csv.reader(f)
-    for row in reader:
-        print(row)
-"'
-
-# Results printed to stdout (use `mags logs` to retrieve)
-# VM and data cleaned up automatically after ~5 minutes
-```
-
-## Ephemeral Mode
-
-For the fastest runs with no workspace at all:
-```
-mags run -e 'uname -a && df -h'
-```
-
-## API
-
-Base URL: `https://api.magpiecloud.com/api/v1`
-
-### Authentication
-
-Use a Bearer token in the Authorization header:
-```
-Authorization: Bearer <your-api-token>
-```
-
-Generate tokens at https://mags.run/tokens or via `mags login`.
-
-### Job Endpoints
-
-- `POST /mags-jobs` — Submit a job (supports `file_ids` array for uploaded files)
-- `GET /mags-jobs` — List jobs
-- `GET /mags-jobs/{id}/status` — Get job status
-- `GET /mags-jobs/{id}/logs` — Get job logs
-- `POST /mags-jobs/{id}/access` — Enable URL or SSH access
-- `PATCH /mags-jobs/{id}` — Update job settings (startup_command, no_sleep)
-
-### File Endpoints
-
-- `POST /mags-files` — Upload file(s) via multipart/form-data (max 100MB)
-
-### Workspace Endpoints
-
-- `GET /mags-workspaces` — List workspaces
-- `DELETE /mags-workspaces/{id}` — Delete workspace and S3 data
-
-### Cron Endpoints
-
-- `POST /mags-cron` — Create a cron job
-- `GET /mags-cron` — List cron jobs
-- `GET /mags-cron/{id}` — Get a specific cron job
-- `PATCH /mags-cron/{id}` — Update a cron job
-- `DELETE /mags-cron/{id}` — Delete a cron job
-
-### 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 World",
-    "type": "inline",
-    "workspace_id": "myproject",
-    "persistent": true
-  }'
-```
-
-## Python SDK
-
-```
-pip install magpie-mags
-```
-
-```python
-from mags import Mags
-
-mags = Mags()  # uses MAGS_API_TOKEN env var
-
-# Run a script and wait for result
-result = mags.run_and_wait('echo Hello World')
-print(result['logs'])
-
-# Create a sandbox (local disk)
-mags.new('my-project')
-
-# Create with S3 persistence
-mags.new('my-project', persistent=True)
-
-# Execute a command on an existing sandbox
-result = mags.exec('my-project', 'ls -la /root')
-print(result['output'])
-
-# Stop a running job
-mags.stop('my-project')
-
-# Enable public URL
-info = mags.url('my-project', port=3000)
-print(info['url'])
-
-# Find a job by name or workspace
-job = mags.find_job('my-project')
-
-# Upload files and run
-file_ids = mags.upload_files(['script.py', 'data.csv'])
-mags.run('python3 script.py', file_ids=file_ids)
-
-# Cron jobs
-mags.cron_create(name='daily-backup', cron_expression='0 0 * * *',
-                 script='tar czf backup.tar.gz /data', workspace_id='my-ws')
-mags.cron_delete(cron_id)
-```
-
-## Node.js SDK
-
-```
-npm install @magpiecloud/mags
-```
-
-```js
-const Mags = require('@magpiecloud/mags');
-
-const mags = new Mags({
-  apiToken: process.env.MAGS_API_TOKEN
-});
-
-// Run a script
-const result = await mags.runAndWait('echo Hello World');
-console.log(result.logs);
-
-// Upload files
-const fileIds = await mags.uploadFiles(['script.py', 'data.csv']);
-const result = await mags.run('python3 script.py', { fileIds });
-
-// Cron jobs
-await mags.cronCreate({
-  name: 'daily-backup',
-  cronExpression: '0 0 * * *',
-  script: 'tar czf backup.tar.gz /data',
-  workspaceId: 'my-workspace'
-});
-const { cron_jobs } = await mags.cronList();
-await mags.cronDelete(id);
-```
-
-## Claude Code Integration
-
-Install the Mags skill for Claude Code:
-```
-mags setup-claude
-```
-
-Then use `/mags <description>` in Claude Code to run scripts in microVMs.
-
-## VM Environment
-
-- Alpine Linux base image
-- Hostname: `mags-vm`
-- Home directory: `/root`
-- JuiceFS mount: `/jfs` (persistent workspaces only)
-- Package manager: `apk`
-- Pre-installed: curl, wget, git, python3, node, vim, nano
-
-## Cookbook
-
-Ready-to-run recipes at https://mags.run/cookbook including:
-- Quick script runs
-- Persistent Python/Node workspaces
-- Exposing web servers with URLs
-- HN Marketing Digest cron job
-
-## Links
-
-- Website: https://mags.run
-- Dashboard: https://mags.run/dashboard
-- API Tokens: https://mags.run/tokens
-- API Reference: https://mags.run/api
-- Cookbook: https://mags.run/cookbook
-- Claude Skill: https://mags.run/claude-skill
-- Documentation: https://mags.run/#cli

package/website/login.html

@@ -1,108 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Mags Login</title>
-    <meta name="description" content="Sign in to Mags with Google." />
-    <meta name="api-base" content="https://api.magpiecloud.com" />
-    <meta name="auth-base" content="https://api.magpiecloud.com" />
-    <link rel="stylesheet" href="styles.css?v=6" />
-    <script src="env.js"></script>
-  </head>
-  <body>
-    <div class="backdrop"></div>
-
-    <header class="site-header">
-      <div class="container nav">
-        <div class="brand">
-          <span class="logo">Mags</span>
-          <span class="tag">Sign in</span>
-        </div>
-        <nav class="nav-links">
-          <a href="index.html">Home</a>
-          <a href="index.html#quickstart">Docs</a>
-          <a href="api.html">API</a>
-          <a href="cookbook.html">Cookbook</a>
-          <a href="https://discord.gg/3avpC2nS" target="_blank" rel="noreferrer">Discord</a>
-        </nav>
-        <div class="nav-cta">
-          <a class="button ghost" href="index.html">Back to home</a>
-        </div>
-      </div>
-    </header>
-
-    <main class="auth-page">
-      <div class="container auth-layout">
-        <div class="auth-shell">
-          <div>
-            <span class="pill">Login</span>
-            <h1 class="auth-title">Sign in to Mags.</h1>
-            <p class="auth-subtitle">Sign in with your Google account to get started.</p>
-          </div>
-
-          <button class="button full" type="button" data-google-login>Continue with Google</button>
-        </div>
-      </div>
-    </main>
-
-    <footer class="site-footer">
-      <div class="container footer-grid">
-        <div>
-          <div class="brand">
-            <span class="logo">Mags</span>
-            <span class="tag">Instant sandboxes and runtime environments</span>
-          </div>
-          <p>Build, test, and run from clean microVMs whenever you need them.</p>
-        </div>
-        <div class="footer-links">
-          <a href="index.html">Home</a>
-          <a href="api.html">API</a>
-          <a href="cookbook.html">Cookbook</a>
-          <a href="https://discord.gg/3avpC2nS" target="_blank" rel="noreferrer">Discord</a>
-        </div>
-      </div>
-    </footer>
-
-    <script src="script.js?v=7"></script>
-    <script>
-    (function() {
-      // Handle logout: clear tokens when ?logout=1 is present
-      var params = new URLSearchParams(window.location.search);
-      if (params.get('logout') === '1') {
-        localStorage.removeItem('microvm-access-token');
-        localStorage.removeItem('microvm-refresh-token');
-        // Clean up the URL
-        window.history.replaceState({}, '', 'login.html');
-        return;
-      }
-
-      // If already logged in, redirect to next or show dashboard link
-      var token = localStorage.getItem('microvm-access-token');
-      if (token) {
-        var next = params.get('next');
-        if (next && next.startsWith('/')) {
-          window.location.replace(next);
-          return;
-        }
-        var shell = document.querySelector('.auth-shell');
-        if (shell) {
-          shell.innerHTML =
-            '<div>' +
-              '<span class="pill">Logged in</span>' +
-              '<h1 class="auth-title">You\'re signed in.</h1>' +
-              '<p class="auth-subtitle">You\'re already logged in to Mags.</p>' +
-            '</div>' +
-            '<a class="button full" href="usage.html">Go to Dashboard</a>' +
-            '<button class="button ghost full" type="button" id="logout-btn" style="margin-top:0.75rem">Sign out</button>';
-          document.getElementById('logout-btn').addEventListener('click', function() {
-            localStorage.removeItem('microvm-access-token');
-            localStorage.removeItem('microvm-refresh-token');
-            window.location.reload();
-          });
-        }
-      }
-    })();
-    </script>
-  </body>
-</html>

package/website/mags.md

@@ -1,210 +0,0 @@
-# Mags Job Runner
-
-Execute scripts on Magpie's instant microVM infrastructure using the `mags` CLI.
-
-## How to Use
-
-IMPORTANT: Always use the `mags` CLI tool. NEVER use curl or direct API calls.
-The CLI handles authentication, polling, and output automatically.
-
-When the user says `/mags <command or description>`, run it using the `mags` CLI.
-
-## Commands
-
-### Run a script
-```bash
-mags run '<script>'
-```
-
-### Run with a persistent workspace (changes saved to S3)
-```bash
-mags run -w <workspace-name> '<script>'
-```
-
-### Run a persistent VM with public URL
-```bash
-mags run -p --url '<script>'
-```
-
-### Run with workspace + persistence + URL + custom port
-```bash
-mags run -w <workspace> -p --url --port 3000 '<script>'
-```
-
-### Create a new VM sandbox (stays alive for SSH)
-```bash
-mags new <name>            # Local disk only
-mags new <name> -p         # With S3 data persistence
-```
-
-### Execute a command on an existing sandbox
-```bash
-mags exec <name-or-id> '<command>'
-```
-
-### SSH into a running VM
-```bash
-mags ssh <name-or-id>
-```
-
-### Check job status
-```bash
-mags status <name-or-id>
-```
-
-### View job logs
-```bash
-mags logs <name-or-id>
-```
-
-### List recent jobs
-```bash
-mags list
-```
-
-### Enable URL access on existing job
-```bash
-mags url <name-or-id> [port]
-```
-
-### Stop a running job
-```bash
-mags stop <name-or-id>
-```
-
-### Update VM settings
-```bash
-mags set <name-or-id> --no-sleep    # Never auto-sleep
-mags set <name-or-id> --sleep       # Re-enable auto-sleep
-```
-
-### Run without workspace (ephemeral, fastest)
-```bash
-mags run -e '<script>'
-```
-
-### Upload files into the VM before running
-```bash
-mags run -f script.py -f data.csv 'python3 script.py'
-```
-
-### Cron: schedule recurring jobs
-```bash
-mags cron add --name "daily-backup" --schedule "0 0 * * *" 'tar czf /root/backup.tar.gz /root/data'
-mags cron list
-mags cron remove <id>
-mags cron enable <id>
-mags cron disable <id>
-```
-
-## CLI Flags for `run`
-
-| Flag | Description |
-|------|-------------|
-| `-w, --workspace <id>` | Persistent workspace (S3 sync) |
-| `-n, --name <name>` | Job name for easier reference |
-| `-p, --persistent` | Keep VM alive after script |
-| `--no-sleep` | Never auto-sleep this VM (requires -p) |
-| `-e, --ephemeral` | No workspace, no S3 sync (fastest). Cannot combine with -w or -p |
-| `-f, --file <path>` | Upload a file into /root/ in the VM (repeatable) |
-| `--url` | Enable public URL (requires -p) |
-| `--port <port>` | Port to expose (default: 8080) |
-| `--disk <GB>` | Custom disk size in GB (default: 2) |
-| `--startup-command <cmd>` | Command to run when VM wakes |
-
-## Workflow
-
-When the user asks to run something on mags:
-
-1. **Parse the request** - determine the script/command and any flags needed
-2. **Run via CLI** - use `mags run '<script>'` (with appropriate flags)
-3. **Show the output** - the CLI handles polling and displays results automatically
-
-## Examples
-
-### Simple command
-User: `/mags echo Hello World`
-```bash
-mags run 'echo Hello World'
-```
-
-### Install packages and run code
-User: `/mags run python with numpy`
-```bash
-mags run 'apk add python3 py3-pip && pip install numpy && python3 -c "import numpy; print(numpy.array([1,2,3]))"'
-```
-
-### Deploy a web server
-User: `/mags deploy a python web server`
-```bash
-mags run -p --url 'python3 -m http.server 8080'
-```
-
-### Persistent workspace
-User: `/mags set up a node project in my-app workspace`
-```bash
-mags run -w my-app 'cd /root && npm init -y && npm install express'
-```
-
-### Run more commands on existing workspace
-User: `/mags run my server in the my-app workspace`
-```bash
-mags run -w my-app -p --url --port 3000 'cd /root && node index.js'
-```
-
-### Exec into existing workspace sandbox
-User: `/mags install lodash in my-app`
-```bash
-mags exec my-app 'cd /root && npm install lodash'
-```
-
-### Ephemeral (no workspace, fastest)
-User: `/mags quickly check disk info`
-```bash
-mags run -e 'df -h && uname -a'
-```
-
-### Upload a file and run it
-User: `/mags run my local script.py in a VM`
-```bash
-mags run -f script.py 'python3 script.py'
-```
-
-### Upload multiple files
-User: `/mags run my analysis with the data file`
-```bash
-mags run -f analyze.py -f data.csv 'python3 analyze.py'
-```
-
-### Run a command on an existing sandbox
-User: `/mags check what's running on my-app`
-```bash
-mags exec my-app 'ps aux'
-```
-
-### Keep a VM always running (never auto-sleep)
-User: `/mags start a persistent server that never sleeps`
-```bash
-mags run -w my-server -p --no-sleep --url --port 3000 'cd /root && node server.js'
-```
-
-### Schedule a cron job
-User: `/mags schedule a health check every hour`
-```bash
-mags cron add --name "health-check" --schedule "0 * * * *" 'curl -sf https://example.com/health || echo FAIL'
-```
-
-## Authentication
-
-The CLI reads credentials from `~/.mags/config.json` (set via `mags login`).
-If not authenticated, tell the user to run `mags login` first.
-Do NOT hardcode tokens or use environment variables for auth.
-
-## Important Rules
-
-1. ALWAYS use `mags run '...'` - never use curl or direct API calls
-2. ALWAYS quote the script argument in single quotes
-3. The CLI handles job submission, polling, and log retrieval automatically
-4. For multi-line scripts, use semicolons or `&&` to chain commands
-5. If the user wants to create a VM and SSH in, use `mags new <name>` then `mags ssh <name>`
-6. To run a command on an already-running sandbox, use `mags exec <name> '<command>'` instead of starting a new run