# Cookbook

Hands-on recipes and workflows. Copy, paste, and build.

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