Cookbook — Mags

Quick Script Run

Run a one-liner in an isolated sandbox. No setup, no cleanup.

mags run 'echo Hello World'

Persistent Python Workspace

Install packages that stick across runs. Build up your environment incrementally.

mags run -w py-env -p 'pip install pandas numpy matplotlib'
mags run -w py-env -p 'python analyze.py'

Run Tests with Cached Dependencies

Install once, run tests many times. Dependencies persist in the workspace.

mags run -w tests -p 'npm install && npm test'

Expose a Web Server

Start a web server and get a public URL instantly. Share with your team.

mags run -w webapp -p --url 'npm start'
# Access at the returned public URL

Upload Files and Process

Send local files to a sandbox and process them with any script.

mags run -f data.csv -f process.py 'python process.py'

Create a Dev Environment

Spin up a persistent sandbox, SSH in, and install whatever you need.

mags new dev-env
mags ssh dev-env
# Inside the VM:
apk add git nodejs npm python3

Ephemeral Run (Fastest)

Fire-and-forget execution. The sandbox is destroyed immediately after the run.

mags run --ephemeral 'curl -s https://api.example.com | jq .'

Schedule a Cron Job

Run scripts on a schedule. Great for reports, scraping, and health checks.

mags cron create '0 9 * * *' -w digest -p 'python daily_report.py'
mags cron list

Node.js App with Startup Command

Install dependencies first, then set a startup command for the server.

mags run -w myapp -p --url --startup 'node server.js' 'npm install'

Base Image Workflow

Create a base image with all dependencies, then run fast ephemeral jobs on top.

# Create base with all dependencies
mags run -w python-base --base-image 'pip install pandas flask requests'

# Fast ephemeral runs using the base
mags run -w python-base --ephemeral 'python my_script.py'

Python SDK — Batch Processing

Use the Python SDK to loop through files and process them in parallel sandboxes.

from mags import Mags
client = Mags()

files = ['data1.csv', 'data2.csv', 'data3.csv']
for f in files:
    job = client.run(
        script=f'python process.py {f}',
        files=[f, 'process.py'],
        workspace='batch-job',
        persist=True
    )
    print(f'{f}: {job.status}')

REST API — Submit and Poll

Submit a job via the REST API, then poll for its status using curl and jq.

# Submit
JOB_ID=$(curl -s -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"script": "sleep 5 && echo done", "type": "inline"}' | jq -r .id)

# Poll
curl -s https://api.magpiecloud.com/api/v1/mags-jobs/$JOB_ID \
  -H "Authorization: Bearer $TOKEN" | jq .status