Claude Code

# Run code in clean microVMs directly from Claude.

Install the Mags skill to give Claude Code the ability to execute scripts in isolated microVMs. Keep workspaces between runs and use SSH or public URLs when you need them.

Install skill See examples
Isolated environments for repeatable runs. Workspaces persist files and packages between sessions.
Example prompt Claude

    /mags create a python environment
    with numpy and pandas, then run
    a script that generates sample data

Claude handles the API calls and shows you the results.

Installation

## Add the Mags skill to Claude Code.

### 1. Install the CLI

    npm install -g @magpiecloud/mags

### 2. Install the Claude skill

    mags setup-claude

Installs the skill to `~/.claude/commands/`

### 3. Login to Magpie

    mags login

Opens your browser to create an API token.

That's it! You can now use `/mags` in Claude Code.

Features

## What the Mags skill can do.

### Fast execution

Runs start in clean microVMs backed by a warm pool.

### Persistent workspaces

Files in `/root` persist across sessions so you can reuse packages and configs.

### SSH access

Get a full shell via SSH proxy. Debug interactively, explore the filesystem, run commands manually.

### Public URLs

Expose any port with a public URL. Perfect for testing webhooks, APIs, and web apps.

### Full isolation

Each run is isolated in its own microVM environment.

### Auto sleep/wake

Persistent VMs can sleep when idle and wake on request.

### File upload

Upload local files into the VM with `-f`. They appear in `/root/` before your script runs.

### Ephemeral mode

Use `-e` for the fastest runs — no workspace mount or S3 sync overhead.

### Cron scheduling

Schedule recurring jobs with standard cron expressions. Managed via `mags cron`.

Examples

## What you can ask Claude to do.

### Run a simple script

    /mags echo Hello World

Claude submits the job, polls for completion, and shows the output.

### Install packages and run code

    /mags install python with requests
    and fetch https://api.github.com

Claude installs the package and runs the script in one job.

### Create a dev environment

    /mags create a node.js environment
    with express and jest installed

Claude uses a workspace so packages persist between runs.

### Deploy a web server

    /mags run a flask server that
    returns JSON on port 5000 and
    give me the public URL

Claude creates a persistent VM, runs the server, and enables URL access.

### Get SSH access

    /mags create a VM I can SSH into
    with python and vim installed

Claude creates the VM, enables SSH, and gives you the connection command.

### Run tests in isolation

    /mags run the pytest tests from
    this project in a clean environment

Claude copies the relevant files and runs tests in an isolated VM.

### Build and compile code

    /mags compile this Go program
    and show me the output

Claude installs Go, compiles the code, and runs the binary.

### Process data files

    /mags use pandas to analyze
    this CSV and show summary stats

Claude creates a Python environment, loads the data, and runs the analysis.

### Upload files and run

    /mags upload my script.py and data.csv
    and run the analysis

Claude uploads files with `-f`, they land in `/root/` before the script runs.

### Schedule a cron job

    /mags schedule a daily backup at midnight
    that archives /root/data to S3

Claude creates a cron job with `mags cron add` and the right schedule.

Advanced examples

## More complex workflows.

### Multi-step development workflow

    # Step 1: Create a workspace with dependencies
    /mags create workspace "my-api" with python, flask, and sqlalchemy

    # Step 2: Add your application code
    /mags in workspace "my-api" create a REST API with user CRUD endpoints

    # Step 3: Run with a public URL
    /mags run the API in "my-api" on port 5000 and give me the URL

    # Step 4: SSH in to debug
    /mags give me SSH access to "my-api" so I can check the logs

Each step builds on the previous one. Files persist in the workspace.

### Test a webhook endpoint

    /mags create a server that:
    - Listens on port 8080
    - Logs all incoming POST requests to /webhook
    - Returns {"status": "received"}
    - Give me the public URL so I can test with Stripe

Great for testing webhooks from Stripe, GitHub, Slack, etc.

### Prototype with multiple languages

    /mags create a workspace called "polyglot" with:
    - Python 3 with numpy
    - Node.js with axios
    - Go compiler
    Then show me how to call a Python function from Node

Install multiple runtimes in one workspace for polyglot development.

### Complex project: create files, upload, run

    # Step 1: Create your project files locally
    /mags create an Express API server with two routes:
      GET /health and POST /data
    Save it as server.js

    # Step 2: Upload files and install dependencies in a workspace
    /mags upload server.js to workspace "my-api" and run npm init + npm install express

    # Step 3: Start the server with a public URL
    /mags in workspace "my-api" run node server.js on port 3000 with a URL

For complex projects, create the files first, then upload with `-f` and run in a workspace. Files land in `/root/`.

### Cron-based monitoring

    /mags create a cron job called "uptime-check" that runs every 5 minutes
    and curls https://myapp.com/health — if it fails, write to a log file
    Use workspace "monitors" so the log persists

Cron jobs run on a schedule in persistent workspaces. Manage with `mags cron list`.

How it works

## What happens behind the scenes.

### 1. Claude parses your request

The skill instructs Claude how to translate your natural language into Mags API calls.

### 2. Job is submitted

Claude POSTs to the Mags API with your script, workspace ID, and options.

### 3. VM boots

A microVM is allocated from the warm pool to run your script.

### 4. Script executes

Your code runs in Alpine Linux. The `/root` directory syncs to S3.

### 5. Claude polls for results

The skill checks job status until completion, then fetches logs.

### 6. Output is displayed

Claude shows you the script output, any errors, and access URLs if enabled.

VM Environment

## What's available inside the VM.

### System details

- `Alpine Linux` Lightweight base image
- `mags-vm` Hostname
- `/root` Persistent home directory
- `/jfs` Direct JuiceFS mount
- `apk` Package manager

### Pre-installed tools

- `curl, wget` HTTP clients
- `git` Version control
- `python3` Python interpreter
- `node` JavaScript runtime
- `vim, nano` Text editors

Tip: Install additional packages with `apk add <package>`. In a workspace, packages persist between runs.

Complex projects

## Create files first, upload, then run.

For multi-file projects, the best workflow is: create the files locally, upload them with `-f` into a workspace, then run. This keeps your project organized and lets you iterate.

### 1. Create files locally

Write your scripts, configs, and data files on your machine first. Claude can help generate them.

    # Claude writes server.js, package.json, etc.
    # to your local project directory

### 2. Upload and install deps

Upload files with `-f` and install dependencies in a persistent workspace.

    mags run -w my-project \
      -f server.js -f package.json \
      'cp *.js *.json /root/ && \
       cd /root && npm install'

### 3. Run the project

Execute in the same workspace. All your files and packages are still there.

    mags run -w my-project -p --url \
      --port 3000 'cd /root && node server.js'

Pattern: Create locally → upload with `-f` → install in workspace → run. Use `mags cron add` to schedule recurring runs.

Tips

## Get the most out of the skill.

### Use workspaces for projects

Ask Claude to use a workspace name so your files and packages persist. "Create workspace my-app with..."

### Be specific about ports

When running servers, tell Claude which port to use and whether you need a public URL.

### Request SSH for debugging

If something isn't working, ask for SSH access to investigate interactively.

### Check logs on errors

If a job fails, ask Claude to show you the full logs to understand what went wrong.

Reference

## Skill configuration options.

### Environment variables

- `MAGS_API_TOKEN` Your API token (required)
- `MAGS_API_URL` API endpoint (optional)

Default API URL: `https://api.magpiecloud.com`

### Token storage

- `~/.mags/config.json` CLI config file
- `.env.sh` Project env file
- `Environment variable` Shell export