# Mags Quickstart Guide

Mags lets you run code in ephemeral VMs with persistent filesystems. Your files, packages, and configs persist across runs - but processes don't.

## Getting Access

### 1. Get an API Token

Contact your admin or generate a token from the Magpie dashboard:
```
https://magpiecloud.com/dashboard/tokens
```

### 2. Set Environment Variable

```bash
export MAGS_API_TOKEN="your-api-token-here"
```

Add to your shell profile (`~/.bashrc`, `~/.zshrc`) to persist:
```bash
echo 'export MAGS_API_TOKEN="your-api-token-here"' >> ~/.zshrc
```

## Installing the CLI

### Option 1: Download Binary

```bash
# 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/
```

### Option 2: Build from Source

```bash
git clone https://github.com/magpie/magpie-api-layer.git
cd magpie-api-layer
go build -o mags ./cmd/mags/
sudo mv mags /usr/local/bin/
```

### Verify Installation

```bash
mags --help
```

## Quick Examples

### Run a Simple Command

```bash
mags run "echo hello world"
```

### Use a Persistent Workspace

```bash
# First run - install Node.js (persists!)
mags run -w my-project "apk add nodejs npm"

# Second run - Node.js is already there
mags run -w my-project "node --version"
```

### Deploy a Web Server with Public URL

```bash
# Deploy with --url flag to get a public URL
mags run -w webapp -p --url "python3 -m http.server 8080"
# Output: https://abc123.apps.magpiecloud.com

# With startup command (runs when VM wakes from sleep)
mags run -w webapp -p --url --startup-command "npm start" "npm install && npm start"
```

### SSH into a VM

```bash
mags ssh my-project
# Now you're in an interactive shell
# All changes persist to 'my-project' workspace
```

### List Recent Jobs

```bash
mags list
```

## Workspaces

A **workspace** is a persistent filesystem stored in S3. Everything you do in a workspace persists:

| Persists | Does NOT Persist |
|----------|------------------|
| Files & directories | Running processes |
| Installed packages | In-memory state |
| Config files | Network connections |
| Environment customizations | Open ports |

### Workspace Naming

```bash
# Good workspace names
mags run -w my-project "..."
mags run -w user-123-dev "..."
mags run -w webapp-prod "..."

# Workspace names should be:
# - Lowercase alphanumeric with hyphens
# - Unique per user/project
# - Descriptive
```

## Command Reference

| Command | Description | Example |
|---------|-------------|---------|
| `mags run` | Run a script | `mags run "npm test"` |
| `mags run -w NAME` | Run with workspace | `mags run -w proj "npm test"` |
| `mags run -p --url` | Run with public URL | `mags run -w app -p --url "python3 -m http.server 8080"` |
| `mags exec` | Quick command in workspace | `mags exec proj "ls -la"` |
| `mags ssh` | Interactive SSH | `mags ssh proj` |
| `mags url ID` | Enable URL for job | `mags url abc123 --port 3000` |
| `mags list` | List jobs | `mags list -n 20` |
| `mags logs ID` | View job logs | `mags logs abc123` |
| `mags status ID` | Job status | `mags status abc123` |

## CLI Flags

| Flag | Description | Default |
|------|-------------|---------|
| `-w, --workspace` | Workspace ID for persistent storage | auto-generated |
| `-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 |
| `-e, --ephemeral` | No S3 sync (faster, truly ephemeral) | false |
| `-t, --timeout` | Timeout in seconds | 300 |

## Common Workflows

### Web Development

```bash
# Set up project with public URL
mags run -w webapp -p --url "apk add nodejs npm && npm init -y && npm install express"

# Your app is now at https://xyz123.apps.magpiecloud.com

# Update code and restart
mags run -w webapp -p --url "npm start"
```

### Python Development

```bash
# Set up Python environment
mags run -w pyproject "apk add python3 py3-pip"

# Install packages (persists!)
mags run -w pyproject "pip install flask requests"

# Run script
mags run -w pyproject "python app.py"

# Deploy with URL
mags run -w pyproject -p --url "flask run --host=0.0.0.0 --port=8080"
```

### CI/CD Jobs

```bash
# Run tests with timeout
mags run -w myapp -t 600 "npm ci && npm test"

# Build project
mags run -w myapp -t 600 "npm run build"

# Check results
mags logs <job-id>
```

### Deploy a Persistent Web App

```bash
# Deploy with auto-wake (VM sleeps when idle, wakes on request)
mags run -w myapp -p --url --startup-command "npm start" "npm install && npm start"

# Get a URL like: https://abc123.apps.magpiecloud.com
# The app wakes automatically when someone visits the URL!
```

## Timeouts

| Command | Default | Max | Flag |
|---------|---------|-----|------|
| `run` | 5 min | configurable | `-t 600` |
| `exec` | 1 min | configurable | `-t 120` |
| `ssh` | 1 hour | 1 hour | - |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `MAGS_API_TOKEN` | API token (required) |
| `MAGS_API_URL` | Custom API URL (optional) |

## API Access

You can also use the REST API directly:

```bash
# 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",
    "type": "inline",
    "workspace_id": "my-workspace",
    "persistent": true
  }'

# Check status
curl https://api.magpiecloud.com/api/v1/mags-jobs/{job-id}/status \
  -H "Authorization: Bearer $MAGS_API_TOKEN"

# Get logs
curl https://api.magpiecloud.com/api/v1/mags-jobs/{job-id}/logs \
  -H "Authorization: Bearer $MAGS_API_TOKEN"

# Enable URL access
curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs/{job-id}/access \
  -H "Authorization: Bearer $MAGS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'
```

## Troubleshooting

### "API token required"
```bash
export MAGS_API_TOKEN="your-token"
```

### "invalid or expired token"
Get a new token from the dashboard.

### Job timeout
Increase timeout: `mags run -t 600 -w proj "long-command"`

### Workspace not persisting
Ensure you use the same `-w` name across runs.

### URL not working
Make sure you used `--url` flag: `mags run -w app -p --url "..."`

Or enable it after: `mags url <job-id>`

## Getting Help

```bash
mags --help
mags run --help
mags url --help
```

For issues: https://github.com/magpie/magpie-api-layer/issues
