{"id":20895166,"url":"https://github.com/wy-z/container-vm","last_synced_at":"2025-04-23T21:02:06.871Z","repository":{"id":224242322,"uuid":"752977893","full_name":"wy-z/container-vm","owner":"wy-z","description":"A simple way to run QEMU/KVM VM inside a container (supports Windows, OpenWRT VM and all others)","archived":false,"fork":false,"pushed_at":"2024-03-08T15:03:56.000Z","size":144,"stargazers_count":151,"open_issues_count":0,"forks_count":26,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-19T10:08:15.437Z","etag":null,"topics":["container","docker","kvm","linux","opengl","qemu","vm","vnc","windows"],"latest_commit_sha":null,"homepage":"","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/wy-z.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}},"created_at":"2024-02-05T08:24:43.000Z","updated_at":"2025-03-30T05:44:00.000Z","dependencies_parsed_at":"2024-02-24T19:27:01.409Z","dependency_job_id":"e9bd9062-d98a-4e1f-bda9-ea8bc9d828e7","html_url":"https://github.com/wy-z/container-vm","commit_stats":null,"previous_names":["wy-z/container-vm"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wy-z%2Fcontainer-vm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wy-z%2Fcontainer-vm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wy-z%2Fcontainer-vm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wy-z%2Fcontainer-vm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wy-z","download_url":"https://codeload.github.com/wy-z/container-vm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250514767,"owners_count":21443208,"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":["container","docker","kvm","linux","opengl","qemu","vm","vnc","windows"],"created_at":"2024-11-18T10:25:30.853Z","updated_at":"2025-04-23T21:02:06.818Z","avatar_url":"https://github.com/wy-z.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# container-vm\n\n[![Pulls]][hub_url]\n[![image](https://raw.githubusercontent.com/wy-z/container-vm/main/tests/coverage.svg)](https://github.com/wy-z/container-vm)\n\nRun qemu/kvm VM inside a docker container\n\n## Quick Start\n\n### Linux\n\n```sh\nmkdir tmp \u0026\u0026 cp tmp\nwget https://dl-cdn.alpinelinux.org/alpine/v3.19/releases/x86_64/alpine-virt-3.19.1-x86_64.iso\ndocker run --name container-vm --rm -v $PWD:/storage --cap-add=NET_ADMIN \\\n    --device=/dev/kvm -p 8080:8080 weiyang/container-vm run --iso /storage/alpine-virt-3.19.1-x86_64.iso\n```\n\n### MacOS\n\n```sh\nmkdir tmp \u0026\u0026 cp tmp\nwget https://dl-cdn.alpinelinux.org/alpine/v3.19/releases/x86_64/alpine-virt-3.19.1-x86_64.iso\ndocker run --name container-vm --rm -v $PWD:/storage --cap-add=NET_ADMIN --device-cgroup-rule='c *:* rwm' \\\n    -p 8080:8080 weiyang/container-vm run --macvlan --iso /storage/alpine-virt-3.19.1-x86_64.iso\n```\n\nThen you can:\n\n- Open `http://localhost:8080` to visit VM graphic\n- `docker exec -it container-vm telnet 127.0.0.1 10000` to visit VM console\n  - `Ctrl-A-C` -\u003e Qemu monitor console\n  - `Ctrl-]` + `quit` to exit telnet\n\n## Features\n\n- Simplicity: Utilizes a clean, straightforward QEMU setup for hassle-free virtualization, focusing on ease of use.\n- Flexibility: Offers full compatibility and extensibility with customizable configurations, catering to diverse needs and ensuring easy adaptability for future expansions.\n- Native Performance: Delivers exceptional efficiency and optimal performance through the use of advanced technologies such as Tap, MacVlan, and KVM acceleration.\n\n## Windows VM\n\n1.  Download windows iso (`Win11_23H2_x64v2.iso` or [tiny11](https://archive.org/details/tiny11-2311))\n2.  Download VirtIO from `https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio` (`virtio-win.iso`)\n\n        If the hard drive is not detected, remember to install the drivers from the VirtIO ISO\n\n3.  Start container\n\n    Linux\n\n    ```sh\n    docker run --rm -v $PWD:/storage --cap-add=NET_ADMIN --device /dev/kvm \\\n        -p 8080:8080 weiyang/container-vm run -c 4 -m 8192 \\\n        --iso /storage/Win11_23H2_x64v2.iso windows --virtio-iso /storage/virtio-win.iso \\\n        apply-disk -s 64G -n hda ext-args -- -cpu host\n    ```\n\n    MacOS\n\n    ```sh\n    docker run --rm -v $PWD:/storage --cap-add=NET_ADMIN --device-cgroup-rule='c *:* rwm' \\\n        -p 8080:8080 weiyang/container-vm run --macvlan -c 4 -m 8192 \\\n        --iso /storage/Win11_23H2_x64v2.iso windows --virtio-iso /storage/virtio-win.iso \\\n        apply-disk -s 64G -n hda\n    ```\n\n        On MacOS, rm `--device=/dev/kvm` and `ext-args -- -cpu host`\n\n    1. `--cap-add=NET_ADMIN` is necessary for network configuration\n    2. `--device-cgroup-rule='c *:* rwm'` is necessary for macvlan, or disable by `--no-macvlan`\n    3. `-c 4 -m 8192` 4 cpu cores, 8G memory\n    4. `--iso /storage/Win11_23H2_x64v2.iso` add boot cdrom\n    5. `windows --virtio-iso /storage/virtio-win.iso` add virtio iso\n    6. `apply-disk -s 64G -n hda` create a 64G disk if not exists\n    7. `ext-args -- -cpu host` host-passthrough cpu mode, all flags after `ext-args --` will be passed to qemu\n    8. VirtIO iso is recommended for best performance\n\n#### OpenGL Support\n\nInstall Mesa3D driver https://github.com/pal1000/mesa-dist-win/releases\n\n#### Better Graphical Performance\n\n1.  Run docker with `--device=/dev/dri`\n2.  Run image with `run *** --vga - ext-args -- -display egl-headless -device virtio-vga-gl`\n\n## Container capability limits\n\n1. Minimum capability requirement is `--cap-add=NET_ADMIN`, run with `--no-accel`\n2. `--device-cgroup-rule='c *:* rwm'`/`--macvlan` will enable macvlan, otherwise use tap bridge\n3. `--device=/dev/kvm`/`--no-accel` will disable IO acceleration, not recommended\n\n## Custom Actions\n\n1. Write custom shell script to `/tmp/setup.sh`, e.g.\n\n```sh\nset -e\napt update\napt install -y glusterfs-common\n```\n\n2. Run docker with `-v /tmp:/tmp`\n\n3. Run image with `run *** exec-sh -f /tmp/setup.sh`\n\n## Podman Support\n\nThe testing for Podman is not yet complete; you may submit an Issue if needed.\n\n- May need to add more capabilities, such as `--cap-add NET_RAW`\n- May need to add more devices, such as `--device=/dev/net/tun`\n\n## CLI Commands\n\n### Run\n\n    Commands are chainable, e.g. `run xxx windows xxx apply-disk xxx port-forward xxx ext-args -- xxx xxx`\n\n```\n❯ python main.py run --help\n\n Usage: main.py run [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...\n\n╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ --cpu        -c                  INTEGER                                                                    CPU cores [default: None]                                                   │\n│ --mem        -m                  INTEGER RANGE [x\u003e=1]                                                       Memory size in MB [default: None]                                           │\n│ --arch                           [alpha|sparc|nios2|sh4|xtensa|avr|sparc64|riscv32|m68k|tricore|microblaze  VM arch [default: x86_64]                                                   │\n│                                  |cris|mipsel|sh4eb|aarch64|loongarch64|ppc|hppa|mips64el|or1k|i386|mips64                                                                              │\n│                                  |rx|microblazeel|riscv64|xtensaeb|mips|x86_64|s390x|arm|ppc64]                                                                                         │\n│ --iso                            TEXT                                                                       ISO file path or drive url [default: None]                                  │\n│ --accel          --no-accel                                                                                 Enable acceleration [default: accel]                                        │\n│ --macvlan        --no-macvlan                                                                               Enable macvlan network, otherwise use bridge network [default: no-macvlan]  │\n│ --netdev         --no-netdev                                                                                Setup netdev or not [default: netdev]                                       │\n│ --dhcp           --no-dhcp                                                                                  Enable DHCP [default: dhcp]                                                 │\n│ --vnc-web        --no-vnc-web                                                                               Enable VNC web client (noVNC) [default: vnc-web]                            │\n│ --console        --no-console                                                                               Enable Qemu monitor (mon+telnet+qmp) [default: console]                     │\n│ --machine                        TEXT                                                                       Machine type [default: None]                                                │\n│ --boot                           STR_OR_NONE                                                                Boot options (Set to '-' to disable) [default: once=dc]                     │\n│ --vga                            STR_OR_NONE                                                                Setup VGA (Set to '-' to disable) [default: virtio]                         │\n│ --boot-mode                      [uefi|secure|windows|legacy]                                               Boot mode [default: legacy]                                                 │\n│ --iface                          TEXT                                                                       (multiple) Special VM network interface (e.g. eth1)                         │\n│ --network                        TEXT                                                                       (multiple) Special VM network CIDR (IPv4) (e.g. 192.168.1.0/24)             │\n│ --dry            --no-dry                                                                                   Dry run [default: no-dry]                                                   │\n│ --help                                                                                                      Show this message and exit.                                                 │\n╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ apply-disk                                   Apply VM disk                                                                                                                              │\n│ exec-sh                                      Exec shell script files before start Qemu                                                                                                  │\n│ ext-args                                     External Qemu args                                                                                                                         │\n│ port-forward                                 Forward VM ports                                                                                                                           │\n│ windows                                      Windows specific options                                                                                                                   │\n╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n### Apply Disk\n\n    `run xxx apply-disk -s 64G -n hda apply-disk -s 32G -n hdb`\n\n```\n❯ python main.py run apply-disk --help\n\n Usage: main.py run apply-disk [OPTIONS]\n\n Apply VM disk\n\n╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ *  --name       -n      TEXT  Disk name (e.g. disk1) [default: None] [required]                                                                                                         │\n│    --size       -s      TEXT  Disk size (e.g. 32G) [default: 16G]                                                                                                                       │\n│    --file-type          TEXT  Drive file type (e.g. qcow2,raw) [default: qcow2]                                                                                                         │\n│    --if-type            TEXT  Drive interface type (e.g. virtio,ide) [default: None]                                                                                                    │\n│    --opts               TEXT  External drive options (e.g. index=i,format=f) [default: None]                                                                                            │\n│    --help                     Show this message and exit.                                                                                                                               │\n╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n### Windows\n\n    `run xxx windows --virtio-iso /storage/virtio-iso.iso`\n\n```\n❯ python main.py run windows --help\n\n Usage: main.py run windows [OPTIONS]\n\n Windows specific options\n\n╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ --virtio-iso                PATH  Window virtio driver iso, download from https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio [default: None]                │\n│ --tpm           --no-tpm          Enable TPM [default: tpm]                                                                                                                             │\n│ --help                            Show this message and exit.                                                                                                                           │\n╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n### Port Forwarding\n\n    `run xxx port-forward -p 22:22 -p 3389:3389`\n    Ports 22 and 3389 are set to forward automatically by default\n\n```\n❯ python main.py run port-forward --help\n\n Usage: main.py run port-forward [OPTIONS]\n\n Forward VM ports\n\n╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ --port  -p      TEXT  (multiple) Port forward spec (e.g. 80:8088) [default: None]                                                                                                       │\n│ --help                Show this message and exit.                                                                                                                                       │\n╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n### External Arguments\n\n    `run xxx ext-args -- -cpu host -netdev xxx`\n\n```\n❯ python main.py run ext-args --help\n\n Usage: main.py run ext-args [OPTIONS] ARGS...\n\n External Qemu args\n\n╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ *    args      ARGS...  External Qemu args [default: None] [required]                                                                                                                   │\n╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ --help          Show this message and exit.                                                                                                                                             │\n╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n### Execute shell script\n\n    `run xxx exec-sh -f xxx.sh`\n\n```\n❯ python main.py run exec-sh --help\n\n Usage: main.py run exec-sh [OPTIONS]\n\n Exec shell script files before start Qemu\n\n╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ --file  -f      PATH  (multiple) shell script file [default: None]                                                                                                                      │\n│ --help                Show this message and exit.                                                                                                                                       │\n╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n## Similar Projects\n\n- https://github.com/BBVA/kvm\n- https://github.com/qemus/qemu-docker\n\n## License\n\nMIT\n\n[hub_url]: https://hub.docker.com/r/weiyang/container-vm/\n[Pulls]: https://img.shields.io/docker/pulls/weiyang/container-vm.svg?style=flat\u0026label=pulls\u0026logo=docker\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwy-z%2Fcontainer-vm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwy-z%2Fcontainer-vm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwy-z%2Fcontainer-vm/lists"}