Mags Documentation

Mags API

Mags runs low-latency jobs backed by a warm VM pool with <100ms warm start. All endpoints live under /api/v1 and require authentication via session cookie or Bearer token.

Submit a Mags Job

{
  "name": "my-job",
  "type": "inline",
  "script": "echo Hello World",
  "workspace_id": "optional-workspace",
  "persistent": true,
  "startup_command": "npm start",
  "environment": {
    "NODE_ENV": "production"
  }
}

Check Status

{
  "request_id": "abc123-def456",
  "name": "my-job",
  "status": "running",
  "vm_id": "vm-xyz789",
  "subdomain": "f25a2d8f80cc",
  "url": "https://f25a2d8f80cc.apps.magpiecloud.com",
  "script_duration_ms": 92,
  "started_at": "2024-01-23T12:00:00Z"
}

Fetch Logs

{
  "logs": [
    {"timestamp": "2024-01-23T12:00:01Z", "level": "info", "message": "Hello World"}
  ]
}

Enable URL Access

# Request
{ "port": 8080 }

# Response
{
  "success": true,
  "url": "https://f25a2d8f80cc.apps.magpiecloud.com",
  "port": 8080
}

Update Job

{ "startup_command": "npm start" }

List Mags Jobs

Pool Status

{
  "idle_vms": 3,
  "busy_vms": 5,
  "total_vms": 8,
  "min_pool_size": 3,
  "max_pool_size": 0
}

Mags CLI (Go)

The Mags CLI is a lightweight Go client for running jobs and managing workspaces.

Install

# macOS (Apple Silicon)
curl -L https://releases.magpiecloud.com/mags/latest/mags-darwin-arm64 -o mags
chmod +x mags
sudo mv mags /usr/local/bin/

# macOS (Intel)
curl -L https://releases.magpiecloud.com/mags/latest/mags-darwin-amd64 -o mags
chmod +x mags
sudo mv mags /usr/local/bin/

# Linux
curl -L https://releases.magpiecloud.com/mags/latest/mags-linux-amd64 -o mags
chmod +x mags
sudo mv mags /usr/local/bin/

Authenticate

export MAGS_API_TOKEN="your-api-token-here"
# Optional: override API URL
export MAGS_API_URL="https://api.magpiecloud.com"

Core Commands

CLI Flags

Deploy Web App with Public URL

# Deploy with public URL
mags run -w webapp -p --url "python3 -m http.server 8080"
# Returns: https://abc123.apps.magpiecloud.com

# 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

# Enable URL access on default port 8080
mags url abc123-job-id

# Enable URL access on custom port
mags url abc123-job-id --port 3000

Mags Shell Script

A lightweight bash script alternative to the Go CLI. No compilation required.

Setup

# Download
curl -L https://raw.githubusercontent.com/magpie/magpie-api-layer/main/mags/mags.sh -o mags.sh
chmod +x mags.sh

# Set API token
export MAGS_API_TOKEN="your-api-token-here"

Commands

# Simple command
./mags.sh run 'echo Hello'

# With workspace
./mags.sh run -w my-project 'apk add python3'

# Persistent with URL
./mags.sh run -p --url 'python3 -m http.server 8080'

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

# Status/logs
./mags.sh status <job-id>
./mags.sh logs <job-id>
./mags.sh list

Claude Code Skill

Use Mags directly from Claude Code with the /mags skill.

Install

# Global installation
mkdir -p ~/.claude/commands
curl -L https://raw.githubusercontent.com/magpie/magpie-api-layer/main/mags/skill.md \
  -o ~/.claude/commands/mags.md

# Or project-specific
mkdir -p .claude/commands
curl -L https://raw.githubusercontent.com/magpie/magpie-api-layer/main/mags/skill.md \
  -o .claude/commands/mags.md

Configuration

# Set in your shell profile or .env
export MAGS_API_TOKEN="your-token-here"

Usage in Claude Code

# Run a script
/mags run a python script that calculates fibonacci numbers

# Deploy a web app
/mags deploy a simple express server with a /health endpoint

# Install packages in workspace
/mags install nodejs and npm in my-project workspace

Jobs API

The Jobs API orchestrates full Firecracker jobs, templates, and persistent VMs.

Create Job

{
  "name": "nightly-billing-rollup",
  "type": "inline",
  "script": "#!/bin/bash\necho hello",
  "vcpus": 2,
  "memory_mb": 512,
  "environment": {"ENV": "prod"},
  "stateful": false,
  "persist": false,
  "ip_lease": false,
  "proxy_port": 8080
}

Job History

Job Details

Status & Logs

For live logs, append ?follow=true to stream via Server-Sent Events.

curl -N https://api.magpiecloud.com/api/v1/jobs/REQ_ID/logs?follow=true

Persistent VM Helpers

{ "command": "uname -a", "timeout_seconds": 30 }

Job Templates

Jobs SDK (Python)

The official Python SDK is published as magpie-cloud.

Install

pip install magpie-cloud

Initialize

from magpie import Magpie

client = Magpie(api_key="YOUR_API_KEY")

Run a Job

result = client.jobs.run(
    name="hello-world",
    script="echo 'Hello from Magpie'",
    script_type="inline",
    vcpus=2,
    memory_mb=512,
)
status = client.jobs.get_status(result["request_id"])
logs = client.jobs.get_logs(result["request_id"])

Persistent VM + SSH

handle = client.jobs.create_persistent_vm(
    name="dev-shell",
    script="echo ready",
    register_proxy=True,
    proxy_port=8080,
)
print(handle.request_id, handle.ip_address, handle.proxy_url)
ssh_result = client.jobs.ssh(handle.request_id, "uname -a")

Templates

template = client.templates.create(
    name="realtime-ingest",
    script="python app.py",
    script_type="inline",
    vcpus=2,
    memory_mb=1024,
)
run = client.templates.run(template.id)

Creating VMs and SSH

Create full microVMs and connect using generated or provided SSH keys.

Create a MicroVM

{
  "name": "ingest-edge",
  "cpu": 2,
  "memory": 2048,
  "disk": 20,
  "image": "ubuntu-22.04",
  "ssh_public_keys": ["ssh-ed25519 AAAA..."]
}

Fetch SSH Connection Info

# Response includes ssh_command and IPs
{
  "ssh_command": "ssh -i ~/.ssh/vm-abc-key.pem ubuntu@12.34.56.78",
  "ip_address": "12.34.56.78",
  "ipv6_address": "2001:db8::1",
  "key_generated": true
}

Download Generated Private Key (if server generated one)

Save the key to ~/.ssh/vm-<id>-key.pem and run the provided ssh command.

Lifecycle

• POST /api/v1/microvms/:id/start
• POST /api/v1/microvms/:id/stop
• POST /api/v1/microvms/:id/restart