@magpiecloud/mags 1.5.1 → 1.6.1

package/API.md

@@ -0,0 +1,381 @@
+# Mags API Reference
+
+Base URL: `https://api.magpiecloud.com`
+
+All endpoints require authentication via `Authorization: Bearer <token>` header.
+
+---
+
+## Workflow: Base Image + Ephemeral Workers
+
+```
+1. Create a workspace, install dependencies, save it
+   POST /api/v1/mags-jobs  (workspace_id: "my-base", script: "apk add python3 nodejs ...")
+
+2. Use that workspace as a read-only base for ephemeral workers
+   POST /api/v1/mags-jobs  (base_workspace_id: "my-base", script: "npm test")
+   POST /api/v1/mags-jobs  (base_workspace_id: "my-base", script: "python3 run.py")
+   ...workers run in parallel, base is never modified
+```
+
+---
+
+## Endpoints
+
+### Submit Job
+
+```
+POST /api/v1/mags-jobs
+```
+
+Creates a VM, runs a script, and returns. The VM boots in ~300ms from a pool.
+
+**Request:**
+
+```json
+{
+  "script": "echo hello world",
+  "type": "inline",
+  "workspace_id": "my-project",
+  "base_workspace_id": "my-base",
+  "persistent": false,
+  "startup_command": "python3 -m http.server 8080",
+  "environment": { "FOO": "bar" },
+  "file_ids": ["file-uuid-1", "file-uuid-2"]
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `script` | string | yes | Shell script to execute inside the VM |
+| `type` | string | yes | Always `"inline"` |
+| `workspace_id` | string | no | Persistent workspace name. Filesystem changes (apt install, files, configs) are synced to S3 and restored on next run. Omit for truly ephemeral (no sync). |
+| `base_workspace_id` | string | no | Mount an existing workspace **read-only** as the starting filesystem. Changes are discarded unless `workspace_id` is also set (fork pattern). |
+| `persistent` | bool | no | If `true`, VM stays alive after script finishes. Use for long-running servers, SSH access, or URL-exposed services. |
+| `startup_command` | string | no | Command to run when a sleeping persistent VM wakes up (on URL access). |
+| `environment` | object | no | Key-value env vars injected into the VM. |
+| `file_ids` | string[] | no | File IDs from the upload endpoint. Files are downloaded into `/root/` before script runs. |
+
+**Response (202):**
+
+```json
+{
+  "request_id": "eab1e214-39c8-4ecc-b941-75551976e0fa",
+  "status": "accepted",
+  "message": "Mags job submitted successfully"
+}
+```
+
+**Workspace modes:**
+
+| `workspace_id` | `base_workspace_id` | Behavior |
+|-----------------|----------------------|----------|
+| omit | omit | Fully ephemeral. No S3 sync. Fastest. |
+| `"my-ws"` | omit | Read+write workspace. Changes persist across runs. |
+| omit | `"my-base"` | Base mounted read-only. Changes discarded after run. |
+| `"fork-1"` | `"my-base"` | Fork: starts from base, saves changes to `fork-1`. |
+
+---
+
+### Get Job Status
+
+```
+GET /api/v1/mags-jobs/:id/status
+```
+
+**Response (200):**
+
+```json
+{
+  "request_id": "eab1e214-...",
+  "status": "running",
+  "vm_id": "a488ceef",
+  "persistent": true,
+  "subdomain": "28dfed70c32e",
+  "url": "https://28dfed70c32e.apps.magpiecloud.com",
+  "sleeping": false,
+  "exit_code": 0,
+  "queue_duration_ms": 2,
+  "acquire_duration_ms": 45,
+  "script_duration_ms": 1200,
+  "started_at": "2026-02-04T22:30:00Z",
+  "completed_at": null
+}
+```
+
+**Status values:** `pending` → `running` → `completed` | `error` | `sleeping`
+
+Poll this endpoint to wait for job completion. For persistent jobs, `running` is the final state (VM stays alive).
+
+---
+
+### Get Job Logs
+
+```
+GET /api/v1/mags-jobs/:id/logs
+```
+
+**Response (200):**
+
+```json
+{
+  "logs": [
+    { "timestamp": "2026-02-04T22:30:01Z", "level": "info", "message": "hello world", "source": "stdout" },
+    { "timestamp": "2026-02-04T22:30:01Z", "level": "error", "message": "warning: ...", "source": "stderr" }
+  ]
+}
+```
+
+Filter by `source`: `"stdout"`, `"stderr"`, or `"system"` (internal events).
+
+---
+
+### List Jobs
+
+```
+GET /api/v1/mags-jobs?page=1&page_size=20
+```
+
+**Response (200):**
+
+```json
+{
+  "jobs": [
+    {
+      "request_id": "eab1e214-...",
+      "job_id": "372525f4-...",
+      "name": "mags-job-1738703400",
+      "status": "completed",
+      "workspace_id": "my-project",
+      "exit_code": 0,
+      "created_at": "2026-02-04T22:30:00Z"
+    }
+  ],
+  "total": 42,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+---
+
+### Enable Access (SSH or HTTP)
+
+```
+POST /api/v1/mags-jobs/:id/access
+```
+
+Enables external access to a running VM. Use `port: 22` for SSH, any other port for HTTP proxy.
+
+**Request:**
+
+```json
+{ "port": 22 }
+```
+
+**Response (200) — SSH (port 22):**
+
+```json
+{
+  "success": true,
+  "message": "SSH proxy enabled",
+  "ssh_host": "api.magpiecloud.com",
+  "ssh_port": 40000,
+  "ssh_private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----\n",
+  "access_type": "ssh_proxy"
+}
+```
+
+Connect with: `ssh -i <key_file> -p <ssh_port> root@<ssh_host>`
+
+**Response (200) — HTTP (other ports):**
+
+```json
+{
+  "success": true,
+  "message": "External access enabled",
+  "ipv6_address": "2a01:4f9:...",
+  "port": 8080,
+  "access_type": "http_proxy"
+}
+```
+
+HTTP services are also available via subdomain: `https://<subdomain>.apps.magpiecloud.com`
+
+---
+
+### Update Job
+
+```
+PATCH /api/v1/mags-jobs/:id
+```
+
+Update a job's startup command (used when waking from sleep).
+
+**Request:**
+
+```json
+{ "startup_command": "python3 -m http.server 8080" }
+```
+
+**Response (200):**
+
+```json
+{ "success": true, "message": "Job updated" }
+```
+
+---
+
+### Upload File
+
+```
+POST /api/v1/mags-files
+Content-Type: multipart/form-data
+```
+
+Upload a file (max 100MB) that can be attached to jobs via `file_ids`.
+
+**Request:** Multipart form with field name `file`.
+
+**Response (201):**
+
+```json
+{
+  "file_id": "a1b2c3d4-...",
+  "file_name": "script.py",
+  "size": 4096
+}
+```
+
+---
+
+## Examples
+
+### 1. Set up a base workspace with dependencies
+
+```bash
+curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "script": "apk add python3 py3-pip nodejs npm && pip install requests flask",
+    "type": "inline",
+    "workspace_id": "python-base"
+  }'
+# Returns request_id — poll /status until completed
+```
+
+### 2. Spawn ephemeral workers from the base
+
+```bash
+# Worker 1 — changes discarded, base untouched
+curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "script": "python3 -c \"import requests; print(requests.get('https://httpbin.org/ip').text)\"",
+    "type": "inline",
+    "base_workspace_id": "python-base"
+  }'
+
+# Worker 2 — runs in parallel, isolated from worker 1
+curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "script": "node -e \"console.log(process.version)\"",
+    "type": "inline",
+    "base_workspace_id": "python-base"
+  }'
+```
+
+### 3. Fork a base into a new workspace
+
+```bash
+curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "script": "pip install pandas && python3 -c \"import pandas; print(pandas.__version__)\"",
+    "type": "inline",
+    "base_workspace_id": "python-base",
+    "workspace_id": "python-data"
+  }'
+# python-data now has everything from python-base + pandas
+```
+
+### 4. Run a persistent server with URL
+
+```bash
+curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "script": "echo \"<h1>Hello</h1>\" > index.html && python3 -m http.server 8080",
+    "type": "inline",
+    "workspace_id": "my-server",
+    "persistent": true,
+    "startup_command": "python3 -m http.server 8080"
+  }'
+# After status=running, enable URL access:
+curl -X POST https://api.magpiecloud.com/api/v1/mags-jobs/$REQUEST_ID/access \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"port": 8080}'
+```
+
+### 5. Execute a command on a running VM via SSH
+
+```bash
+# Enable SSH proxy
+RESP=$(curl -s -X POST https://api.magpiecloud.com/api/v1/mags-jobs/$REQUEST_ID/access \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"port": 22}')
+
+# Extract connection info
+SSH_HOST=$(echo $RESP | jq -r '.ssh_host')
+SSH_PORT=$(echo $RESP | jq -r '.ssh_port')
+echo "$RESP" | jq -r '.ssh_private_key' > /tmp/mags_key && chmod 600 /tmp/mags_key
+
+# Connect
+ssh -i /tmp/mags_key -p $SSH_PORT -o StrictHostKeyChecking=no root@$SSH_HOST "echo hello"
+```
+
+---
+
+## Error Responses
+
+All errors return:
+
+```json
+{ "error": "description of what went wrong" }
+```
+
+| Status | Meaning |
+|--------|---------|
+| 400 | Invalid request (missing fields, bad JSON) |
+| 401 | Missing or invalid auth token |
+| 404 | Job not found |
+| 500 | Server error (includes workspace conflict messages) |
+
+**Workspace conflict (500):**
+
+```json
+{
+  "error": "workspace 'my-ws' is already in use by job eab1e214-... (status: running); use 'mags exec my-ws <command>' to run commands on it, or 'mags ssh my-ws' to connect interactively"
+}
+```
+
+---
+
+## VM Environment
+
+- **OS:** Alpine Linux (lightweight, ~50MB rootfs)
+- **Shell:** `/bin/sh` (ash)
+- **Package manager:** `apk add <package>`
+- **User:** `root`
+- **Working directory:** `/root`
+- **Filesystem:** OverlayFS on top of base rootfs. Workspace changes sync to S3.
+- **Boot time:** ~300ms from pool
+- **Default timeout:** 300 seconds (configurable per job)