{"id":29201938,"url":"https://github.com/bdr-pro/lumaris-python","last_synced_at":"2025-07-02T12:36:34.524Z","repository":{"id":293505490,"uuid":"981281796","full_name":"BDR-Pro/Lumaris-Python","owner":"BDR-Pro","description":"Lumaris is a decentralized compute marketplace where buyers send Docker jobs and sellers run them securely","archived":false,"fork":false,"pushed_at":"2025-05-15T16:48:44.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-15T17:48:25.935Z","etag":null,"topics":["distributed-computing","peer-to-peer","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BDR-Pro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-10T18:43:13.000Z","updated_at":"2025-05-15T16:48:47.000Z","dependencies_parsed_at":"2025-05-15T17:48:28.069Z","dependency_job_id":"68c08747-5114-44bf-b140-b941885243e6","html_url":"https://github.com/BDR-Pro/Lumaris-Python","commit_stats":null,"previous_names":["bdr-pro/lumaris-python"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/BDR-Pro/Lumaris-Python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BDR-Pro%2FLumaris-Python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BDR-Pro%2FLumaris-Python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BDR-Pro%2FLumaris-Python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BDR-Pro%2FLumaris-Python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BDR-Pro","download_url":"https://codeload.github.com/BDR-Pro/Lumaris-Python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BDR-Pro%2FLumaris-Python/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263141279,"owners_count":23420046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distributed-computing","peer-to-peer","python"],"created_at":"2025-07-02T12:36:30.562Z","updated_at":"2025-07-02T12:36:34.477Z","avatar_url":"https://github.com/BDR-Pro.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧠 Compute Marketplace\n\nA decentralized platform where **buyers** request computational resources, and **sellers** offer their machines as secure, containerized compute environments accessible over **SSH**. Think of it as turning any machine into a lightweight **EC2 alternative**.\n\n---\n\n## 📦 Features\n\n* 🔌 **Real-time matchmaking** between buyers and online sellers\n* 🐳 **SSH-enabled Docker containers** acting as disposable VMs\n* 📡 **WebSocket-based seller heartbeat + communication**\n* 🔐 **SSH key-based access** for buyers\n* ⏳ **Auto-destruction** of VMs after timeout\n* 🧾 **Job tracking** in a PostgreSQL database (status, history)\n* 🚫 **No Celery** – moved to on-demand container creation\n\n---\n\n## ⚙️ System Overview\n\n```mermaid\nsequenceDiagram\n    participant Buyer\n    participant API (FastAPI)\n    participant Seller Agent\n    participant Docker (on Seller)\n\n    Buyer-\u003e\u003eAPI: Submit job (SSH key + preferences)\n    API-\u003e\u003eSeller Agent: spawn_vm (via WebSocket)\n    Seller Agent-\u003e\u003eDocker: run container with SSH + limits\n    Seller Agent-\u003e\u003eAPI: Respond with container IP, port\n    API-\u003e\u003eBuyer: Return SSH details\n    Note over Buyer, Docker: Buyer connects via SSH and runs code\n    Docker-\u003e\u003eSeller Agent: Auto destroys after timeout\n```\n\n---\n\n## 🛠️ Tech Stack\n\n| Component     | Tech                           |\n| ------------- | ------------------------------ |\n| API Server    | FastAPI + SQLAlchemy (async)   |\n| Database      | PostgreSQL                     |\n| Real-time     | WebSocket (Starlette)          |\n| Compute Unit  | Docker container (SSH-enabled) |\n| Orchestration | Docker Compose                 |\n\n---\n\n## 🧪 API Endpoints\n\n### `POST /jobs/submit`\n\nSubmit a new job.\n\n```json\n{\n  \"ssh_pubkey\": \"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...\",\n  \"preferred_image\": \"ubuntu:ssh-enabled\",\n  \"cpu_quota\": 50000,\n  \"mem_limit\": \"512m\"\n}\n```\n\nReturns:\n\n```json\n{\n  \"job_id\": \"uuid\",\n  \"seller_ip\": \"192.168.x.x\",\n  \"ssh_port\": 2222,\n  \"ssh_user\": \"root\"\n}\n```\n\n---\n\n### `GET /sellers/online`\n\nReturns a list of currently connected sellers.\n\n---\n\n## 🧑‍💻 Seller Setup\n\nRun the seller agent on your own machine:\n\n```bash\npython seller_agent.py --id my-machine-id\n```\n\nThis will:\n\n* Connect to the central API via WebSocket\n* Listen for job requests\n* Spawn Docker containers with SSH access\n* Auto-destroy containers after timeout\n\n---\n\n## 🧰 Docker Compose\n\n```bash\ndocker-compose up --build\n```\n\nRuns:\n\n* `api`: FastAPI app with WebSocket + REST\n* `postgres`: stores jobs \u0026 metadata\n\n---\n\n## 🔐 Security Considerations\n\n* Only whitelisted Docker images are allowed\n* Resource limits enforced (CPU, RAM)\n* SSH only via provided public key\n* VM (container) auto-destroyed after 10 min\n\n---\n\n## 🧭 Future Roadmap\n\n* [ ] Add real VMs using Firecracker or QEMU\n* [ ] Buyer authentication (JWT/session)\n* [ ] Billing based on usage (time/resources)\n* [ ] Prometheus metrics + dashboards\n* [ ] Rate-limiting \u0026 abuse protection\n\n---\n\n## 🤝 Contributing\n\n1. Fork the repo\n2. Add your seller machine\n3. Test real-time container provisioning\n4. Submit PRs for new provider types (e.g., Firecracker)\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdr-pro%2Flumaris-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbdr-pro%2Flumaris-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdr-pro%2Flumaris-python/lists"}