Skip to content
BranchesTags

Repository files navigation

⚡ RunBox — High-Performance Isolated Remote Code Execution Engine

Go Version Docker Next.js Redis TailwindCSS

An ultra-secure, multi-tenant remote code execution engine and dark-mode web IDE designed for high-concurrency coding platforms (similar to LeetCode and HackerRank).

Features • System Architecture • Security Sandbox • API Reference • Quickstart

🌟 Key Features

  • 🛡️ Kernel-Level Sandboxing: Linux cgroups (CPU, RAM, PID limits), air-gapped network isolation (NetworkMode: "none"), non-root execution (UID 1000), and dropped Linux capabilities (CapDrop: ALL).
  • ⚡ 6 Major Programming Languages: Hardened Alpine Linux runner containers supporting Python 3.12, JavaScript (Node.js 20), C++ (GCC 13), C (GCC 13), Go 1.22, and Java 21 (OpenJDK).
  • 📬 Distributed Async Job Queue: Redis-backed FIFO message broker with decoupled API gateway and a scalable multi-goroutine worker pool (WORKER_CONCURRENCY=4+).
  • 📥 Multi-File & Stdin Stream Pipeline: Seamless standard input (stdin) sequential stream redirection (< /sandbox/input.txt) packed via in-memory TAR streaming directly into running containers.
  • 📊 24-Hour Rolling Telemetry Engine: Atomic sub-millisecond platform metrics tracking total executions, language market share, average execution latencies, and success/error status breakdowns.
  • 💻 Modern Monaco Web IDE: Single-page dark-mode playground with live compilation status badges, millisecond latency metrics, dynamic language file tabs, font size zoom controls (A- / A+), and one-click copy output.
  • 🐳 One-Command Container Orchestration: Production multi-stage Dockerfiles (~15 MB Alpine binaries) and automated docker-compose.yml stack with integrated healthchecks.

🏗️ System Architecture

                                  ┌───────────────────────────┐
                                  │   Browser / Web Client    │
                                  │ (Next.js 14 + Monaco IDE) │
                                  └─────────────┬─────────────┘
                                                │
                                    POST /api/v1/execute
                                    GET  /api/v1/submissions/:id
                                                │
                                                ▼
                                  ┌───────────────────────────┐
                                  │    Go REST API Gateway    │
                                  │  - 1MB Payload Protection │
                                  │  - UUID Job Generation    │
                                  │  - Sub-millisecond Ack    │
                                  └─────────────┬─────────────┘
                                                │
                                    LPUSH runbox:queue:jobs
                                                │
                                                ▼
                                  ┌───────────────────────────┐
                                  │    Redis In-Memory Bus    │
                                  │  - FIFO Job Queue         │
                                  │  - Job State Hash Storage │
                                  │  - 24h Rolling Telemetry  │
                                  └─────────────┬─────────────┘
                                                │
                                    BRPOP runbox:queue:jobs
                                                │
                                                ▼
                                  ┌───────────────────────────┐
                                  │  Go Concurrent Worker     │
                                  │  (4+ Parallel Goroutines) │
                                  └─────────────┬─────────────┘
                                                │
                                      Docker Engine API
                                  (/var/run/docker.sock)
                                                │
                  ┌─────────────────────────────┼─────────────────────────────┐
                  ▼                             ▼                             ▼
       ┌────────────────────┐        ┌────────────────────┐        ┌────────────────────┐
       │   runbox-python    │        │     runbox-cpp     │        │    runbox-golang   │
       │  (128MB / 1.0 CPU) │        │ (128MB / 1.0 CPU)  │        │ (128MB / 1.0 CPU)  │
       └────────────────────┘        └────────────────────┘        └────────────────────┘

🛡️ Security & Sandbox Isolation

RunBox neutralizes all major arbitrary code execution (RCE) attack vectors:

Attack Vector Simulated Malicious Code Defense Mechanism Sandbox Outcome
💣 Fork Bomb while True: os.fork() Linux Cgroup pids.max = 256 BLOCKED — Process spawn rejected with BlockingIOError: Resource temporarily unavailable.
💾 Memory Leak (OOM) Allocating > 128 MB RAM Linux Cgroup memory.max = 128MB + 0MB Swap KILLED — Linux Kernel OOM Killer sends SIGKILL (Exit Code 137), tagged MEMORY_LIMIT_EXCEEDED.
⏳ Infinite While Loop while True: pass Go Context Watchdog (3.0s Timeout) FORCE TERMINATED — Clean container termination at 3.0s, tagged TIME_LIMIT_EXCEEDED.
📂 Filesystem Escape open('/etc/shadow') Non-Root User (UID 1000) + Read-Only System ACCESS DENIED — Blocked with PermissionError: [Errno 13] Permission denied.
🌐 Outbound Network Scan Socket connection to external IP Docker NetworkMode: "none" AIR-GAPPED — Container has zero network interfaces. Outbound packets dropped immediately.

📊 Supported Language Matrix

Language Runner Image Base Image Compiler / Runtime Default File
Python runbox-python:latest Alpine 3.20 Python 3.12 (Unbuffered -u) main.py
JavaScript runbox-javascript:latest Node 20 Alpine Node.js v20.x index.js
C++ runbox-cpp:latest Alpine 3.20 GCC 13.x (g++ -O2 -Wall) main.cpp
C runbox-cpp:latest Alpine 3.20 GCC 13.x (gcc -O2 -Wall) main.c
Go runbox-golang:latest Go 1.22 Alpine Go 1.22 Standard Toolchain main.go
Java runbox-java:latest Alpine 3.20 OpenJDK 21 (javac + JVM -Xmx64m) Main.java

🔌 API Reference

1. Submit Code for Execution

POST /api/v1/execute
Content-Type: application/json

Request Body:

{
  "language": "python",
  "code": "name = input()\nprint(f'Hello, {name}!')",
  "stdin": "Ibrahim"
}

Response (202 Accepted in < 2ms):

{
  "job_id": "843e0171-dd9a-4058-b708-4f965104e600",
  "status": "QUEUED",
  "poll_url": "/api/v1/submissions/843e0171-dd9a-4058-b708-4f965104e600"
}

2. Poll Execution Results

GET /api/v1/submissions/{id}

Response (200 OK):

{
  "id": "843e0171-dd9a-4058-b708-4f965104e600",
  "status": "COMPLETED",
  "result": {
    "status": "SUCCESS",
    "stdout": "Hello, Ibrahim!\n",
    "stderr": "",
    "exit_code": 0,
    "execution_time_ms": 283,
    "memory_used_kb": 0
  },
  "created_at": "2026-08-29T13:45:37Z",
  "finished_at": "2026-08-29T13:45:38Z"
}

3. Get 24-Hour Rolling Telemetry

GET /api/v1/analytics

Response (200 OK):

{
  "period": "Last 24 Hours (Live Redis Telemetry)",
  "total_executions": 36,
  "status_breakdown": {
    "SUCCESS": "23",
    "COMPILATION_ERROR": "8",
    "TIME_LIMIT_EXCEEDED": "3",
    "MEMORY_LIMIT_EXCEEDED": "1",
    "RUNTIME_ERROR": "1"
  },
  "languages": {
    "python": { "count": 11, "percentage": "30.6%", "avg_time_ms": 1653 },
    "javascript": { "count": 5, "percentage": "13.9%", "avg_time_ms": 539 },
    "cpp": { "count": 5, "percentage": "13.9%", "avg_time_ms": 1214 },
    "golang": { "count": 5, "percentage": "13.9%", "avg_time_ms": 1584 }
  }
}

🚀 1-Command Quickstart

Prerequisites

Step 1: Clone Repository

git clone https://github.com/itsIbrahim03/RunBox.git
cd RunBox

Step 2: Launch Production Backend Stack

docker compose up -d

Starts runbox-redis (:6379), runbox-api (:8080), and runbox-worker (4 parallel workers).

Step 3: Launch Web Frontend

cd web
npm install
npm run dev

Open http://localhost:3000 in your browser and start coding!

📁 Project Directory Structure

RunBox/
├── cmd/
│   ├── api/             # REST Gateway with CORS, validation, and JSON endpoints
│   ├── worker/          # Concurrent Goroutine Worker Pool with Redis consumer
│   └── runbox-cli/      # Multi-language test verification CLI
├── internal/
│   ├── queue/           # Redis connection, LPUSH/BRPOP queue, 24h telemetry hash
│   └── sandbox/         # Docker client, cgroups, memory TAR stream, watchdog
├── runners/             # Hardened Alpine runner Dockerfiles
│   ├── python/          # Python 3.12 Alpine
│   ├── javascript/      # Node 20 Alpine
│   ├── cpp/             # GCC 13 Alpine (C & C++)
│   ├── golang/          # Go 1.22 Alpine
│   └── java/            # OpenJDK 21 Alpine
├── web/                 # Next.js 14 Single-Page Monaco Playground
│   ├── src/app/         # Dark-mode UI with live telemetry, dynamic tabs, font zoom
│   └── package.json
├── Dockerfile.api       # Multi-stage production API image (~15 MB)
├── Dockerfile.worker    # Multi-stage production Worker image (~15 MB)
├── docker-compose.yml   # Master multi-container orchestrator
└── README.md

About

High-performance, multi-tenant Remote Code Execution (RCE) engine and dark-mode Monaco IDE with Linux cgroup sandboxing, Redis distributed queue, and sub-second execution across 6 languages.

Topics

cgroupscode-execution-enginedistributed-systemsdockergolangleetcode-clonelinux-containersmicroservicemonaco-editornextjsonline-judgeredissandboxsecuritytailwindcss

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages