🚀 Quick Start

Prerequisites:

• Docker and Docker Compose

One-Click Deploy with Docker Compose:

# Download the docker-compose.yml file
curl -L https://raw.githubusercontent.com/sdcb/csharp-runner/refs/heads/master/docker-compose.yml -o docker-compose.yml

# Start the services in detached mode
docker compose up -d

For Windows:

# Download the docker-compose.yml file
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sdcb/csharp-runner/refs/heads/master/docker-compose.yml" -OutFile "docker-compose.yml"

# Start the services in detached mode
docker compose -p csharp-runner up -d

Once deployed, open your browser to http://localhost:5050 to access the web UI.

🔧 Configuration

Docker Compose

The docker-compose.yml file defines the Host and Worker services. You can scale the number of Workers by changing deploy.replicas and configure Worker behavior via environment variables.

services:
  host:
    image: sdcb/csharp-runner-host:latest
    container_name: csharp-runner-host
    ports:
      - "5050:8080"
    restart: unless-stopped

  worker:
    image: sdcb/csharp-runner-worker:latest
    environment:
      - MaxRuns=2           # Max runs per worker (0=unlimited)
      - Register=true       # Auto-register to the Host
      - RegisterHostUrl=http://host:8080
      - WarmUp=false        # Enable warm-up (recommended for standalone deployment)
    restart: unless-stopped
    depends_on:
      - host
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: 0.50
          memory: 256M
          pids: 32
        reservations:
          cpus: 0.25
          memory: 128M

Worker Environment Variables

| Parameter | Description | Default | | ----------------- | ------------------------------------------------------------------ | --------------- | | MaxRuns | The maximum number of times a Worker can execute code (0=unlimited). | 0 | | Register | Whether to auto-register to the Host service. | false | | RegisterHostUrl | The registration URL of the Host service. | http://host | | ExposedUrl | The externally exposed URL of the Worker (optional). | null | | WarmUp | Whether to perform a warm-up on startup. | false | | MaxTimeout | Maximum execution timeout in milliseconds. | 30000 |

📡 API Usage

HTTP API (SSE)

Execute code by sending a POST request to /api/run. The response is streamed as Server-Sent Events (SSE).

Request

POST /api/run
Content-Type: application/json

{
  "code": "Console.WriteLine(\"Hello, World!\"); return 42;",
  "timeout": 30000
}

Response Stream

data: {"kind":"stdout","stdOutput":"Hello, World!"}

data: {"kind":"result","result":42}

data: {"kind":"end","elapsed":150,"stdOutput":"Hello, World!","stdError":""}

MCP Protocol

The MCP endpoint is at /mcp and supports the run_code tool.

Request Example

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "run_code",
    "arguments": {
      "code": "Console.WriteLine(\"Hello from MCP!\");"
    }
  },
  "id": 1
}

🏗️ Architecture & Development Guide

System Architecture

• Host: Provides the public API and web UI. It receives requests, manages a pool of Workers, and handles load balancing.
• Worker: Runs in an isolated sandbox environment, responsible for executing the C# code and returning the result.

Project Structure

src/
├── Sdcb.CSharpRunner.Host/     # Host Service (ASP.NET Core)
├── Sdcb.CSharpRunner.Worker/   # Worker Service (Console App)
└── Sdcb.CSharpRunner.Shared/   # Shared Library (DTOs, etc.)

Local Development

1. Run the Host Service

   cd src/Sdcb.CSharpRunner.Host
   dotnet run
   

2. Run the Worker Service

   cd src/Sdcb.CSharpRunner.Worker
   dotnet run
   

Building Custom Images

# Build the Host image
dotnet publish ./src/Sdcb.CSharpRunner.Host/Sdcb.CSharpRunner.Host.csproj -c Release /t:PublishContainer /p:ContainerRepository=csharp-runner-host

# Build the Worker image
dotnet publish ./src/Sdcb.CSharpRunner.Worker/Sdcb.CSharpRunner.Worker.csproj -c Release /t:PublishContainer /p:ContainerRepository=csharp-runner-worker

🤝 Contributing

Contributions via Issues and Pull Requests are welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⭐ If you find this project helpful, please give it a star!