{"id":15626123,"url":"https://github.com/code-hex/vz","last_synced_at":"2025-05-14T21:10:37.245Z","repository":{"id":39405940,"uuid":"319086813","full_name":"Code-Hex/vz","owner":"Code-Hex","description":"Create virtual machines and run Linux-based operating systems in Go using Apple Virtualization.framework.","archived":false,"fork":false,"pushed_at":"2025-01-06T06:54:41.000Z","size":746,"stargazers_count":645,"open_issues_count":2,"forks_count":57,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-03-30T14:03:08.355Z","etag":null,"topics":["apple","applesilicon","go","golang","linux","m1","m2","macos","virtualization","vm"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/Code-Hex/vz/v3","language":"Go","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/Code-Hex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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},"funding":{"github":"Code-Hex"}},"created_at":"2020-12-06T17:09:07.000Z","updated_at":"2025-03-28T16:50:49.000Z","dependencies_parsed_at":"2023-02-12T19:31:03.288Z","dependency_job_id":"accdc5cb-bc14-4805-87dc-4f174949c191","html_url":"https://github.com/Code-Hex/vz","commit_stats":{"total_commits":328,"total_committers":15,"mean_commits":"21.866666666666667","dds":0.4359756097560976,"last_synced_commit":"e20c903856566be53a0511acd98d4e7bc555d9c3"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Code-Hex%2Fvz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Code-Hex%2Fvz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Code-Hex%2Fvz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Code-Hex%2Fvz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Code-Hex","download_url":"https://codeload.github.com/Code-Hex/vz/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247500462,"owners_count":20948879,"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":["apple","applesilicon","go","golang","linux","m1","m2","macos","virtualization","vm"],"created_at":"2024-10-03T10:10:49.240Z","updated_at":"2025-04-06T15:04:30.928Z","avatar_url":"https://github.com/Code-Hex.png","language":"Go","readme":"vz - Go binding with Apple [Virtualization.framework](https://developer.apple.com/documentation/virtualization?language=objc)\n=======\n\n[![Build](https://github.com/Code-Hex/vz/actions/workflows/compile.yml/badge.svg)](https://github.com/Code-Hex/vz/actions/workflows/compile.yml) [![Go Reference](https://pkg.go.dev/badge/github.com/Code-Hex/vz/v3.svg)](https://pkg.go.dev/github.com/Code-Hex/vz/v3)\n\nvz provides the power of the Apple Virtualization.framework in Go. Put here is block quote of overreview which is written what is Virtualization.framework from the document.\n\n\u003e The Virtualization framework provides high-level APIs for creating and managing virtual machines (VM) on Apple silicon and Intel-based Mac computers. Use this framework to boot and run macOS or Linux-based operating systems in custom environments that you define. The framework supports the [Virtual I/O Device (VIRTIO)](https://docs.oasis-open.org/virtio/virtio/v1.1/csprd01/virtio-v1.1-csprd01.html) specification, which defines standard interfaces for many device types, including network, socket, serial port, storage, entropy, and memory-balloon devices.\n\n## Usage\n\nPlease see the [example](https://github.com/Code-Hex/vz/tree/main/example) directory.\n\n## Requirements\n\n- Higher or equal to macOS Big Sur (11.0.0).\n- Latest version of vz supports last two Go major [releases](https://go.dev/doc/devel/release) and might work with older versions.\n\n## Installation\n\nInitialize your project by creating a folder and then running `go mod init github.com/your/repo` ([learn more](https://go.dev/blog/using-go-modules)) inside the folder. Then install vz with the go get command:\n\n```\n$ go get github.com/Code-Hex/vz/v3\n```\n\nDeprecated older versions (v1, v2).\n\n## Feature Overview\n\n- ✅ Virtualize Linux on a Mac **(x86_64, arm64)**\n  - GUI Support\n  - Boot Extensible Firmware Interface (EFI) ROM\n  - Clipboard sharing through the SPICE agent\n- ✅ Virtualize macOS on Apple Silicon Macs **(arm64)**\n    - Fetches the latest restore image supported by this host from the network\n  - Start in recovery mode\n- ✅ Running Intel Binaries in Linux VMs with Rosetta **(arm64)**\n- ✅ [Shared Directories](https://github.com/Code-Hex/vz/wiki/Shared-Directories)\n- ✅ [Virtio Sockets](https://github.com/Code-Hex/vz/wiki/Sockets)\n- ✅ Less dependent (only under golang.org/x/*)\n\n## Important\n\nFor binaries used in this package, you need to create an entitlements file like the one below and apply the following command.\n\n\u003cdetails\u003e\n\u003csummary\u003evz.entitlements\u003c/summary\u003e\n\n```\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n\t\u003ckey\u003ecom.apple.security.virtualization\u003c/key\u003e\n\t\u003ctrue/\u003e\n\u003c/dict\u003e\n\u003c/plist\u003e\n```\n\n\u003c/details\u003e\n\n```sh\n$ codesign --entitlements vz.entitlements -s - \u003cYOUR BINARY PATH\u003e\n```\n\n\u003e A process must have the com.apple.security.virtualization entitlement to use the Virtualization APIs.\n\nIf you want to use [`VZBridgedNetworkDeviceAttachment`](https://developer.apple.com/documentation/virtualization/vzbridgednetworkdeviceattachment?language=objc), you need to add also `com.apple.vm.networking` entitlement.\n\n## Known compile-time warnings\n\nIf you compile using an older Xcode SDK, you will get the following warnings.\n\nThis example warns that macOS 12.3 API and macOS 13 API are not available in the binary build. This means these APIs are not available even if you are running this binary on a modern OS (macOS 12.3 or macOS 13). \n\n```\n$ go build .\n# github.com/Code-Hex/vz/v3\nIn file included from _cgo_export.c:4:\nIn file included from socket.go:6:\nIn file included from ./virtualization_11.h:9:\n./virtualization_helper.h:25:9: warning: macOS 12.3 API has been disabled [-W#pragma-messages]\n./virtualization_helper.h:32:9: warning: macOS 13 API has been disabled [-W#pragma-messages]\n```\n\nIf you want to build a binary that can use the API on all operating systems, make sure the Xcode SDK is up-to-date.\n\nYou can check the version of the Xcode SDK available for each macOS on this site.\n\nhttps://xcodereleases.com/\n\n## Version compatibility check\n\nThe package provides a mechanism for checking the availability of the respective API through error handling:\n\n```go\nbootLoader, err := vz.NewEFIBootLoader()\nif errors.Is(err, vz.ErrUnsupportedOSVersion) || errors.Is(err, vz.ErrBuildTargetOSVersion) {\n  return fallbackBootLoader()\n}\nif err != nil {\n  return nil, err\n}\nreturn bootLoader, nil\n```\n\nThere are two items to check.\n\n1. API is compatible with the version of macOS\n2. The binary was built with the API enabled\n\n## Knowledge for the Apple Virtualization.framework\n\nThere is a lot of knowledge required to use this Apple Virtualization.framework, but the information is too scattered and very difficult to understand. In most cases, this can be found in [the official documentation](https://developer.apple.com/documentation/virtualization?language=objc). However, the Linux kernel knowledge required to use the feature provided by this framework is not documented. Therefore, I have compiled the knowledge I have gathered so far into this wiki.\n\nhttps://github.com/Code-Hex/vz/wiki\n\nAnyone is free to edit this wiki. It would help someone if you could add information not listed here. Let's make a good wiki together!\n\n## Testing\n\nIf you want to contribute some code, you will need to add tests.\n\n[PUI PUI Linux](https://github.com/Code-Hex/puipui-linux) is used to test this library. This Linux is designed to provide only the minimum functionality required for the Apple Virtualization.framework (Virtio), so the kernel file size is very small.\n\nThe test code uses the `Makefile` in the project root.\n\n```\n$ # Download PUI PUI Linux, Only required the first time.\n$ make download_kernel\n$ make test\n```\n\n## Which projects use this library?\n\n- [vfkit](https://github.com/crc-org/vfkit) is a macOS command-line hypervisor for Apple and Intel CPUs that supports most of Apple's Virtualization Framework features.\n- [Lima](https://lima-vm.io/) launches Linux virtual machines with automatic file sharing and port forwarding (similar to WSL2).\n- [linuxkit](https://github.com/linuxkit/linuxkit) is a toolkit for building custom minimal, immutable Linux distributions.\n\n## LICENSE\n\nMIT License\n","funding_links":["https://github.com/sponsors/Code-Hex"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-hex%2Fvz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcode-hex%2Fvz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-hex%2Fvz/lists"}