{"id":13564632,"url":"https://github.com/gyf304/vmcli","last_synced_at":"2026-02-03T14:10:38.621Z","repository":{"id":37011535,"uuid":"328723332","full_name":"gyf304/vmcli","owner":"gyf304","description":"A set of utilities (vmcli + vmctl) for macOS Virtualization.framework","archived":false,"fork":false,"pushed_at":"2024-04-12T07:23:46.000Z","size":57,"stargazers_count":827,"open_issues_count":14,"forks_count":44,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-04-03T21:35:57.733Z","etag":null,"topics":["cli","m1","macos","virtual-machine","vm"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gyf304.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":"2021-01-11T16:23:18.000Z","updated_at":"2025-03-22T10:46:16.000Z","dependencies_parsed_at":"2024-01-14T03:48:38.502Z","dependency_job_id":"9b8a3d26-7db2-4977-9e5f-49c623ddf14a","html_url":"https://github.com/gyf304/vmcli","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/gyf304/vmcli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gyf304%2Fvmcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gyf304%2Fvmcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gyf304%2Fvmcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gyf304%2Fvmcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gyf304","download_url":"https://codeload.github.com/gyf304/vmcli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gyf304%2Fvmcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29047453,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T10:09:22.136Z","status":"ssl_error","status_checked_at":"2026-02-03T10:09:16.814Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cli","m1","macos","virtual-machine","vm"],"created_at":"2024-08-01T13:01:33.889Z","updated_at":"2026-02-03T14:10:38.603Z","avatar_url":"https://github.com/gyf304.png","language":"Swift","readme":"# VMCLI\n\nA set of utilities to help you manage VMs with `Virtualization.framework`\n\n![vmctl-demo](./docs/demos/vmctl.svg)\n\n## Installation\n\n### Prerequisites\n\n* macOS Ventura (13+)\n* XCode.app installed\n\n```\n# make sure xcode command-line tools are installed\nxcode-select --install\n\n# run build, install. This will install vmcli and vmctl to /usr/local/bin\nmake\nsudo make install\n```\n\nYou have now finished installing `vmcli` and `vmctl`\n\nSet environment variable `VMCTLDIR` to `~/VMs` so `vmctl` knows how to find VMs.\nIf you don't set this, `vmctl` will use current working directory to find VMs.\n```bash\necho 'export VMCTLDIR=\"$HOME/VMs\"' \u003e\u003e ~/.zprofile\nexport VMCTLDIR=\"$HOME/VMs\"\n```\n\nProvision a Ubuntu VM, and install that to `~/VMs`.\nThe VM will auto create your user with your ssh public key at `~/.ssh/id_rsa.pub`.\n```bash\nmake build/vm/ubuntu\nmv build/vm/ubuntu \"${VMCTLDIR}/ubuntu\"\n```\n\nOptionally expand the VM volume, for example to 16G.\n```bash\ndd if=/dev/null of=\"${VMCTLDIR}/ubuntu/disk.img\" bs=1g count=0 seek=16\n```\n\nOptionally edit the VM config for more RAM and/or CPU cores\n```bash\nvi \"${VMCTLDIR}/ubuntu/vm.conf\"\n```\n\nStart the VM\n```bash\nvmctl start ubuntu\n```\n\nAttach to the serial console, use (CTRL+A - D to quit)\n```\nvmctl attach ubuntu\n```\n\nYou can use `vmctl ip ubuntu` to check your VM IP.\n\nWait for the VM to boot and ssh into the VM\n```\nvmctl ssh ubuntu\n```\n\nYou should shutdown the VM using ssh within the VM.\nIf that's not an option, you can forcibly shut it down.\n```\nvmctl stop ubuntu\n```\n\n## Share folders with host\n\nSupport for sharing folders with the host was added in macOS 12 (Monterey), and\nthis is enabled if compiled on 12.0 or later.\n\nAs of 12.1 the macOS support for this feature seems somewhat unreliable. If you\nwant to try it anyway, use `--folder \u003chost path\u003e:\u003ctag\u003e` arguments. In the guest,\nmount these using `-t virtiofs \u003ctag\u003e \u003cguest mountpoint\u003e`.\n\nIf the `:\u003ctag\u003e` component is omitted, the host path will be used as a tag, but\nnote there is a size limit of 36 UTF-8 bytes for tags.\n\nThe shared folder can be made read-only to the guest by adding `ro` as a third\ncomponent to the shared folder argument: `--folder \u003chost path\u003e:\u003ctag\u003e:ro`\n\nFor example: in the host, create a `foo` directory in the VM directory (where\nthe kernel and initrd live), and add this using `--folder`. For example, add\n`folder=foo` to `vm.conf`, or pass `--folder=foo` to `vmcli` directly.\n\nIn the guest, ensure `/mnt/foo` is an empty directory, then\n`sudo mount -t virtiofs foo /mnt/foo`.\n\n## Known Issues\n\n* Virtual Machine cannot be started with networking when InternetSharing is\n  already enabled. See [#5](/../../issues/5).\n\n## Usage\n\n### vmcli\n\n```\nUSAGE: vmcli [--cpu-count \u003ccpu-count\u003e] [--memory-size \u003cmemory-size\u003e] [--memory-size-suffix \u003cmemory-size-suffix\u003e] [--disk \u003cdisk\u003e ...] [--cdrom \u003ccdrom\u003e ...] [--folder \u003cfolder\u003e ...] [--network \u003cnetwork\u003e ...] [--balloon \u003cballoon\u003e] [--bootloader \u003cbootloader\u003e] [--kernel \u003ckernel\u003e] [--initrd \u003cinitrd\u003e] [--cmdline \u003ccmdline\u003e] [--escape-sequence \u003cescape-sequence\u003e]\n\nOPTIONS:\n  -c, --cpu-count \u003ccpu-count\u003e\n                          CPU count (default: 1)\n  -m, --memory-size \u003cmemory-size\u003e\n                          Memory Bytes (default: 512)\n  --memory-size-suffix \u003cmemory-size-suffix\u003e\n                          Memory Size Suffix (default: MiB)\n  -d, --disk \u003cdisk\u003e       Disks to use\n  --cdrom \u003ccdrom\u003e         CD-ROMs to use\n  -f, --folder \u003cfolder\u003e   Folders to share (macOS 12.0 or later)\n  -n, --network \u003cnetwork\u003e Networks to use. e.g. aa:bb:cc:dd:ee:ff@nat for a nat device, or ...@en0 for bridging to en0. Omit mac address for a\n                          generated address. (default: nat)\n  --balloon \u003cballoon\u003e     Enable / Disable Memory Ballooning (default: true)\n  -b, --bootloader \u003cbootloader\u003e\n                          Bootloader to use (default: linux)\n  -k, --kernel \u003ckernel\u003e   Kernel to use\n  --initrd \u003cinitrd\u003e       Initrd to use\n  --cmdline \u003ccmdline\u003e     Kernel cmdline to use\n  --escape-sequence \u003cescape-sequence\u003e\n                          Escape Sequence, when using a tty (default: q)\n  -h, --help              Show help information.\n```\n\n### vmctl\n\n```\nusage: vmctl {start|stop|attach|ip|ssh} vm\n       vmctl list\n```\n\n## References\n\n[SimpleVM](https://github.com/KhaosT/SimpleVM) is a proof-of-concept using `Virtualization.framework` by [KhaosT](https://github.com/KhaosT)\n\n[vftool](https://github.com/evansm7/vftool) is a very similar tool written by [evansm7](https://github.com/evansm7) but in Objective-C not Swift.\n","funding_links":[],"categories":["Swift","By Language"],"sub_categories":["Swift"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgyf304%2Fvmcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgyf304%2Fvmcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgyf304%2Fvmcli/lists"}