# Mags

> Instant sandboxes and runtime environments

Mags is a CLI, SDK, and API for running scripts on isolated microVMs with persistent workspaces, file upload, cron scheduling, and optional URL access.

## Quickstart

Install the CLI:
```
npm install -g @magpiecloud/mags
```

Authenticate:
```
mags login
```

Run your first script:
```
mags run 'echo Hello World'
```

## Core CLI Commands

- `mags login` — Authenticate and save credentials
- `mags logout` — Remove saved credentials
- `mags whoami` — Check auth status
- `mags new <workspace>` — Create a persistent VM workspace
- `mags run <script>` — Execute a script on a microVM
- `mags ssh <workspace>` — Open an SSH session into a workspace
- `mags url <job-id>` — Enable public URL access for a running job
- `mags list` — List recent jobs
- `mags logs <job-id>` — View job logs
- `mags status <job-id>` — Check job status
- `mags stop <job-id>` — Stop a running job

## Run Options

| Flag | Description |
|------|-------------|
| `-w, --workspace <id>` | Persist files with a named workspace |
| `-n, --name <name>` | Job name for easier reference |
| `-p, --persistent` | Keep VM alive after script for URL or SSH |
| `-e, --ephemeral` | No workspace, no S3 sync (fastest). Cannot combine with -w or -p |
| `-f, --file <path>` | Upload a local file into /root/ in the VM (repeatable) |
| `--url` | Enable public URL (requires -p) |
| `--port <port>` | Port to expose (default: 8080) |
| `--startup-command <cmd>` | Command to run when a VM wakes |

## File Upload

Upload local files into the VM before your script runs. Files appear at `/root/<filename>`.

```
# Single file
mags run -f script.py 'python3 script.py'

# Multiple files
mags run -f analyze.py -f data.csv 'python3 analyze.py'

# With workspace persistence
mags run -w my-project -f config.json -f app.js 'cp *.js *.json /root/ && cd /root && npm install'
```

## Cron Scheduling

Schedule recurring jobs with standard cron expressions.

```
# Create a cron job
mags cron add --name "daily-backup" --schedule "0 0 * * *" 'tar czf /root/backup.tar.gz /root/data'

# Create with workspace
mags cron add --name "health-check" --schedule "*/5 * * * *" -w monitors 'curl -sf https://myapp.com/health'

# List cron jobs
mags cron list

# Remove a cron job
mags cron remove <id>

# Enable / disable
mags cron enable <id>
mags cron disable <id>
```

### Cron flags for `add`

| Flag | Description |
|------|-------------|
| `-n, --name` | Cron job name (required) |
| `-s, --schedule` | Cron expression, e.g. "0 */2 * * *" (required) |
| `-w, --workspace` | Workspace ID for persistent storage |
| `-p, --persistent` | Keep VM alive after script |

## Workspaces

Workspaces persist files, installed packages, and configuration between runs. Running processes, in-memory state, and open ports reset between sessions.

## Complex Project Workflow

For multi-file projects, the recommended pattern is: create files locally, upload them, then run.

```
# Step 1: Upload files and install deps in a workspace
mags run -w my-project -f server.js -f package.json \
  'cp *.js *.json /root/ && cd /root && npm install'

# Step 2: Test run
mags run -w my-project 'cd /root && node server.js'

# Step 3: Run with public URL
mags run -w my-project -p --url --port 3000 'cd /root && node server.js'

# Step 4: Schedule recurring run with cron
mags cron add --name "my-server" --schedule "0 */6 * * *" -w my-project \
  'cd /root && node server.js'
```

## Ephemeral Mode

For the fastest runs with no workspace or S3 sync overhead:
```
mags run -e 'uname -a && df -h'
```

## API

Base URL: `https://api.magpiecloud.com/api/v1`

### Authentication

Use a Bearer token in the Authorization header:
```
Authorization: Bearer <your-api-token>
```

Generate tokens at https://mags.run/tokens or via `mags login`.

### Job Endpoints

- `POST /mags-jobs` — Submit a job (supports `file_ids` array for uploaded files)
- `GET /mags-jobs` — List jobs
- `GET /mags-jobs/{id}/status` — Get job status
- `GET /mags-jobs/{id}/logs` — Get job logs
- `POST /mags-jobs/{id}/access` — Enable URL or SSH access
- `PATCH /mags-jobs/{id}` — Update startup command

### File Endpoints

- `POST /mags-files` — Upload file(s) via multipart/form-data (max 100MB)

### Cron Endpoints

- `POST /mags-cron` — Create a cron job
- `GET /mags-cron` — List cron jobs
- `GET /mags-cron/{id}` — Get a specific cron job
- `PATCH /mags-cron/{id}` — Update a cron job
- `DELETE /mags-cron/{id}` — Delete a cron job

### Submit a Job

```
curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
  -H "Authorization: Bearer $MAGS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "echo Hello World",
    "type": "inline",
    "workspace_id": "myproject",
    "persistent": true
  }'
```

## Node.js SDK

```
npm install @magpiecloud/mags
```

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

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

// Run a script
const result = await mags.runAndWait('echo Hello World');
console.log(result.logs);

// Upload files
const fileIds = await mags.uploadFiles(['script.py', 'data.csv']);
const result = await mags.run('python3 script.py', { fileIds });

// Cron jobs
await mags.cronCreate({
  name: 'daily-backup',
  cronExpression: '0 0 * * *',
  script: 'tar czf backup.tar.gz /data',
  workspaceId: 'my-workspace'
});
const { cron_jobs } = await mags.cronList();
await mags.cronDelete(id);
```

## Claude Code Integration

Install the Mags skill for Claude Code:
```
mags setup-claude
```

Then use `/mags <description>` in Claude Code to run scripts in microVMs.

## VM Environment

- Alpine Linux base image
- Hostname: `mags-vm`
- Persistent home: `/root` (synced to S3 with workspaces)
- JuiceFS mount: `/jfs`
- Package manager: `apk`
- Pre-installed: curl, wget, git, python3, node, vim, nano

## Cookbook

Ready-to-run recipes at https://mags.run/cookbook including:
- Quick script runs
- Persistent Python/Node workspaces
- Exposing web servers with URLs
- HN Marketing Digest cron job

## Links

- Website: https://mags.run
- Dashboard: https://mags.run/dashboard
- API Tokens: https://mags.run/tokens
- API Reference: https://mags.run/api
- Cookbook: https://mags.run/cookbook
- Claude Skill: https://mags.run/claude-skill
- Documentation: https://mags.run/#cli
