{"id":31237023,"url":"https://github.com/macvmio/geranos","last_synced_at":"2026-01-12T06:38:38.254Z","repository":{"id":233372860,"uuid":"776445582","full_name":"macvmio/geranos","owner":"macvmio","description":"Transfers macOS virtual machine images to and from OCI registries","archived":false,"fork":false,"pushed_at":"2024-10-26T13:53:13.000Z","size":206,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-31T09:38:08.499Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/macvmio.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-03-23T14:30:30.000Z","updated_at":"2024-10-26T13:53:17.000Z","dependencies_parsed_at":"2024-09-07T22:20:51.996Z","dependency_job_id":"63e89c73-cef0-4a5b-8444-68089331e818","html_url":"https://github.com/macvmio/geranos","commit_stats":null,"previous_names":["tomekjarosik/geranos","mobileinf/geranos","macvmio/geranos"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/macvmio/geranos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macvmio%2Fgeranos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macvmio%2Fgeranos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macvmio%2Fgeranos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macvmio%2Fgeranos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/macvmio","download_url":"https://codeload.github.com/macvmio/geranos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macvmio%2Fgeranos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276439796,"owners_count":25642752,"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","status":"online","status_checked_at":"2025-09-22T02:00:08.972Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-09-22T16:59:22.202Z","updated_at":"2025-09-22T16:59:23.810Z","avatar_url":"https://github.com/macvmio.png","language":"Go","funding_links":[],"categories":["Virtualization"],"sub_categories":["macOS Environments"],"readme":"![Geranos](resources/geranos-logo.png)\n\n[![Build Status](https://github.com/macvmio/geranos/actions/workflows/main.yml/badge.svg)](https://github.com/macvmio/geranos/actions)\n[![Build Status](https://github.com/macvmio/geranos/actions/workflows/release.yml/badge.svg)](https://github.com/macvmio/geranos/actions)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\n## Introduction\n\nGeranos is a command-line tool written in Go for efficiently transferring **macOS virtual machine images** to and from OCI-compliant container registries. Specifically designed for macOS VMs utilizing the **APFS Copy-on-Write filesystem**, Geranos optimizes both bandwidth and disk usage by leveraging sparse files and filesystem cloning capabilities.\n\nGeranos integrates seamlessly with [Curie](https://github.com/macvmio/curie), a macOS VM virtualization program, allowing users to pull VM images and run them with minimal effort.\n\n## Features\n\n- **Efficient Transfer of Large VM Images**: Handles VM images typically over 30GB in size.\n- **Bandwidth Optimization**: Verifies local hashes in `disk.img` files to minimize data transfer.\n- **Disk Usage Optimization**: Utilizes clone operations for efficient cloning and skips writing zeros to save disk space.\n- **Integration with Curie**: Easily pull VM images with Geranos and run them using Curie.\n- **OCI Registry Support**: Push and pull VM images from any OCI-compliant container registry.\n- **Familiar Interface**: Command-line interface similar to Docker and `crane`, making it easy for users familiar with these tools.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n    - [Configuration](#configuration)\n    - [Pulling a VM Image](#pulling-a-vm-image)\n    - [Running a Pulled VM Image with Curie](#running-a-pulled-vm-image-with-curie)\n    - [Available Commands](#available-commands)\n- [Contributing](#contributing)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n- [Future Plans](#future-plans)\n- [Contact and Support](#contact-and-support)\n\n## Installation\n\nGeranos can be downloaded from the [GitHub releases page](https://github.com/macvmio/geranos/releases).\n\n### Prerequisites\n\n- **Go**: If you plan to build Geranos from source, ensure you have Go installed.\n- **Curie**: For running pulled VM images, install [Curie](https://github.com/macvmio/curie).\n\n### Download Binary\n\n1. **Visit the Releases Page**: Go to the [Geranos Releases](https://github.com/macvmio/geranos/releases) page.\n2. **Download the Binary**: Choose the appropriate binary for your operating system.\n3. **Install the Binary**:\n    - Move the binary to a directory in your `$PATH`, such as `/usr/local/bin`.\n    - Make the binary executable:\n      ```bash\n      chmod +x /usr/local/bin/geranos\n      ```\n\n### Using Mise\n\nYou can use [Mise](https://mise.jdx.dev)'s [Ubi backend](https://mise.jdx.dev/dev-tools/backends/ubi.html) to install `geranos` with the following command:\n\n```bash\nmise install ubi:macvmio/geranos\n```\n\n### Build from Source (Optional)\n\nIf you prefer to build from source:\n\n```bash\ngit clone https://github.com/macvmio/geranos.git\ncd geranos\ngo build -o geranos ./cmd/geranos/main.go\n```\n\n## Usage\n\n### Configuration\n\nGeranos requires a configuration file located at `~/.geranos/config.yaml`. This file specifies where images are stored locally.\n\n**Example `~/.geranos/config.yaml`:**\n\n```yaml\nimages_directory: /Users/yourusername/.curie/.images\n```\n\nReplace `/Users/yourusername` with your actual username or the path where Curie stores images.\n\nNOTE: For curie up to 3.0, you have to specify \".curie/images\" (without a dot)\n\n### Pulling a VM Image\n\nTo pull a macOS VM image from an OCI registry:\n\n```bash\ngeranos pull ghcr.io/macvmio/macos-sonoma:14.5-agent-v1.6\n```\n\nThis command downloads the VM image while optimizing bandwidth and disk usage.\n\n### Running a Pulled VM Image with Curie\n\nAfter pulling the image, run it using Curie:\n\n```bash\ncurie run ghcr.io/macvmio/macos-sonoma:14.5-agent-v1.6\n```\n\n### Available Commands\n\nGeranos provides several commands:\n\n- **adopt**: Adopt a directory as an image under the current local registry.\n- **clone**: Locally clone one reference to another name.\n- **completion**: Generate the autocompletion script for the specified shell.\n- **context**: Manage contexts.\n- **help**: Help about any command.\n- **inspect**: Inspect details of a specific OCI image.\n- **list**: List all OCI images in a specific local registry.\n- **login**: Log in to a registry.\n- **logout**: Log out of a registry.\n- **pull**: Pull an OCI image from a registry and extract the file.\n- **push**: Push a large file as an OCI image to a registry.\n- **remote**: Manipulate remote repositories.\n- **remove**: Remove locally stored images.\n- **version**: Print the version.\n\n**General Flags:**\n\n- `-h`, `--help`: Help for Geranos.\n- `-v`, `--verbose`: Enable verbose output.\n- `--version`: Show Geranos version.\n\n**Get Help for a Command:**\n\n```bash\ngeranos [command] --help\n```\n\n### Examples\n\n- **List remote images**\n\n  ```bash\n  geranos remote images ghcr.io/macvmio/macos-sonoma\n  ```\n\n- **Push an Image to a Registry:**\n\n  ```bash\n  geranos push registry.example.com/namespace/myimage:tag\n  ```\n\n- **List Images in Local Registry:**\n\n  ```bash\n  geranos list\n  ```\n\n## Contributing\n\nContributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n- **Reporting Issues**: Use the [issue tracker](https://github.com/macvmio/geranos/issues) to report bugs or request features.\n- **Pull Requests**: Submit pull requests to the `main` branch.\n\n## License\n\nGeranos is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by [go-containerregistry](https://github.com/google/go-containerregistry).\n- Utilizes [Cobra](https://github.com/spf13/cobra) and [Viper](https://github.com/spf13/viper) for command-line interface and configuration management.\n\n## Future Plans\n\n- Integration with the upcoming [macvm.io](https://macvm.io) website.\n- Enhanced filesystem optimization features.\n- Support for additional VM formats and platforms.\n\n\n## Contact and Support\n\n- **GitHub Repository**: [github.com/macvmio/geranos](https://github.com/macvmio/geranos)\n- **Issues**: [github.com/macvmio/geranos/issues](https://github.com/macvmio/geranos/issues)\n- **Email**: [contact@macvm.io](mailto:contact@macvm.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacvmio%2Fgeranos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacvmio%2Fgeranos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacvmio%2Fgeranos/lists"}