{"id":15700138,"url":"https://github.com/erikh/emu","last_synced_at":"2025-05-12T13:13:12.103Z","repository":{"id":145966902,"uuid":"358966552","full_name":"erikh/emu","owner":"erikh","description":"emu is a CLI tool for managing qemu on desktop Linux","archived":false,"fork":false,"pushed_at":"2025-03-01T18:21:29.000Z","size":315,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-12T13:13:00.241Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","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/erikh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2021-04-17T19:36:16.000Z","updated_at":"2025-03-01T18:21:33.000Z","dependencies_parsed_at":"2024-10-24T04:58:58.111Z","dependency_job_id":"d08ecce0-f83a-4374-a1d5-d24f1e94ca0b","html_url":"https://github.com/erikh/emu","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Femu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Femu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Femu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Femu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erikh","download_url":"https://codeload.github.com/erikh/emu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745195,"owners_count":21957319,"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":[],"created_at":"2024-10-03T19:46:21.813Z","updated_at":"2025-05-12T13:13:11.988Z","avatar_url":"https://github.com/erikh.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# emu-cli: a small control toolkit for qemu\n\n`emu-cli` installs the `emu` tool, which is a CLI program currently aimed at making x86 VM usage easier for Linux desktop users.\n\nSee a video of it in action: [YouTube](https://youtu.be/snagHPxFIgw)\n\nIt contains commands to:\n\n-   Manage VMs as a system-wide fleet\n    -   List all VMs in one place, along with their run status\n    -   Clone and Import VMs from other sources\n-   Create, Delete, Start, Stop, and Reboot VMs\n    -   ISOs can be attached\n    -   You can start VMs with or without graphical screens\n    -   `emu` does not have to be running to maintain your VM\n-   Import and Clone VM images\n-   Maintain snapshots and save states\n-   Supervise VMs with systemd\n    -   Uses the user profile (`systemctl --user`)\n    -   Knows about which systemd units its maintaining\n        -   Deletes them when the VM is deleted\n-   Manage settings for VMs\n    -   RAM, CPUs, Video \u0026 CPU type\n    -   Forward Ports to VM networks\n-   Define a SSH port that stays with the VM and `emu ssh` to it easily\n-   Poke and prod at your VMs with `emu nc`, which opens a TCP socket to the port on the VM\n-   Play with qemu QMP commands to control your VM externally\n\n## Requirements\n\nLinux with systemd and qemu. It places things according to the XDG standards, so that means `$HOME/.local` will have the VMs, etc.\n\nTo build the software, you will need a working rust environment. I strongly recommend [rustup](https://rustup.rs).\n\n## Stability\n\nemu is still undergoing some UI changes. I do use it somewhat regularly, but there may be additional work that needs to be done for a larger goal that changes small things as they stand now.\n\nemu has bugs, particularly nasty ones at times related to your VMs. I would not use emu in a setting where data integrity mattered much.\n\n## Installation\n\n```\ncargo install emu-cli\n```\n\nOnce installed, you can invoke the software with `emu`.\n\n## Usage\n\n```bash\n$ emu create myvm 50 # gigabytes of storage\n\n# start the vm with the cdrom set to the ubuntu iso. Press ^C to terminate the vm.\n$ emu run myvm --cdrom ubuntu.iso\n\n# make a copy before doing something dumb\n$ emu clone myvm myvm.template\n$ emu list\nmyvm (unsupervised) (size: 6.10 GB)\nmyvm.template (unsupervised) (size: 6.10 GB)\n\n# supervision in systemd\n$ emu supervise myvm\n$ emu supervised\nmyvm: not running\n$ systemctl --user start myvm.emu # or enable it, if you'd like. it sticks to your login session.\n$ emu list\nmyvm (supervised: running) (size: 6.10 GB)\nmyvm.template (unsupervised) (size: 6.10 GB)\n$ systemctl --user stop myvm.emu # graceful shutdown\n$ emu unsupervise myvm\n\n# run detached and without a screen\n$ emu run --detach --headless myvm\n$ emu list\nmyvm (pid: 8675309) (size: 6.10 GB)\nmyvm.template (unsupervised) (size: 6.10 GB)\n\n# ssh support\n$ emu config port map myvm 2222 22\n$ emu config set myvm ssh-port 2222\n$ emu ssh myvm\nmyvm$ exit\n\n# nc support\n$ emu config port map myvm 8000 80\n$ emu nc myvm 8000\nGET / HTTP/1.1\nHost: localhost\nHTTP/1.1 403 Forbidden\nConnection: close\n\n# cleanup\n$ emu shutdown myvm\n$ emu remove myvm\n$ emu list\nmyvm.template (unsupervised) (6.10 GB)\n```\n\n### Configuration\n\nConfiguration is provided currently by injecting values into a file under\n`~/.local/share/emu/\u003cVM\u003e/config`. It is in TOML format.\n\n#### Configuration Values\n\n`[machine]` section:\n\n-   `memory`: integer; memory in megabytes. Default is 16384.\n-   `cpus`: integer; count of CPU cores. Default is 8.\n-   `vga`: string; name of VGA driver to use with `qemu -vga`. Default is `virtio`.\n-   `image_interface`: string; name of interface to use for talking to images with `-drive`. Default `virtio` is recommended.\n-   `cpu_type`: string; type of CPU to support. Must be x86 and valid to pass to `qemu -cpu`. Default `host` is recommended.\n-   `ssh_port`: integer; port to contact for SSH access; used by `emu ssh`. Default is 2222.\n\n`[ports]` is just a key/value map of host ports, opened on `localhost`, to guest ports, opened on `0.0.0.0`. No other processing is performed.\n\n#### Configuration Example\n\n```toml\n[machine]\ncpus = 4\nmemory = 512\n\n[ports]\n2222 = 22\n```\n\n#### Management Tool\n\nYou can control these values with `emu config \u003csubcommand\u003e` sub-commands. `emu config show`, `emu config set`, and `emu config port` can be used to manage these sections.\n\nThe commands for `emu config set` are the same as the above `[machine]` section keys, only the underscores (`_`) are replaced with dashes (`-`); so that `ssh_port` is now `ssh-port`.\n\n```bash\n$ emu config show myvm\n[machine]\ncpus = 4\nmemory = 512\n\n[ports]\n2222 = 22\n\n$ emu config port map myvm 2223 23\n$ emu config port unmap myvm 2223\n\n$ emu config set myvm ssh-port 2222\n$ emu config set myvm cpus 8\n\n$ emu config show myvm\n[machine]\ncpus = 8\nmemory = 512\nssh_port = 2222\n\n[ports]\n2222 = 22\n2223 = 23\n```\n\n## License\n\nMIT\n\n## Author\n\nErik Hollensbe \u003cgithub@hollensbe.org\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferikh%2Femu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferikh%2Femu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferikh%2Femu/lists"}