knowledge-base/Agent_Endpoint_Specifications_Phase1.md

Agent Endpoint Specifications - Phase 1 Release

Last Updated: February 21, 2026
Status: Active Development
Target: Pre-Launch Release

---

📋 Current Agent Capabilities (Baseline)

Already Implemented:

• ✅ Provisioning (dev + game containers)
• ✅ Lifecycle control (/start, /stop, /restart)
• ✅ State reporting (/status, /health)
• ✅ PTY-backed WebSocket console (/console/stream)
• ✅ Minecraft player telemetry (/game/players)
• ✅ Self-update system (/agent/update, /agent/update/status)
• ✅ Version endpoint (/version)
• ✅ Autostart subsystem
• ✅ Periodic update checks (notify/auto/off modes)

---

🎯 New Endpoints for Phase 1

Priority 1: Mod Management (CRITICAL - Blocking Release)

GET /game/mods - Mod Detection

Purpose: List all installed mods with metadata

Response:

{
  "variant": "forge",
  "variant_version": "47.2.0",
  "minecraft_version": "1.20.1",
  "mods": [
    {
      "id": "jei",
      "name": "Just Enough Items",
      "version": "15.2.0.27",
      "filename": "jei-1.20.1-forge-15.2.0.27.jar",
      "description": "Item and recipe viewing mod",
      "required": false,
      "server_side": true,
      "client_side": true,
      "dependencies": ["minecraft@1.20.1", "forge@>=47.0.0"],
      "enabled": true,
      "source": "curated"
    }
  ],
  "total_count": 1,
  "scan_timestamp": "2026-02-21T16:00:00Z"
}

Implementation Requirements:

• Scan /server/mods/ directory for .jar files
• Detect variant by checking for:
  • Forge: /server/config/forge-*.toml or META-INF/mods.toml in JARs
  • Fabric: /server/fabric.mod.json or fabric.mod.json in JARs
  • Paper: /server/plugins/*.jar exists
• Parse metadata from:
  • Forge: META-INF/mods.toml or mcmod.info
  • Fabric: fabric.mod.json
  • Paper: plugin.yml
• Cache results for 5-10 minutes
• Gracefully handle missing/corrupt metadata (fallback to filename)

---

POST /game/mods/install - Install Curated Mod

Purpose: Download and install mod from curated artifact store

Request:

{
  "source": "curated",
  "mod_id": "jei",
  "version": "15.2.0.27",
  "artifact_url": "https://artifacts.zerolaghub.com/mods/forge/jei-15.2.0.27.jar",
  "artifact_hash": "sha256:abc123..."
}

Response:

{
  "success": true,
  "mod": { /* full mod object */ },
  "action": "installed",
  "restart_required": true
}

Implementation Requirements:

• Download from artifact_url to temp directory
• Verify SHA-256 hash matches artifact_hash (CRITICAL - security)
• Only accept URLs from artifacts.zerolaghub.com domain
• Drop privileges to minecraft user before file operations
• Move verified file to /server/mods/{filename}
• Set permissions: owner=minecraft, mode=0644
• Return error if hash mismatch
• Return error if disk full

Security (Non-Negotiable):

// Example secure implementation pattern:
// 1. Download to /tmp/
// 2. Verify hash
// 3. If valid, install as minecraft user
exec.Command("su", "-", "minecraft", "-c", 
    "cp /tmp/verified-mod.jar /server/mods/mod.jar").Run()

---

PATCH /game/mods/:mod_id - Enable/Disable Mod

Purpose: Toggle mod enabled state without removing

Request:

{
  "enabled": false
}

Response:

{
  "success": true,
  "mod": { /* updated mod object */ },
  "action": "disabled",
  "restart_required": true
}

Implementation:

• Disable: Rename .jar → .jar.disabled
• Enable: Rename .jar.disabled → .jar
• Alternative: Move to /server/mods-disabled/ directory

---

DELETE /game/mods/:mod_id - Remove Mod

Purpose: Permanently remove mod

Response:

{
  "success": true,
  "action": "removed",
  "restart_required": true
}

Implementation:

• Delete .jar file from /server/mods/
• Optional: Move to /server/mods-removed/ for rollback capability

---

Priority 2: Process Metrics (HIGH)

GET /metrics/process - Game Process Stats

Purpose: Expose game server process metrics

Response:

{
  "process": {
    "pid": 12345,
    "status": "running",
    "uptime_seconds": 3600,
    "restart_count": 2,
    "last_start": "2026-02-21T15:30:00Z",
    "last_crash": "2026-02-21T12:00:00Z"
  },
  "memory": {
    "rss_bytes": 2147483648,
    "vms_bytes": 4294967296
  }
}

Implementation:

• Read from /proc/{pid}/stat and /proc/{pid}/status
• Track restart count in state file
• Return 404 if process not running (not an error)

---

Priority 3: Agent Health (MEDIUM)

GET /metrics/agent - Agent Health

Purpose: Expose agent operational metrics

Response:

{
  "agent": {
    "version": "v1.2.3",
    "uptime_seconds": 86400,
    "last_update_check": "2026-02-21T14:00:00Z",
    "update_available": false
  },
  "handlers": {
    "console_sessions": 2,
    "active_websockets": 3,
    "provisioning_active": false
  }
}

---

Priority 4: Provisioning Progress (LOW)

GET /metrics/provisioning - Install Progress

Purpose: Real-time provisioning status

Response:

{
  "active": true,
  "current_step": "downloading_artifacts",
  "progress_percent": 45,
  "started_at": "2026-02-21T15:00:00Z",
  "estimated_completion": "2026-02-21T15:10:00Z"
}

---

🔒 Security Requirements (CRITICAL)

Privilege Separation

MUST: All mod file operations run as non-root user

✅ DO: Use su/sudo to drop privileges
❌ DON'T: Write files as root

Hash Verification

MUST: Verify SHA-256 before installing curated mods

Process:
1. Download to temp directory
2. Calculate SHA-256 hash
3. Compare with expected hash
4. If match → install
5. If mismatch → delete and error

URL Whitelisting

MUST: Only download from trusted domains

Allowed:
✅ artifacts.zerolaghub.com

Rejected:
❌ Arbitrary URLs
❌ User-provided URLs
❌ External mod sites (Phase 2)

Container Isolation

Verify:

• Game server runs as non-root user (minecraft/gameserver)
• LXC containers are unprivileged
• Network segmentation active (10.200.0.0/24 VLAN)

---

📦 Suggested Go Package Structure

internal/
├── mods/
│   ├── scanner.go       // Directory scanning
│   ├── forge.go         // Forge metadata parser
│   ├── fabric.go        // Fabric metadata parser
│   ├── paper.go         // Paper plugin parser
│   ├── installer.go     // Download + install logic
│   └── types.go         // Structs and enums
├── metrics/
│   ├── process.go       // Game process metrics
│   ├── agent.go         // Agent health metrics
│   └── provisioning.go  // Provisioning progress
└── handlers/
    ├── game.go          // Mod endpoints
    └── metrics.go       // Metrics endpoints

---

🎯 Implementation Priority

Week 1: Mod Detection + Install

1. GET /game/mods with .jar listing
2. Forge metadata parsing
3. POST /game/mods/install with hash verification
4. Test with 5-10 mods

Week 2: Mod Management

1. PATCH /game/mods/:id (enable/disable)
2. DELETE /game/mods/:id (remove)
3. Fabric metadata parsing
4. Paper plugin parsing

Week 3: Metrics

1. GET /metrics/process
2. GET /metrics/agent
3. Optional: GET /metrics/provisioning

---

🚫 Phase 2 Features (NOT Phase 1)

Defer These:

• ❌ User upload handling (requires malware scanning)
• ❌ Dependency resolution
• ❌ Mod update checking
• ❌ Config file management
• ❌ Rollback/restore functionality
• ❌ Dev container → Game server transfer

---

🧪 Testing Requirements

Mod Detection:

• Empty directory → Empty array
• Forge mods → Correct parsing
• Fabric mods → Correct parsing
• Paper plugins → Correct parsing
• Corrupt metadata → Graceful fallback
• Mixed types → Correct variant detection

Mod Installation:

• Valid hash → Success
• Invalid hash → Error, no install
• Network failure → Error, no corruption
• Disk full → Error
• Invalid URL → Rejection

Security:

• File ops run as minecraft user
• Hash mismatch prevents install
• Malformed requests don't crash agent

---

📊 API Integration

API Will:

• Cache GET /game/mods responses
• Validate user ownership before agent calls
• Handle authentication/authorization
• Aggregate metrics with Prometheus data

Agent Doesn't Handle:

• User authentication (API's job)
• Ownership validation (API's job)
• Billing (API's job)
• Frontend concerns (API's job)

---

✅ Definition of Done

Phase 1 Complete When:

• ✅ All mod variants parse correctly (Forge/Fabric/Paper)
• ✅ Hash verification prevents tampered artifacts
• ✅ Mod enable/disable/remove works
• ✅ Process metrics accurate
• ✅ All file operations use dropped privileges
• ✅ Tests pass for all scenarios
• ✅ Error handling graceful (no crashes)
• ✅ Integration with API tested

---

🔗 Related Documentation

• API Integration: See game.js endpoint specifications
• Security Model: See Drift Prevention Card DEC-008
• Container Architecture: See Infrastructure documentation
• Mod Catalog: See artifact store structure (to be documented)