# @magpiecloud/mags

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

## Installation

```bash
npm install -g @magpiecloud/mags
```

## Quick Start

### 1. Login to Magpie

```bash
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 persistent VM

```bash
mags new myproject
mags ssh myproject
```

### 3. Or run a script

```bash
mags run 'echo Hello World'
```

## Authentication

### Interactive Login (Recommended)

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

```bash
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):

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

## CLI Commands

```bash
# Create a persistent VM
mags new myproject

# 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:

```bash
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](https://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:

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

Your `/root` directory automatically syncs to S3:
- **Auto-sync**: Every 30 seconds while running
- **On stop**: Full sync before VM terminates
- **On wake**: Previous state restored

## Node.js SDK

```javascript
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
