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 a persistent workspace with all dependencies
mags run -n python-base -p 'pip install pandas flask requests'

# Fast throwaway runs mounting it read-only as a base
mags run --base python-base '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

Deploy a Docker Image

Turn any image into a managed app with a public URL. Scale-to-zero by default.

mags deploy -i nginx:latest -n my-site --port 80
# Live at https://my-site.apps.mags.run

Deploy an API with Env Vars

Pass configuration and secrets into your deployment with repeatable -e flags.

mags deploy -i node:20 -n my-api -p 3000 \
  -e "DB_URL=postgres://..." -e "SECRET=xyz"

Deploy a Heavy ML Image

Lazy-load multi-gigabyte images from object storage instead of materializing the full rootfs.

mags deploy -i pytorch/pytorch:latest -n ml --port 80 --heavy

Persistent State with Volumes

Attach a durable, object-storage-backed volume so state survives restarts and failover.

mags deploy -i my/app:latest -n hermes \
  --volume bucket:hermes-state:/opt/data

Instant Rollback

Every deploy is a new version. Roll back to the previous one in one command.

mags deploy -i my/app:v2 -n my-app
mags rollback my-app
# Back on the previous version