Overview

Mags gives AI agents and developers secure, isolated sandboxes (microVMs) that boot in <100ms. Workspaces persist automatically to the cloud. Run code, schedule jobs, and let agents work safely.

Mags is available via four interfaces, so you can pick whatever fits your workflow:

• CLI — quick tasks, scripting, and interactive SSH sessions
• Python SDK — integrate sandboxes into Python agents and pipelines
• Node.js SDK — integrate sandboxes into JavaScript/TypeScript projects
• REST API — full programmatic control from any language (see API Reference)

Every sandbox is a real microVM with its own kernel, filesystem, and network stack — not a container. This means full isolation with no risk of breakout, making Mags ideal for running untrusted code from AI agents.

Quickstart

Get up and running in under 60 seconds.

1. Install the CLI

npm install -g @magpiecloud/mags

2. Authenticate

mags login

This opens your browser for a one-time authentication flow. Once complete, your session is saved locally.

3. Run your first sandbox

mags run 'echo Hello World'

That's it. Mags spins up an isolated microVM, executes your command, streams the output, and tears down the sandbox. The entire cycle takes under a second for simple commands.

Authentication

Mags supports two authentication methods:

Browser login (interactive)

Run mags login to open a browser-based login flow. This is the recommended approach for local development and CLI usage. Your session token is stored securely on disk.

API token (programmatic)

For CI/CD pipelines, servers, and SDK usage, generate an API token from the Dashboard and set it as an environment variable:

export MAGS_TOKEN=your-token

Both the Python and Node.js SDKs will automatically pick up the MAGS_TOKEN environment variable. You can also pass it explicitly when initializing the client.

Running Scripts

The mags run command is the primary way to execute code in a sandbox. It accepts inline commands, script files, and a wide range of flags for customizing behavior.

Inline script

mags run 'echo Hello World'

Script file

mags run script.sh

Named workspace

Assign a name to the workspace so you can reconnect to it later:

mags run -w name 'command'

Persistent workspace

Add -p to sync the workspace to the cloud so it survives restarts:

mags run -p 'command'

With file upload

Upload local files into the sandbox before execution:

mags run -f file.txt 'command'

Sandboxes

Manage sandbox lifecycle directly from the CLI.

Create a sandbox

mags new name

SSH into a sandbox

mags ssh name

Stop a sandbox

mags stop name

List all sandboxes

mags list

View logs

mags logs name

Management

Commands for managing workspaces, URLs, and scheduled jobs.

Workspaces

# List all workspaces
mags workspace list

# Delete a workspace
mags workspace delete name

Public URLs

# Enable a public URL for a sandbox
mags url enable name

# Set a custom alias
mags url alias name alias

Cron jobs

# Create a cron job (runs every 5 minutes)
mags cron create '*/5 * * * *' 'command'

Flags

Complete reference for all mags run flags.

Workspaces

Workspaces define how your sandbox's filesystem is managed. Mags supports three distinct modes, each optimized for different use cases.

Local (default)

The default mode. The workspace lives on the host machine's local disk. It's the fastest option because there is no cloud sync overhead. When the sandbox stops, the local workspace is cleared.

# Local workspace — fast, ephemeral
mags run 'pip install pandas && python analyze.py'

Persistent (-p)

Persistent workspaces sync to S3 automatically. When a sandbox restarts, Mags restores the workspace from the cloud snapshot, so you pick up exactly where you left off. Ideal for long-running projects, dev environments, and anything you want to keep.

# Persistent workspace — survives restarts
mags run -w myproject -p 'npm install && npm start'

Base Image (--base-image)

A base image workspace is a read-only template. You set it up once with all your dependencies, then new sandboxes inherit from it. Workers get a copy-on-write overlay so they can make changes without affecting the base. Great for standardized environments where many sandboxes need the same starting state.

# Create a base image
mags run -w python-ml --base-image 'pip install numpy pandas scikit-learn torch'

# New sandboxes inherit the base
mags run -w experiment-1 --from python-ml 'python train.py'

Always-On Servers

By default, sandboxes shut down after the script completes. With the --always-on flag, the sandbox stays running indefinitely — perfect for web servers, background workers, and APIs.

• Auto-recovery: If the process crashes, Mags automatically restarts it.
• Sleep and wake: After a configurable idle period, the sandbox sleeps to save resources. It wakes up automatically on the next incoming request.
• Persistent by default: Always-on sandboxes use persistent workspaces, so your data is safe even across host restarts.

mags run -w api-server --always-on --url 'node server.js'

Public URLs

Expose any port in your sandbox to the internet with a single flag. Mags provisions an HTTPS URL with automatic TLS termination.

# Enable a public URL
mags url enable name

# Set a custom alias for a friendlier URL
mags url alias name my-app

You can also enable public URLs at creation time with the --url flag on mags run. URLs follow the pattern https://<name>.mags.run, or https://<alias>.mags.run if you set an alias.

Cron Jobs

Schedule recurring tasks using standard 5-field cron expressions. Mags spins up a sandbox at the scheduled time, runs your command, and tears it down.

# Create — run every 5 minutes
mags cron create '*/5 * * * *' 'python scrape.py'

# List all cron jobs
mags cron list

# Delete a cron job
mags cron delete job-id

File Upload

Upload local files into the sandbox before your script runs. Use the -f flag one or more times to include files. Files are placed in the sandbox's working directory.

# Upload multiple files
mags run -f file1.txt -f file2.csv 'python process.py'

# Combine with persistent workspace
mags run -w data-pipeline -p -f dataset.parquet 'python etl.py'

Python SDK — Installation

Install the Mags Python SDK from PyPI:

pip install mags

The SDK requires Python 3.8 or later. Authentication is handled automatically via the MAGS_TOKEN environment variable or a prior mags login session.

Python SDK — Methods

The Mags client exposes the following methods:

Python SDK — Options

The client.run() method accepts the following keyword arguments:

Python SDK — Examples

Basic execution

from mags import Mags

client = Mags()

# Run a simple command
job = client.run("echo hello")
print(job.logs)

Persistent workspace with public URL

from mags import Mags

client = Mags()

job = client.run(
    script="python app.py",
    workspace="myapp",
    persist=True,
    url=True,
    files=["data.csv"]
)
print(job.url)

Job lifecycle

from mags import Mags

client = Mags()

# Start a long-running job
job = client.run(
    script="python train.py",
    workspace="ml-training",
    persist=True
)

# Check status
status = client.status(job.id)
print(status)  # "running"

# Stream logs
logs = client.logs(job.id)
print(logs)

# Stop when done
client.stop(job.id)

Node.js SDK — Installation

Install the Mags Node.js SDK from npm:

npm install @magpiecloud/mags

The SDK requires Node.js 18 or later. Authentication is handled automatically via the MAGS_TOKEN environment variable or a prior mags login session.

Node.js SDK — Methods

The Mags client exposes the following async methods:

Node.js SDK — Options

When passing an options object to mags.run():

Node.js SDK — Examples

Basic execution

import { Mags } from '@magpiecloud/mags';

const mags = new Mags();

// Run a simple command
const job = await mags.run('echo hello');
console.log(job.logs);

Persistent workspace with public URL

import { Mags } from '@magpiecloud/mags';

const mags = new Mags();

const app = await mags.run({
  script: 'npm start',
  workspace: 'myapp',
  persist: true,
  url: true,
  files: ['package.json', 'index.js']
});
console.log(app.url);

Job lifecycle

import { Mags } from '@magpiecloud/mags';

const mags = new Mags();

// Start a long-running job
const job = await mags.run({
  script: 'node worker.js',
  workspace: 'background-worker',
  persist: true,
  alwaysOn: true
});

// Check status
const status = await mags.status(job.id);
console.log(status); // "running"

// Stream logs
const logs = await mags.logs(job.id);
console.log(logs);

// Stop when done
await mags.stop(job.id);

API Authentication

All API requests require a Bearer token in the Authorization header. Get your token from the API Tokens dashboard.

Authorization: Bearer YOUR_API_TOKEN

Base URL

All endpoints are relative to:

https://api.magpiecloud.com/api/v1

Jobs Endpoints

Submit, monitor, and control sandbox jobs.

Submit a Job

Create a new sandbox and run a script. The script field is required.

curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "echo Hello World",
    "type": "inline",
    "workspace": "my-app",
    "persist": true
  }'

from mags import Mags
client = Mags()
job = client.run(script="echo Hello", workspace="my-app", persist=True)

const job = await mags.run({
  script: 'echo Hello',
  workspace: 'my-app',
  persist: true,
});

Get Job Status

curl https://api.magpiecloud.com/api/v1/mags-jobs/$JOB_ID \
  -H "Authorization: Bearer $TOKEN"

Get Job Logs

curl https://api.magpiecloud.com/api/v1/mags-jobs/$JOB_ID/logs \
  -H "Authorization: Bearer $TOKEN"

Workspaces Endpoints

URL Aliases Endpoints

Cron Endpoints

Error Codes

Claude Skill Installation

Give Claude Code the ability to execute scripts in isolated microVMs. Install in three steps:

Step 1: Install the CLI

npm install -g @magpiecloud/mags

Step 2: Set up the Claude skill

mags setup-claude

Step 3: Log in

mags login

That's it. Claude can now execute code in isolated sandboxes. Workspaces persist between runs, and you can use SSH or public URLs when needed.

Example Prompts

With the Mags skill installed, just describe what you want in plain English:

• "Create a Python environment with numpy and pandas, then run a script that generates sample data"
• "Set up a Node.js web server, install express, and give me the public URL"
• "Upload my data.csv file, install pandas, and run analysis.py on it"
• "Create a persistent workspace called 'ml-project', install tensorflow, and SSH in"
• "Schedule a cron job that runs every morning to scrape news headlines"
• "Build my Go project in a clean environment and show me the test results"

VM Environment

Every sandbox runs on Alpine Linux with these specs:

Pre-installed tools: python3, pip, node, npm, git, curl, wget, jq, openssh, gcc, make.