{"id":29872285,"url":"https://github.com/hectorpulido/pequeroku","last_synced_at":"2026-07-11T11:31:18.262Z","repository":{"id":298157177,"uuid":"999062571","full_name":"HectorPulido/pequeroku","owner":"HectorPulido","description":"A lightweight container management platform empowering community members to spin up isolated QEMU environments for experiments and learning. 🚀","archived":false,"fork":false,"pushed_at":"2026-07-08T22:54:08.000Z","size":51409,"stargazers_count":69,"open_issues_count":0,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-08T23:17:22.322Z","etag":null,"topics":["backend","dev-tools","developer-tools","development-environment","ide","mcp","monaco-editor","paas","python","qemu","remote-management","virtual-machine","xterm-js"],"latest_commit_sha":null,"homepage":"https://pequeroku.hectorpulido.net","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HectorPulido.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"HectorPulido","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-06-09T17:19:37.000Z","updated_at":"2026-07-08T22:54:11.000Z","dependencies_parsed_at":"2025-08-31T20:27:28.556Z","dependency_job_id":"26a7cc0a-760f-41c1-8f62-c4f6224ca936","html_url":"https://github.com/HectorPulido/pequeroku","commit_stats":null,"previous_names":["hectorpulido/pequeroku"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HectorPulido/pequeroku","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HectorPulido%2Fpequeroku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HectorPulido%2Fpequeroku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HectorPulido%2Fpequeroku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HectorPulido%2Fpequeroku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HectorPulido","download_url":"https://codeload.github.com/HectorPulido/pequeroku/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HectorPulido%2Fpequeroku/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35361644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["backend","dev-tools","developer-tools","development-environment","ide","mcp","monaco-editor","paas","python","qemu","remote-management","virtual-machine","xterm-js"],"created_at":"2025-07-30T20:09:41.002Z","updated_at":"2026-07-11T11:31:18.255Z","avatar_url":"https://github.com/HectorPulido.png","language":"Python","funding_links":["https://github.com/sponsors/HectorPulido"],"categories":[],"sub_categories":[],"readme":"# PequeRoku\n\n\u003e Real root-access VMs for you *and* your AI agents: a self-hosted, Replit-style cloud lab in the browser, plus an MCP server and public API that hand the same VMs to any agent — Claude Code, Cursor, or your own.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/HectorPulido/pequeroku/blob/main/LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/github/license/HectorPulido/pequeroku?color=blue\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/HectorPulido/pequeroku/stargazers\"\u003e\u003cimg alt=\"Stars\" src=\"https://img.shields.io/github/stars/HectorPulido/pequeroku?style=flat\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/HectorPulido/pequeroku/issues\"\u003e\u003cimg alt=\"Issues\" src=\"https://img.shields.io/github/issues/HectorPulido/pequeroku\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/HectorPulido/pequeroku/pulls\"\u003e\u003cimg alt=\"PRs Welcome\" src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Self-hosted\" src=\"https://img.shields.io/badge/self--hosted-%E2%9C%94-success\"\u003e\n\u003c/p\u003e\n\n\n## Demo\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/demo.gif\" alt=\"PequeRoku Demo\" width=\"800\"\u003e\u003cbr\u003e\n  \u003cem\u003eOpen a real Linux VM from any device: laptop, tablet, or phone. No setup, no waiting.\u003c/em\u003e\n\u003c/p\u003e\n\n\n## What Is It?\n\nPequeRoku is an open-source, self-hosted alternative to Replit, Codespaces, and Gitpod — and, through its MCP server and public API, to agent sandboxes like E2B and Daytona. Instead of a locked-down container, you get a real virtual machine (QEMU/KVM) with full root, a browser IDE, a built-in [AI agent](./AI.md) that operates the box, and an [MCP server](#drive-it-from-any-agent) that gives any agent you already use the same hands.\n\nIt is always on, with no cold starts, no sandbox, and no per-seat billing. The only limits are the ones your own hardware sets.\n\n\n## Quick Start\n\n```bash\ngit clone https://github.com/HectorPulido/pequeroku.git\ncd pequeroku/source\n./start.sh\n```\n\n`start.sh` is idempotent — re-run it anytime. It creates the `.env` files with random secrets, turns on KVM when `/dev/kvm` exists, and runs `docker compose up`. (Prefer two steps? `./setup.sh \u0026\u0026 docker compose up` is equivalent.)\n\n1. Open `http://localhost/dashboard/`.\n2. Log in and create your first VM.\n3. Start coding, or ask Pequenin to scaffold the project for you.\n\n**Faster VM boots (optional).** The first run boots VMs from a stock Debian cloud image (~50 s to SSH). Bake a golden image once to cut that to ~10 s:\n\n```bash\n./vm_service/scripts/build-golden.sh --force\ndocker compose restart vm_services\n```\n\nSSH keys are generated automatically in the persistent `vm_data` volume, so there is zero key setup. Bringing your own key, or upgrading a checkout that predates `start.sh`? See [UPGRADING.md](./UPGRADING.md). Detailed walkthrough: [Wiki, Getting Started](https://github.com/HectorPulido/pequeroku/wiki/Getting-Started).\n\n\n## Why PequeRoku\n\n* **Real root on a real VM.** Install Docker, run `systemd`, build a kernel. It is a Linux machine (QEMU/KVM), not a container with guardrails.\n* **Always on.** No cold starts: your workspace is ready when you are, and resets to a clean slate when you want one.\n* **An agent that operates the box.** [Pequenin](#meet-pequenin-the-ai-that-operates-your-vm) edits files, runs your tests, starts servers, and verifies them live inside the VM.\n* **A sandbox for *your* agent.** Point Claude Code — or any MCP client — at [`/mcp`](#drive-it-from-any-agent) and it gets real, disposable, root-access VMs to run code in. The blast radius is one VM, not your laptop.\n* **Reachable from anywhere.** The IDE is responsive — laptop, tablet, or phone — with a live preview of whatever your VM serves.\n* **Yours.** Open source (MIT), hackable at every layer, cheap to run on a homelab — with quotas and roles for when you share it with a team.\n\n\u003e I built PequeRoku because I could not find a remote dev platform that was open, root-accessible, always-on, reachable from anywhere, and affordable to run myself. So I made one.\n\n\n## Meet Pequenin, the AI That Operates Your VM\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/AI.gif\" alt=\"Pequenin, the AI agent, working inside a VM\" width=\"800\"\u003e\u003cbr\u003e\n  \u003cem\u003ePequenin does not just suggest. It edits, runs, and verifies inside your VM.\u003c/em\u003e\n\u003c/p\u003e\n\nPequenin lives in the IDE chat and works through real tools:\n\n* **Reads, writes, and edits files** with whitespace-tolerant, surgical edits.\n* **Searches your code** (glob, grep) and **runs shell commands**, including long-running background jobs it can monitor.\n* **Brings services up** and checks that they respond.\n* **Searches the web, spawns subagents** to explore in parallel, and keeps switchable conversations per VM.\n* **OpenAI-compatible**, so you bring your own provider: Groq for speed, OpenAI for quality, or HuggingFace for flexibility.\n\nThe result is not a snippet to copy. Pequenin creates the files, installs the dependencies, starts the server, and confirms it responds. Agent loop, tools, and event protocol: [AI.md](./AI.md).\n\n\n## How It Works\n\nThree services and your VM work together:\n\n```\nBrowser            React IDE (Monaco + Xterm.js)\n   |\n   |  HTTPS / WebSocket\n   v\nweb_service        Django, DRF, Channels\n   |               auth, quotas, templates, Pequenin (the AI brain)\n   |  HTTP\n   v\nvm_service         FastAPI\n   |               VM lifecycle (QEMU), SSH pool, live terminal\n   |  SSH / SFTP\n   v\nYour VM            Debian, full root, /app workspace\n```\n\nThe brain (the AI and agentic loop) runs in `web_service`. The hands (files, exec, terminal) are SSH operations that `vm_service` executes inside the VM. The front end only ever talks to `web_service`.\n\n**Stack:** Django · DRF · Channels · FastAPI · QEMU/KVM · React · Monaco · Xterm.js · Postgres · Redis · Docker\n\nFull architecture and setup: [Wiki](https://github.com/HectorPulido/pequeroku/wiki).\n\n\n## Public API \u0026 MCP server\n\nThe same substrate that powers the IDE is exposed as a versioned, public API —\n*infra as API*. Anything the dashboard does, a script, the SDK, or an AI agent\ncan do too, authenticated with an API key. There are no privileged side paths:\nthe SDK and the MCP server are just clients of `/api/v1`.\n\n### Get a key\n\nIn the dashboard, click **API \u0026 MCP** in the header. It's a self-serve page to\ncreate, list, and revoke API keys, and it shows your MCP connection string and a\nready-to-paste `claude mcp add` command. The secret is shown **once** — only its\nhash is stored. Keys carry scopes — `read` \u003c `exec` \u003c `admin` — so you decide how\nmuch power each script or agent gets (`read` can't run code; `exec` can't\ncreate/destroy). Operators can also mint keys from the CLI:\n\n```bash\ndocker compose exec web python manage.py create_api_key \u003cusername\u003e --scopes read,exec,admin\n```\n\n### REST API (`/api/v1`)\n\nThe spec **is** the documentation: OpenAPI at `/api/v1/schema/`, Swagger UI at\n`/api/v1/schema/swagger-ui/`. Errors use a stable envelope\n`{\"error\": {\"code\", \"message\"}}` with enumerated codes (`quota_exceeded`,\n`machine_not_running`, `forbidden_scope`, `timeout`, …).\n\n| Method \u0026 path | Does |\n|---|---|\n| `POST /api/v1/containers` | Create a container (`{type, name?, ttl_seconds?}`) |\n| `GET /api/v1/containers` | List your containers |\n| `POST /api/v1/containers/{id}/exec` | Run a command → `{stdout, stderr, exit_code}` (or `background` → `process_id`) |\n| `PUT /api/v1/containers/{id}/files` | Batch-write files |\n| `GET /api/v1/containers/{id}/ports` | Listening ports + preview paths |\n| `POST /api/v1/runs` | **One-shot**: create + run + destroy, sync or `async` |\n| `GET /api/v1/runs/{id}` | Poll an async run |\n| `GET /api/v1/types` | Flavors available to you + credit cost |\n\nOne-shot run in a throwaway VM:\n\n```bash\ncurl -X POST http://localhost/api/v1/runs \\\n  -H \"Authorization: Bearer pk_xxx\" -H \"Content-Type: application/json\" \\\n  -d '{\"command\":\"python main.py\",\"files\":[{\"path\":\"main.py\",\"content\":\"print(\\\"hi\\\")\"}]}'\n# → {\"status\":\"succeeded\",\"stdout\":\"hi\\n\",\"exit_code\":0, ...}\n```\n\n### Python SDK\n\n```python\nfrom pequeroku import PequeRoku                # sdk/\npq = PequeRoku(api_key=\"pk_xxx\", base_url=\"http://localhost\")\nprint(pq.run(\"echo hello\").stdout)             # one-shot\nc = pq.create_container(type=\"small\", name=\"blog\")\npq.exec(c[\"id\"], \"python -m http.server 8000\", background=True)\n```\n\nSee [`sdk/README.md`](./sdk/README.md).\n\n### Drive it from any agent\n\nPequeRoku ships an [MCP](https://modelcontextprotocol.io) server over streamable\nHTTP at `/mcp`, so any MCP-capable agent — Claude Code, Claude Desktop, Cursor,\nopencode, or your own — gets **hands** on a real sandbox: create VMs, run code,\nmove files, inspect ports. Connect it with the key from the dashboard's\n**API \u0026 MCP** page:\n\n```bash\nclaude mcp add --transport http pequeroku http://localhost/mcp \\\n  --header \"Authorization: Bearer pk_xxx\"\n```\n\nAny other MCP client, same idea:\n\n```json\n{\n  \"mcpServers\": {\n    \"pequeroku\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer pk_xxx\" }\n    }\n  }\n}\n```\n\nThe agent gets 10 task-shaped tools:\n\n| Tool | Does |\n|---|---|\n| `run_code` | one-shot: boot a throwaway VM, write files, run a command, return output, destroy it |\n| `list_types` | VM flavors your key may use, with specs and credit cost |\n| `list_containers` | your persistent containers with status and flavor |\n| `get_or_create_container` | idempotent named workspace — create it once, come back to it |\n| `container_exec` | run a command in a container; `background=true` returns a `process_id` |\n| `process_status` | status and recent output of a background process |\n| `write_files` | batch-write files into a container |\n| `read_path` | file → contents; directory → listing |\n| `get_preview` | listening ports and preview paths for a running app |\n| `destroy_container` | destroy a container (refuses without `confirm=true`) |\n\nIt also ships 3 ready-made prompts (`run_in_sandbox`, `deploy_web_app`,\n`setup_workspace`) and hands the client a block of instructions on connect, so\nthe agent starts knowing the workflow instead of guessing. The blast radius of\nanything an agent runs is **one isolated VM**, not your machine — that's the\npitch: give your agent a real sandbox with sane defaults (destroy needs\nconfirmation, runs carry a timeout + TTL).\n\n\u003e The MCP server is **platform-only by design**: it never exposes Pequenin or any\n\u003e agent internals. The MCP client already *is* the agent; PequeRoku provides the\n\u003e hands, not the brain. See the boundary in [AI.md](./AI.md). Details:\n\u003e [`source/mcp_service/README.md`](./source/mcp_service/README.md).\n\n\n## How It Compares\n\nPequeRoku competes on two fronts at once: cloud IDEs built for humans, and\nsandboxes built for agents. It is the only one on the row that does both — on\nyour own hardware.\n\n| | **PequeRoku** | Replit / Codespaces / Gitpod | E2B / Daytona (agent sandboxes) |\n|---|:---:|:---:|:---:|\n| Built for | Humans **and** agents | Humans | Agents only |\n| Hosting | Self-hosted, your hardware | Their cloud | Their cloud, usage-metered |\n| Compute | Real VM (QEMU/KVM) | Containers | MicroVMs / containers |\n| Root access | Full root | Limited | Root, but ephemeral |\n| Lifespan | Persistent, always-on | Boot and wait | Short-lived by design |\n| Human IDE | Browser IDE (Monaco + terminal) | Yes | None |\n| AI | Built-in agent, plus MCP/API for yours | Mostly autocomplete or chat | Bring your own agent (SDK) |\n| Source | Open source (MIT) | Proprietary | Open core, SaaS-first |\n| Cost | Your hardware | Per-seat or usage | Per sandbox-second |\n\n\n## Roadmap\n\n* Fast snapshots and one-click rollback\n* Automations: a push triggers tests in the active VM\n* Richer multi-user roles and guardrails\n* A standalone AI microservice and more Pequenin capabilities ([AI.md](./AI.md))\n\n\n## Contribute \u0026 Support\n\nPequeRoku is open to ideas, bug reports, and pull requests — browse the\n[Issues](https://github.com/HectorPulido/pequeroku/issues); I reply to\neverything. If the project resonates with you: star the repo, spread the word,\nand run it in your homelab — then tell me how it went.\n\n\u003e PequeRoku is not the ultimate platform. It is your platform, a small way to take back control.\n\n\n## Links\n\n* [pequeroku.net](https://pequeroku.net)\n* [GitHub Wiki](https://github.com/HectorPulido/pequeroku/wiki)\n* [Medium Article](https://medium.com/p/19bc757c735d)\n* License: MIT. See the [LICENSE](./LICENSE) file for details.\n\n\n\u003cdiv align=\"center\"\u003e\n\u003ch3 align=\"center\"\u003eLet's connect\u003c/h3\u003e\n\u003c/div\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://www.linkedin.com/in/hector-pulido-17547369/\" target=\"blank\"\u003e\n\u003cimg align=\"center\" width=\"30px\" alt=\"Hector's LinkedIn\" src=\"https://www.vectorlogo.zone/logos/linkedin/linkedin-icon.svg\"/\u003e\u003c/a\u003e \u0026nbsp; \u0026nbsp;\n\u003ca href=\"https://twitter.com/Hector_Pulido_\" target=\"blank\"\u003e\n\u003cimg align=\"center\" width=\"30px\" alt=\"Hector's Twitter\" src=\"https://www.vectorlogo.zone/logos/twitter/twitter-official.svg\"/\u003e\u003c/a\u003e \u0026nbsp; \u0026nbsp;\n\u003ca href=\"https://www.twitch.tv/hector_pulido_\" target=\"blank\"\u003e\n\u003cimg align=\"center\" width=\"30px\" alt=\"Hector's Twitch\" src=\"https://www.vectorlogo.zone/logos/twitch/twitch-icon.svg\"/\u003e\u003c/a\u003e \u0026nbsp; \u0026nbsp;\n\u003ca href=\"https://www.youtube.com/channel/UCS_iMeH0P0nsIDPvBaJckOw\" target=\"blank\"\u003e\n\u003cimg align=\"center\" width=\"30px\" alt=\"Hector's Youtube\" src=\"https://www.vectorlogo.zone/logos/youtube/youtube-icon.svg\"/\u003e\u003c/a\u003e \u0026nbsp; \u0026nbsp;\n\u003ca href=\"https://pequesoft.net/\" target=\"blank\"\u003e\n\u003cimg align=\"center\" width=\"30px\" alt=\"Pequesoft website\" src=\"https://github.com/HectorPulido/HectorPulido/blob/master/img/pequesoft-favicon.png?raw=true\"/\u003e\u003c/a\u003e \u0026nbsp; \u0026nbsp;\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhectorpulido%2Fpequeroku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhectorpulido%2Fpequeroku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhectorpulido%2Fpequeroku/lists"}