M3 Plugin Runner Service

Container lifecycle management service for M3 Forge plugins.

Overview

M3 Plugin Runner is a Python/FastAPI service that manages Docker containers for user-deployed plugins. It provides a “push code, it runs” experience similar to Hugging Face Spaces or Lightning AI.

Key Features

• Multi-App Support: Gradio, Streamlit, FastAPI, static HTML, custom Docker
• Git Integration: Clone and deploy directly from Git repositories
• Zip Upload: Deploy from uploaded zip files
• Dynamic Routing: Traefik integration for automatic subdomain routing
• Container Lifecycle: Create, start, stop, redeploy, delete
• Log Streaming: Access container logs via API
• Health Checks: Monitor runner and Docker daemon health

Architecture

The frontend never talks to the runner directly. Lifecycle operations flow through the Node.js backend, while the rendered webapp is embedded back into the Studio UI via iframe session access.

Communication Flow

1. User creates webapp via m3-forge UI
2. Frontend calls tRPC webapp.create procedure
3. Backend stores metadata in PostgreSQL and calls m3-plugin-runner HTTP API
4. M3 Plugin Runner clones code, builds Docker image, starts container
5. Traefik automatically routes {slug}.apps.marie.local to the container
6. User accesses webapp via subdomain URL

Quick Start

Prerequisites

• Python 3.11+
• Docker with Docker Compose
• Access to Docker socket (for container management)

Development

pnpm runner:install    # Install Python dependencies in virtualenv
pnpm runner:dev        # Run development server with hot reload

make install           # Install dependencies
make dev               # Run dev server

Docker Deployment

pnpm runner:build      # Build Docker image
pnpm runner:up         # Start services (runner + Traefik)
pnpm runner:logs       # View logs
pnpm runner:down       # Stop services

make docker-build
make docker-up
make docker-logs
make docker-down

Studio Runner Registration

Create a pending app runner registration in Studio, copy the one-time token, and start the runner with MARIE_STUDIO_URL plus MARIE_RUNNER_REGISTRATION_TOKEN.

For managed deployments, the runner control URL is generated from deployment metadata:

PUBLIC_BASE_URL and PUBLIC_ROUTE_PREFIX are different. They describe the browser-facing app route, such as http://localhost:8880/apps/my-app. The control URL is only for Studio API to call the runner API.

Configuration

Environment variables (can be set in .env file):

API Reference

Create Webapp

POST /apps
Content-Type: multipart/form-data

Form Fields:

• id (required): Unique identifier (UUID)
• name (required): Display name
• app_type: gradio | streamlit | fastapi | static | docker (default: gradio)
• git_url: Git repository URL (required if no code file)
• git_branch: Git branch (default: main)
• port: Container port (default: 7860)
• env: JSON-encoded environment variables (default: {})
• code: Uploaded zip file (required if no git_url)

Response:

{
  "id": "abc123",
  "name": "My Webapp",
  "status": "running",
  "url": "https://abc123.apps.marie.local"
}

List Webapps

GET /apps

Get Webapp Status

GET /apps/{app_id}

Delete Webapp

DELETE /apps/{app_id}

Start / Stop / Redeploy

POST /apps/{app_id}/start
POST /apps/{app_id}/stop
POST /apps/{app_id}/redeploy

Get Logs

GET /apps/{app_id}/logs?tail=100

Health Check

GET /health

App Types

my-gradio-app/
├── app.py           # Must contain Gradio interface
└── requirements.txt # Optional dependencies

import gradio as gr
 
def greet(name):
    return f"Hello, {name}!"
 
demo = gr.Interface(fn=greet, inputs="text", outputs="text")
demo.launch()

my-streamlit-app/
├── app.py           # Streamlit application
└── requirements.txt # Optional dependencies

my-fastapi-app/
├── app.py           # Must export `app` FastAPI instance
└── requirements.txt # Optional dependencies

from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/")
def read_root():
    return {"Hello": "World"}

my-static-site/
├── index.html       # Entry point
├── styles.css
└── script.js

my-custom-app/
├── Dockerfile       # Required - your custom Dockerfile
├── app.py
└── requirements.txt

Troubleshooting

Container fails to start

1. Check logs: pnpm runner:logs or GET /apps/{id}/logs
2. Verify Docker network exists: docker network ls | grep marie-network
3. Check port conflicts: docker ps to see running containers

Build fails

1. Ensure requirements.txt has valid dependencies
2. Check for syntax errors in app code
3. For custom Dockerfiles, ensure they’re valid

Cannot access webapp URL

1. Verify Traefik is running: docker ps | grep traefik
2. Check DNS/hosts file for *.apps.marie.local
3. Verify container is running: GET /apps/{id}