Cookbook
Get started
Recipes

Hands-on workflows for developers and hobbyists.

Copy these recipes to bootstrap a new workspace, run tests, or expose a service. Each example is built around real Mags commands.

Browse recipes Claude integration
Starter Workflow 
mags new dev-env
mags ssh dev-env

# inside the VM
apk add git nodejs npm

Create a dev sandbox with one command. Add -p for S3 persistence.

Cookbook

Recipes you can reuse today.

Quick script run

Starter 
mags run 'echo Hello World'

Persistent Python workspace

Workspace 
mags run -w ml-project \
  'apk add python3 py3-pip && pip install numpy pandas'

mags run -w ml-project \
  'python3 train.py'

Run tests with cached deps

CI 
mags run -w myapp 'npm ci'

mags run -w myapp 'npm test'

Expose a simple web server

URL 
mags run -p --url \
  'python3 -m http.server 8080'

Remember: your app should listen on the same port.

Node.js app with startup command

Persistent 
mags run -w myapp -p --url --port 3000 \
  --startup-command 'npm start' \
  'npm install && npm start'

Upload files and run

File 
# Upload a script and a data file, then run
mags run -f analyze.py -f data.csv \
  'python3 analyze.py'

# Upload into a workspace (files persist)
mags run -w analytics -f analyze.py -f data.csv \
  'cp *.py *.csv /root/ && python3 /root/analyze.py'

Files land in /root/ before your script runs.

Ephemeral run (fastest)

Speed 
mags run -e 'uname -a && df -h'

No workspace sync. Best for quick one-off commands.

Manage cron jobs

Cron 
# Schedule a health check every 5 minutes
mags cron add --name "health-check" \
  --schedule "*/5 * * * *" -w monitors \
  'curl -sf https://myapp.com/health || echo FAIL >> /root/alerts.log'

# List all cron jobs
mags cron list

# Disable / enable / remove
mags cron disable <id>
mags cron enable <id>
mags cron remove <id>

Inspect job output

Debug 
mags list
mags status <job-id>
mags logs <job-id>

HN Top 10 Digest

Cron 
# Upload script + install deps (file lands in /root/)
mags run -f hn-marketing.sh -w hn-digest \
  'chmod +x /root/hn-marketing.sh && apk add -q curl jq'

# Run it once (saves to /root/hn-top10.csv)
mags run -w hn-digest 'HN_CSV=/root/hn-top10.csv sh /root/hn-marketing.sh'

# Schedule it (every 2 hours, results append to CSV)
mags cron add --name "hn-top10" \
  --schedule "0 */2 * * *" -w hn-digest \
  'HN_CSV=/root/hn-top10.csv sh /root/hn-marketing.sh'

Download hn-marketing.sh  ·  Full recipe + live demo →

SDK + API

Automate runs from code.

Node.js SDK

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 and run
const fileIds = await mags.uploadFiles(['script.py', 'data.csv']);
const res = await mags.run('python3 script.py', { fileIds });

// Schedule a cron job
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();

REST API

# 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
  }'

# Upload a file
curl -X POST https://api.magpiecloud.com/api/v1/mags-files \
  -H "Authorization: Bearer $MAGS_API_TOKEN" \
  -F "file=@script.py"

# Create a cron job
curl -X POST https://api.magpiecloud.com/api/v1/mags-cron \
  -H "Authorization: Bearer $MAGS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "health-check",
    "cron_expression": "*/5 * * * *",
    "script": "curl -sf https://myapp.com/health"
  }'