{"id":28323637,"url":"https://github.com/cynegeirus/winbox-docker","last_synced_at":"2026-01-27T19:29:13.293Z","repository":{"id":294431852,"uuid":"986951728","full_name":"cynegeirus/winbox-docker","owner":"cynegeirus","description":"This project allows you to run a lightweight, isolated Windows virtual machine using QEMU inside a Docker container, with VNC remote desktop access. It is useful for testing, sandboxing, or serving GUI-based environments remotely.","archived":false,"fork":false,"pushed_at":"2025-05-20T11:32:30.000Z","size":283,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-02T01:02:00.270Z","etag":null,"topics":["docker-machine","docker-sandbox","docker-windows","kvm","qemu","qemu-kvm","sandbox"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","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/cynegeirus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2025-05-20T11:07:02.000Z","updated_at":"2025-05-20T11:32:33.000Z","dependencies_parsed_at":"2025-05-20T12:28:48.025Z","dependency_job_id":"a8381a18-ba94-44b2-8978-7f0aa36917a1","html_url":"https://github.com/cynegeirus/winbox-docker","commit_stats":null,"previous_names":["cynegeirus/winbox-docker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cynegeirus/winbox-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cynegeirus%2Fwinbox-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cynegeirus%2Fwinbox-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cynegeirus%2Fwinbox-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cynegeirus%2Fwinbox-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cynegeirus","download_url":"https://codeload.github.com/cynegeirus/winbox-docker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cynegeirus%2Fwinbox-docker/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261582289,"owners_count":23180566,"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":["docker-machine","docker-sandbox","docker-windows","kvm","qemu","qemu-kvm","sandbox"],"created_at":"2025-05-25T16:14:35.418Z","updated_at":"2026-01-27T19:29:08.273Z","avatar_url":"https://github.com/cynegeirus.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🖥️ QEMU Windows VM in Docker with VNC Access\n\nThis project allows you to run a lightweight, isolated Windows virtual machine using **QEMU inside a Docker container**, with **VNC remote desktop access**. It is useful for testing, sandboxing, or serving GUI-based environments remotely.\n\n---\n\n## 📦 Features\n\n- Full Windows VM with VirtIO drivers\n- QEMU-based virtualization\n- VNC access over configurable ports\n- Parametric CPU, RAM, and Disk configurations\n- Base QCOW2 image support for efficient disk usage\n- Volume-based persistent disk\n- Easy-to-use `docker-compose` deployment\n\n---\n\n## ⚙️ Requirements\n\n- Docker\n- Docker Compose\n- Host system that supports KVM/QEMU (Linux recommended)\n\n---\n\n## 🚀 Getting Started\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/cynegeirus/winbox-docker.git\ncd winbox-docker\n````\n\n### 2. Prepare ISO Images\n\nPlace your Windows installation ISO and VirtIO ISO files into the `iso/` directory:\n\n```\niso/\n├── os.iso         # Windows ISO\n└── virtio.iso     # VirtIO drivers ISO\n```\n\n\u003e You can rename them if needed, just update the Dockerfile or `main.sh` accordingly.\n\n---\n\n## 🔧 Configuration\n\nYou can modify the following environment variables inside `docker-compose.yml` or `.env`:\n\n```yaml\nenvironment:\n  - CPU=2              # Number of CPU cores\n  - RAM=4G        # RAM in megabytes\n  - DISK_SIZE=20G      # Virtual disk size\n  - VNC_PORT=5903      # VNC port to expose\n```\n\n---\n\n## 🧪 First-Time Setup\n\nTo build and start the virtual machine:\n\n```bash\ndocker-compose up -d --build\n```\n\n\u003e The first run will create the disk image and start the Windows installation.\n\n---\n\n## 🖥️ Access the VM\n\nUse any VNC client to connect:\n\n```\nHost: \u003cyour-host-ip\u003e\nPort: \u003cVNC_PORT\u003e (default 5901)\n```\n\n![plot](./images/Example.jpeg)\n\n---\n\n## 💾 Persistent Storage\n\nThe virtual machine disk is stored in a named Docker volume or host path (`/machines/` inside the container). You can mount it from the host or export it for backup.\n\n---\n\n## 🧠 Advanced Features\n\n* **Base Image Layering**: Use `qemu-img` with `-b base.qcow2` to create differential VM disks.\n* **Multiple VMs**: Scale up using `docker-compose --scale machine=n` with different ports.\n\n---\n\n## 📁 Project Structure\n\n```\n.\n├── Dockerfile         # QEMU + VNC setup\n├── docker-compose.yml\n├── main.sh            # VM startup script\n├── iso/               # Directory for ISOs\n└── vm/                # (optional) disk storage\n```\n\n---\n\n## ⚠️ Warnings\n\n* Do **not** mount the same QCOW2 disk in multiple VMs for read-write.\n* Base QCOW2 files must remain **unchanged** once overlay disks are created.\n* Ensure host system supports KVM and nested virtualization.\n\n---\n\n## 📜 License\n\nThis project is licensed under the [MIT License](LICENSE). See the license file for details.\n\n---\n\n## 🙌 Issues, Feature Requests or Support\n\nPlease use the Issue \u003e New Issue button to submit issues, feature requests or support issues directly to me. You can also send an e-mail to akin.bicer@outlook.com.tr.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcynegeirus%2Fwinbox-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcynegeirus%2Fwinbox-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcynegeirus%2Fwinbox-docker/lists"}