@magpiecloud/mags

Execute scripts instantly on Magpie's microVM infrastructure. VMs boot in <100ms from a warm pool.

Installation

npm install -g @magpiecloud/mags

Quick Start

1. Login to Magpie

mags login

This will open your browser to create an API token. Paste the token when prompted, and it will be saved for future use.

2. Create a sandbox

mags new myproject              # Local disk only
mags new myproject -p           # With S3 persistence
mags ssh myproject

3. Or run a script

mags run 'echo Hello World'

Authentication

Interactive Login (Recommended)

mags login

Opens the Magpie dashboard in your browser where you can create an API token. The token is saved to ~/.mags/config.json and used automatically for all future commands.

Other Auth Commands

mags whoami    # Check current authentication status
mags logout    # Remove saved credentials

Environment Variable

You can also set the token via environment variable (overrides saved config):

export MAGS_API_TOKEN="your-token-here"

CLI Commands

# Create a sandbox (local disk)
mags new myproject

# Create with S3 persistence
mags new myproject -p

# SSH into it
mags ssh myproject

# Run a simple command
mags run 'echo Hello'

# With persistent workspace (S3 sync)
mags run -w my-project 'apk add nodejs && node --version'

# Persistent VM with public URL
mags run -w webapp -p --url 'python3 -m http.server 8080'

# With startup command (for auto-wake)
mags run -w webapp -p --url --startup-command 'npm start' 'npm install && npm start'

# Custom port
mags run -w webapp -p --url --port 3000 'npm start'

# Enable URL for existing job
mags url <job-id>
mags url <job-id> 8080

# Other commands
mags status <job-id>
mags logs <job-id>
mags list
mags stop <job-id>

# Install Claude Code skill
mags setup-claude

Claude Code Integration

Install the Mags skill for Claude Code to run scripts directly from Claude:

mags setup-claude

This lets you use natural language commands like:

• /mags run echo Hello World
• /mags create a python environment with numpy and pandas
• /mags run a flask server and give me the public URL

See mags.run/claude-skill.html for full documentation.

CLI Flags

| Flag | Description | Default | |------|-------------|---------| | -w, --workspace | Workspace ID for persistent storage | auto | | -p, --persistent | Keep VM alive for URL/SSH access | false | | --url | Enable public URL access (requires -p) | false | | --port | Port to expose for URL access | 8080 | | --startup-command | Command when VM wakes from sleep | none |

SSH Access

Connect to any running VM:

mags ssh myproject

Features:

• Connects via secure proxy (api.magpiecloud.com:PORT)
• Full PTY support for interactive terminals
• Automatic SSH key management
• Hostname: mags-vm

Workspaces & Persistence

When using persistent mode (-p), your /root directory syncs to S3:

• Auto-sync: Every 30 seconds while running
• On stop: Full sync before VM terminates
• On wake: Previous state restored

Without -p, data lives on local disk only and is cleaned up when the VM is destroyed.

Node.js SDK

const Mags = require('@magpiecloud/mags');

const mags = new Mags({
  apiToken: process.env.MAGS_API_TOKEN
});

// Run and wait for completion
const result = await mags.runAndWait('echo Hello World');
console.log(result.logs);

// Run with workspace
const { requestId } = await mags.run('python script.py', {
  workspaceId: 'myproject',
  persistent: true
});

// Get status
const status = await mags.status(requestId);

// Enable URL access
await mags.enableUrl(requestId, 8080);

// List jobs
const jobs = await mags.list({ page: 1, pageSize: 10 });

// Stop a job
await mags.stop(requestId);

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MAGS_API_TOKEN | Your API token (required) | - | | MAGS_API_URL | API endpoint | https://api.magpiecloud.com |

Performance

• Warm start: <100ms (VM from pool)
• Cold start: ~4 seconds (new VM boot)
• Script overhead: ~50ms
• Workspace sync: Every 30 seconds

License

MIT