@magpiecloud/mags 1.5.1 → 1.6.1

package/website/llms.txt

@@ -0,0 +1,242 @@
+# Mags
+
+> Instant sandboxes and runtime environments
+
+Mags is a CLI, SDK, and API for running scripts on isolated microVMs with persistent 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 <workspace>` — Create a persistent VM workspace
+- `mags run <script>` — Execute a script on a microVM
+- `mags ssh <workspace>` — Open an SSH session into a workspace
+- `mags url <job-id>` — Enable public URL access for a running job
+- `mags list` — List recent jobs
+- `mags logs <job-id>` — View job logs
+- `mags status <job-id>` — Check job status
+- `mags stop <job-id>` — Stop a running job
+
+## Run Options
+
+| Flag | Description |
+|------|-------------|
+| `-w, --workspace <id>` | Persist files with a named workspace |
+| `-n, --name <name>` | Job name for easier reference |
+| `-p, --persistent` | Keep VM alive after script for URL or SSH |
+| `-e, --ephemeral` | No workspace, no S3 sync (fastest). Cannot combine with -w or -p |
+| `-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) |
+| `--startup-command <cmd>` | Command to run when a VM wakes |
+
+## 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 workspace persistence
+mags run -w my-project -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 persistent storage |
+| `-p, --persistent` | Keep VM alive after script |
+
+## Workspaces
+
+Workspaces persist files, installed packages, and configuration between runs. Running processes, in-memory state, and open ports reset between sessions.
+
+## Complex Project Workflow
+
+For multi-file projects, the recommended pattern is: create files locally, upload them, then run.
+
+```
+# Step 1: Upload files and install deps in a workspace
+mags run -w my-project -f server.js -f package.json \
+  'cp *.js *.json /root/ && cd /root && npm install'
+
+# Step 2: Test run
+mags run -w my-project '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'
+```
+
+## Ephemeral Mode
+
+For the fastest runs with no workspace or S3 sync overhead:
+```
+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 startup command
+
+### File Endpoints
+
+- `POST /mags-files` — Upload file(s) via multipart/form-data (max 100MB)
+
+### 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
+  }'
+```
+
+## 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`
+- Persistent home: `/root` (synced to S3 with workspaces)
+- JuiceFS mount: `/jfs`
+- 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

@@ -0,0 +1,88 @@
+<!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 or email." />
+    <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=2" />
+    <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">Quickstart</a>
+          <a href="index.html#cli">CLI</a>
+          <a href="index.html#api">API</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">Use Google or your email and password.</p>
+          </div>
+
+          <button class="button full" type="button" data-google-login>Continue with Google</button>
+
+          <div class="auth-divider"><span>or</span></div>
+
+          <form class="login-form" data-login-form>
+            <div class="form-group">
+              <label class="form-label" for="login-email">Email</label>
+              <input class="input" type="email" id="login-email" name="email" required />
+            </div>
+            <div class="form-group">
+              <label class="form-label" for="login-password">Password</label>
+              <input class="input" type="password" id="login-password" name="password" required />
+            </div>
+            <button class="button full" type="submit">Sign in</button>
+            <p class="form-message" data-login-message></p>
+          </form>
+
+          <div class="form-links">
+            <a data-auth-link="/auth/forgot-password" href="#">Forgot password?</a>
+            <a data-auth-link="/auth/register" href="#">Create an account</a>
+          </div>
+        </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="usage.html">Usage</a>
+          <a href="tokens.html">Tokens</a>
+          <a href="claude-skill.html">Claude Skill</a>
+        </div>
+      </div>
+    </footer>
+
+    <script src="script.js"></script>
+  </body>
+</html>

package/website/mags.md

@@ -0,0 +1,171 @@
+# 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 persistent VM (stays alive for SSH)
+```bash
+mags new <name>
+```
+
+### 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>
+```
+
+### 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 |
+| `-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) |
+| `--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 'apk add nodejs npm && mkdir -p /workspace/my-app && cd /workspace/my-app && npm init -y'
+```
+
+### 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'
+```
+
+### 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>`