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.

Watch the full demo: https://youtu.be/EGv7Z3kXv30

View the slides: Canva Presentation

1. Core Architecture & Network
2. Reinforcement Learning Engine
3. Economic Fairness Engine
4. Job Execution & Management
5. Getting Started
6. Technology Stack
7. Contributors

• 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.

• 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.

• 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.

• 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.

Install MarlOS globally with pip and use the marl command:

pip install git+https://github.com/ayush-jadaun/MarlOS.git

Then run:

marl  # Interactive menu

Or use directly:

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 📦

For the easiest setup experience, use our interactive installer that guides you through everything:

curl -sSL https://raw.githubusercontent.com/ayush-jadaun/MarlOS/main/scripts/install-marlos.sh | bash

Or download and run locally:

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

For local testing with containerized nodes:

docker-compose up -d

This starts 3 agent nodes and an MQTT broker for demonstration.

To deploy MarlOS across actual laptops, desktops, or servers for true distributed computing:

🎯 Interactive Installer (Recommended): Run installer ⚡ 5-Minute Manual Setup: Quick Start Guide 📖 Complete Guide: Distributed Deployment Guide

Quick Manual Overview:

# 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.

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

Team Name: async_await

• Ayush Jadaun
• Shreeya Srivastava
• Arnav Raj

• pip Installation Guide - Install with pip and use marl command
• Interactive Installer Guide - Full system setup walkthrough
• Quick Start Guide - 5-minute manual setup
• Commands Reference - Complete command guide
• Distributed Deployment - Deploy on real devices
• Deployment Verification - Testing your setup
• Share Guide - Share with your team

• Network Design - P2P communication architecture
• RL Architecture - Reinforcement learning details
• Token Economy - Economic system design
• Checkpoint Recovery - Fault tolerance mechanisms
• RL Prediction - Predictive pre-execution system