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 persistent dev environment with one command.

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 Marketing Digest

Cron

    # Upload script + install deps
    mags run -f cookbook/hn-marketing.sh -w hn-digest \
      'cp hn-marketing.sh /root/ && chmod +x /root/hn-marketing.sh && apk add -q curl jq'

    # Activate cron (every 2 hours)
    mags cron add --name "hn-marketing" \
      --schedule "0 */2 * * *" -w hn-digest \
      'sh /root/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"
      }'