@magpiecloud/mags 1.8.11 → 1.8.13

package/website/llms.txt

@@ -1,8 +1,8 @@
 # Mags
 
-> Instant sandboxes and runtime environments
+> Secure cloud sandboxes for AI agents and developers
 
-Mags is a CLI, SDK, and API for running scripts on isolated microVMs with persistent workspaces, file upload, cron scheduling, and optional URL access.
+Mags is a CLI, SDK, and API for running scripts on isolated microVMs with workspaces, file upload, cron scheduling, and optional URL access.
 
 ## Quickstart
 
@@ -26,32 +26,55 @@ mags run 'echo Hello World'
 - `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 new <name> [-p]` — Create a VM sandbox (add -p for S3 data persistence)
 - `mags run <script>` — Execute a script on a microVM
-- `mags ssh <workspace>` — Open an SSH session into a workspace
-- `mags exec <workspace> <command>` — Run a command on an existing sandbox
-- `mags url <job-id>` — Enable public URL access for a running job
+- `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 <job-id>` — View job logs
-- `mags status <job-id>` — Check job status
-- `mags stop <job-id>` — Stop a running job
+- `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 <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 |
+| `-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 S3 sync (fastest). Cannot combine with -w or -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 |
+| `--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
 
@@ -64,8 +87,8 @@ 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'
+# 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
@@ -96,24 +119,20 @@ mags cron disable <id>
 |------|-------------|
 | `-n, --name` | Cron job name (required) |
 | `-s, --schedule` | Cron expression, e.g. "0 */2 * * *" (required) |
-| `-w, --workspace` | Workspace ID for persistent storage |
+| `-w, --workspace` | Workspace ID for 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.
+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 workspace
-mags run -w my-project -f server.js -f package.json \
+# 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
-mags run -w my-project 'cd /root && node server.js'
+# 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'
@@ -123,9 +142,27 @@ 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 or S3 sync overhead:
+For the fastest runs with no workspace at all:
 ```
 mags run -e 'uname -a && df -h'
 ```
@@ -150,12 +187,17 @@ Generate tokens at https://mags.run/tokens or via `mags login`.
 - `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
+- `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
@@ -193,9 +235,12 @@ mags = Mags()  # uses MAGS_API_TOKEN env var
 result = mags.run_and_wait('echo Hello World')
 print(result['logs'])
 
-# Create a persistent workspace
+# 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'])
@@ -265,8 +310,8 @@ Then use `/mags <description>` in Claude Code to run scripts in microVMs.
 
 - Alpine Linux base image
 - Hostname: `mags-vm`
-- Persistent home: `/root` (synced to S3 with workspaces)
-- JuiceFS mount: `/jfs`
+- Home directory: `/root`
+- JuiceFS mount: `/jfs` (persistent workspaces only)
 - Package manager: `apk`
 - Pre-installed: curl, wget, git, python3, node, vim, nano
 

package/website/mags.md

@@ -31,9 +31,10 @@ mags run -p --url '<script>'
 mags run -w <workspace> -p --url --port 3000 '<script>'
 ```
 
-### Create a new persistent VM (stays alive for SSH)
+### Create a new VM sandbox (stays alive for SSH)
 ```bash
-mags new <name>
+mags new <name>            # Local disk only
+mags new <name> -p         # With S3 data persistence
 ```
 
 ### Execute a command on an existing sandbox