marlos 1.0.5
Autonomous Distributed Computing Operating System with Reinforcement Learning
Requires Python: >=3.11
Keywords: distributed-computing, reinforcement-learning, p2p, autonomous-systems, blockchain, economics

<h1 align="center">MarlOS: A Multi-Agent Reinforcement Learning Operating System</h1>
<p align="center">
</p>

[![Built at Hack36](https://raw.githubusercontent.com/nihal2908/Hack-36-Readme-Template/main/BUILT-AT-Hack36-9-Secure.png)](https://raw.githubusercontent.com/nihal2908/Hack-36-Readme-Template/main/BUILT-AT-Hack36-9-Secure.png)


## Introduction:
**MarlOS** is a **decentralized, fairness-aware distributed computing operating system** that removes the need for centralized orchestrators like Kubernetes or cloud controllers.  
It operates as a **peer-to-peer (P2P)** network using **ZeroMQ (PUB/SUB)** for communication — where every node is equal, autonomous, and cryptographically authenticated via **Ed25519 signatures**.  

MarlOS introduces a **Fairness-Aware Economic Layer**, using adaptive tokenomics (**MarlCredits**) to ensure equitable participation and prevent resource monopolies.  
Through **multi-agent reinforcement learning**, nodes learn cooperative bidding, resource sharing, and self-healing behaviors — creating a **self-regulating computational swarm** without any central authority.

---

## 🎥 Demo Video:
<a href="https://youtu.be/EGv7Z3kXv30?si=_A561FUwf21EmcIb" target="_blank">
  <img src="https://img.shields.io/badge/YouTube-Demo%20Video-red?style=for-the-badge&logo=youtube" alt="Demo Video">
</a>

**Watch the full demo:** [https://youtu.be/EGv7Z3kXv30](https://youtu.be/EGv7Z3kXv30?si=_A561FUwf21EmcIb)

---

## 📊 Presentation:
<a href="https://www.canva.com/design/DAG4KrB5-D0/W-mglhEG6lW3rpzn7PW4BA/view" target="_blank">
  <img src="https://img.shields.io/badge/Canva-Presentation-00C4CC?style=for-the-badge&logo=canva" alt="Presentation">
</a>

**View the slides:** [Canva Presentation](https://www.canva.com/design/DAG4KrB5-D0/W-mglhEG6lW3rpzn7PW4BA/view)

---

## Table of Contents:
1. [Core Architecture & Network](#core-architecture--network)
2. [Reinforcement Learning Engine](#reinforcement-learning-engine)
3. [Economic Fairness Engine](#economic-fairness-engine)
4. [Job Execution & Management](#job-execution--management)
5. [Getting Started](#getting-started)
6. [Technology Stack](#technology-stack)
7. [Contributors](#contributors)

---

## Core Architecture & Network
- **Fully Decentralized:** No master node; peer discovery via ZeroMQ gossip protocol.  
- **Cryptographic Security:** Every P2P message is signed using Ed25519 with timestamps and nonces to prevent replay attacks.  
- **Self-Healing:** Detects node failure and automatically migrates active jobs to backup nodes.  
- **Quorum Consensus:** Maintains consistency and prevents double-claims even under network partitions.

---

## Reinforcement Learning Engine
- **RL-Based Bidding:** Each node runs a PPO agent that decides to **Bid**, **Forward**, or **Defer** tasks based on a 25-dimensional state vector representing local and global conditions.  
- **Speculative Execution:** A secondary predictive agent anticipates likely future jobs and executes them in advance for zero-latency responses.

---

## Economic Fairness Engine
- **Token Economy (MarlCredits):** Nodes stake, earn, and spend credits in decentralized job auctions.  
- **Trust & Reputation System:** Each node maintains a 0.0–1.0 trust score; low-trust peers are quarantined automatically.  
- **Progressive Taxation + UBI:** Wealth redistribution mechanisms promote network balance and inclusivity.  
- **Diversity Quotas & Starvation Prevention:** Dynamic bid modifiers ensure all nodes get fair access to jobs.  
- **Proof-of-Work Verification:** Random audits validate completed jobs to deter Byzantine behavior.

---

## Job Execution & Management
- **Extensible Job Runners:** Supports shell, Docker, and cybersecurity tasks (`malware_scan`, `vuln_scan`, `hash_crack`, `forensics`).  
- **Dynamic Complexity Scoring:** Rewards scale (1×–5×) with task difficulty.  
- **Deterministic Coordinator Election:** Transparent synchronization for distributed job allocation.  
- **Self-Healing Runtime:** When a node fails, jobs migrate seamlessly to a verified backup peer.

---

## Getting Started

### ⚡ Quickest: Install with pip (Recommended)

Install MarlOS globally with pip and use the `marl` command:

```bash
pip install git+https://github.com/ayush-jadaun/MarlOS.git
```

Then run:
```bash
marl  # Interactive menu
```

Or use directly:
```bash
marl start           # Start MarlOS
marl execute "cmd"   # Run a command
marl status          # Check status
marl --help          # See all commands
```

**See complete guide:** [pip Installation Guide](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/PIP_INSTALL.md) 📦

> **⚠️ "marl: command not found" error?**
> This happens when Python's Scripts directory isn't in your PATH. See our **[Complete PATH Setup Guide](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/PATH_SETUP_QUICK_REFERENCE.md)** for detailed OS-specific instructions.
>
> **Quick fixes:**
> - **Windows**: Run our [automated installer](https://github.com/ayush-jadaun/MarlOS/blob/main/scripts/install_windows.ps1) or add to PATH manually
> - **Linux/Mac**: Add `export PATH="$HOME/.local/bin:$PATH"` to `~/.bashrc` or `~/.zshrc`
> - **Or use**: `python -m cli.main` (works without PATH changes)
> - **Best solution**: Install with `pipx` instead of `pip` - it handles PATH automatically!

### 🎁 Installing for Friends?

**Share this easy guide:** [INSTALL_FOR_FRIENDS.md](https://github.com/ayush-jadaun/MarlOS/blob/main/INSTALL_FOR_FRIENDS.md)

**Automated Windows installer** (downloads & sets up PATH automatically):
```powershell
# Download and run the installer
irm https://raw.githubusercontent.com/ayush-jadaun/MarlOS/main/scripts/install_windows.ps1 | iex
```

Or download manually:
```powershell
# PowerShell (recommended)
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/ayush-jadaun/MarlOS/main/scripts/install_windows.ps1" -OutFile "install_marlos.ps1"
powershell -ExecutionPolicy Bypass -File install_marlos.ps1

# Or batch file
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/ayush-jadaun/MarlOS/main/scripts/install_windows.bat" -OutFile "install_marlos.bat"
install_marlos.bat
```

---

### 🚀 One-Line Interactive Installation (Full Setup)

For the easiest setup experience, use our interactive installer that guides you through everything:

```bash
curl -sSL https://raw.githubusercontent.com/ayush-jadaun/MarlOS/main/scripts/install-marlos.sh | bash
```

Or download and run locally:
```bash
wget https://raw.githubusercontent.com/ayush-jadaun/MarlOS/main/scripts/install-marlos.sh
chmod +x install-marlos.sh
./install-marlos.sh
```

**The installer will:**
- ✅ Detect your OS and install dependencies
- ✅ Clone the repository
- ✅ Ask about deployment mode (Docker vs Real Device)
- ✅ Configure network settings interactively
- ✅ Set up firewall rules automatically
- ✅ Create launch scripts for your node
- ✅ Optionally set up systemd service (Linux)
- ✅ Start your node automatically

---

### Quick Start with Docker

For local testing with containerized nodes:
```bash
docker-compose up -d
```
This starts 3 agent nodes and an MQTT broker for demonstration.

---

### Distributed Deployment on Real Devices

To deploy MarlOS across actual laptops, desktops, or servers for true distributed computing:

**🎯 Interactive Installer (Recommended):** [Run installer](#-one-line-interactive-installation-full-setup)
**⚡ 5-Minute Manual Setup:** [Quick Start Guide](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/QUICKSTART.md)
**📖 Complete Guide:** [Distributed Deployment Guide](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/DISTRIBUTED_DEPLOYMENT.md)

**Quick Manual Overview:**
```bash
# On each device:
export NODE_ID="laptop-1"
export BOOTSTRAP_PEERS="tcp://192.168.1.101:5555,tcp://192.168.1.102:5555"
./start-node.sh  # or start-node.bat on Windows
```

The system automatically discovers peers, elects coordinators, and distributes jobs using reinforcement learning and cryptographic security.

---

## Technology Stack:
1. **Python** – Core system logic and RL agent implementation  
2. **ZeroMQ** – Decentralized PUB/SUB messaging network  
3. **PyTorch / Stable Baselines3** – Reinforcement learning framework  
4. **Ed25519** – Digital signature and cryptographic authentication  
5. **Docker** – Job containerization and isolated execution  
6. **SQLite / JSON-Ledger** – Local token economy and trust tracking

---

## Contributors:

**Team Name:** async_await

- [Ayush Jadaun](https://github.com/ayushjadaun)
- [Shreeya Srivastava](https://github.com/shreesriv12)
- [Arnav Raj](https://github.com/arnavraj-7)

---

### Made at:
[![Built at Hack36](https://raw.githubusercontent.com/nihal2908/Hack-36-Readme-Template/main/BUILT-AT-Hack36-9-Secure.png)](https://raw.githubusercontent.com/nihal2908/Hack-36-Readme-Template/main/BUILT-AT-Hack36-9-Secure.png)

---

## Documentation

### Setup & Installation
- **[pip Installation Guide](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/PIP_INSTALL.md)** - Install with pip and use `marl` command
- **[Interactive Installer Guide](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/INSTALL.md)** - Full system setup walkthrough
- **[Quick Start Guide](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/QUICKSTART.md)** - 5-minute manual setup
- **[Commands Reference](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/COMMANDS.md)** - Complete command guide
- **[Distributed Deployment](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/DISTRIBUTED_DEPLOYMENT.md)** - Deploy on real devices
- **[Deployment Verification](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/DEPLOYMENT_VERIFICATION.md)** - Testing your setup
- **[Share Guide](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/SHARE.md)** - Share with your team

### Configuration & Network
- **[Network Modes User Guide](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/USER_GUIDE_NETWORK_MODES.md)** - Choose between Private and Public modes
- **[Configuration Architecture](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/CONFIG_ARCHITECTURE.md)** - Two-tier configuration system design
- **[Configuration Management](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/CONFIG_MANAGEMENT_GUIDE.md)** - Manage node configurations
- **[Full Configuration Reference](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/FULL_CONFIG_USAGE.md)** - Complete configuration guide
- **[Cross-Internet Discovery](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/CROSS_INTERNET_DISCOVERY.md)** - Connect nodes across different networks

### Architecture & Design
- **[Network Design](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/NETWORK_DESIGN.md)** - P2P communication architecture
- **[RL Architecture](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/ARCHITECTURE_RL.md)** - Reinforcement learning details
- **[Token Economy](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/ARCHITECTURE_TOKEN.md)** - Economic system design
- **[Checkpoint Recovery](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/CHECKPOINT_RECOVERY_GUIDE.md)** - Fault tolerance mechanisms
- **[RL Prediction](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/RL_PREDICTION_DESIGN.md)** - Predictive pre-execution system

### Complete Documentation Index
- **[Documentation Index](https://github.com/ayush-jadaun/MarlOS/blob/main/docs/README.md)** - Browse all documentation by topic