{"id":31237025,"url":"https://github.com/macvmio/fugaci","last_synced_at":"2026-04-08T23:35:44.003Z","repository":{"id":259984579,"uuid":"847112160","full_name":"macvmio/fugaci","owner":"macvmio","description":"Kubernetes-based system for serving ephemeral macOS virtual machines (VMs)","archived":false,"fork":false,"pushed_at":"2025-08-16T20:53:01.000Z","size":284,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-22T16:59:24.507Z","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-24T22:09:52.000Z","updated_at":"2025-09-10T11:28:56.000Z","dependencies_parsed_at":"2024-10-28T23:28:11.953Z","dependency_job_id":"bfb5cdc2-289c-422e-b296-8ace2399840f","html_url":"https://github.com/macvmio/fugaci","commit_stats":null,"previous_names":["macvmio/fugaci"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/macvmio/fugaci","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macvmio%2Ffugaci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macvmio%2Ffugaci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macvmio%2Ffugaci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macvmio%2Ffugaci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/macvmio","download_url":"https://codeload.github.com/macvmio/fugaci/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macvmio%2Ffugaci/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31579057,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":[],"created_at":"2025-09-22T16:59:22.227Z","updated_at":"2026-04-08T23:35:43.982Z","avatar_url":"https://github.com/macvmio.png","language":"Go","funding_links":[],"categories":["Orchestration"],"sub_categories":["macOS Environments"],"readme":"![Fugaci](resources/fugaci-logo.png)\n\nFugaci is a tool that lets you run temporary macOS virtual machines (VMs) inside a Kubernetes cluster. Think of it as a bridge that connects the world of macOS applications with the powerful automation of Kubernetes.\n\nNormally, Kubernetes is used for managing Linux containers. Fugaci extends this capability, allowing you to manage macOS workloads using the same familiar Kubernetes tools, like `kubectl`. It cleverly makes a Mac computer appear as a special \"node\" in your Kubernetes cluster, ready to run macOS-specific tasks.\n\n#### Demo\n[![Demo](https://img.youtube.com/vi/aNRD9s1ACAo/maxresdefault.jpg)](https://www.youtube.com/watch?v=aNRD9s1ACAo)\n\n#### Integration with Jenkins\n[![Watch the video](https://img.youtube.com/vi/DbzaP82zl7c/maxresdefault.jpg)](https://www.youtube.com/watch?v=DbzaP82zl7c)\n\n---\n\n## A Building Block for macOS Workflows\n\nFugaci is designed to be a fundamental component, not a complete, all-in-one solution. Just as Kubernetes provides a powerful platform for building complex containerized systems, Fugaci provides the missing piece for managing temporary macOS environments within that platform. This allows developers and DevOps engineers to create custom, automated workflows for their specific macOS needs, such as building and testing iOS or macOS applications.\n\n---\n\n## Status\n\n**🧪 Experimental**: Fugaci is currently in an experimental phase and is not recommended for production environments. However, it has been successfully used to run thousands of VMs for continuous integration (CI) purposes over several days.\n\n---\n\n## Features\n\n-   **Ephemeral macOS VMs**: Automatically create and destroy macOS virtual machines as needed. This is great for one-off tasks like builds or tests, as it saves resources.\n-   **Kubernetes Integration**: Manage your macOS VMs using the standard Kubernetes commands and tools you already know.\n-   **Smart Scheduling**: Fugaci uses a Kubernetes feature called \"taints\" to ensure that only macOS-specific workloads are scheduled to run on your Mac hardware.\n-   **Simple Deployment**: It's easy to install and run, distributed as a single file.\n\n---\n\n## Getting Started\n\n### Prerequisites\n\nBefore you begin, you'll need the following:\n\n-   **A macOS Host**: Fugaci needs to be installed on a Mac computer (like a Mac mini or Mac Studio). It's best if this machine is dedicated to running Fugaci, without other virtualization software like Docker Desktop or Parallels.\n-   **Curie Binary**: Fugaci uses a separate tool called \"[curie](https://github.com/macvmio/curie)\" to handle the virtualization. You'll need to have this installed on your macOS host.\n-   **A Kubernetes Cluster**: You need an existing Kubernetes cluster. The guide below shows how to set up a simple `k3s` (a lightweight Kubernetes distribution) cluster for this purpose.\n-   **TLS Certificates**: For secure communication between Fugaci and the Kubernetes cluster, you'll need TLS security certificates. The instructions below cover how to generate these.\n\n### Installation\n\n#### 1. Set Up a Lightweight Kubernetes Cluster (k3s)\n\nOn a separate machine (or a VM that will act as your Kubernetes master), install `k3s`. You'll need to provide an IP address that your Fugaci node can use to communicate with it.\n\n```bash\n# Replace with the IP address of your k3s server\nexport FUGACI_K3S_SERVER_IP_ADDRESS=\"192.168.1.100\"\n\n# Install k3s\ncurl -sfL https://get.k3s.io | INSTALL_K3S_EXEC=\"server \\\n  --tls-san ${FUGACI_K3S_SERVER_IP_ADDRESS:?err} \\\n  --disable traefik \\\n  --disable-kube-proxy \\\n  --egress-selector-mode disabled\" sh -\n````\n\n#### 2\\. Configure `kubectl`\n\nAfter `k3s` is installed, it will create a configuration file at `/etc/rancher/k3s/k3s.yaml`. Copy this file to your local machine, and edit it to replace the server IP address `127.0.0.1` with the `${FUGACI_K3S_SERVER_IP_ADDRESS}` you used above. This file allows `kubectl` to connect to your new cluster.\n\n#### 3\\. Download Fugaci and Curie\n\nOn your macOS host, download the latest release of Fugaci and install the `curie` binary. https://github.com/macvmio/fugaci/releases/tag/v0.6.0\n\n\n#### 4\\. Generate Security Certificates\n\nFor your Mac node (let's call it `m1`) to securely join the cluster, it needs a key and certificate. A helper script is provided in the [Fugaci repository](https://www.google.com/search?q=https://github.com/macvmio/fugaci) to make this easy.\n\n```bash\n# Clone the Fugaci repo to get the helper script\ngit clone https://github.com/macvmio/fugaci\ncd fugaci\n\n# Run the script from inside the repo with your node name and its IP address\n./tools/generate-node-tls-certs.sh m1 \u003cFugaci Node IP address\u003e\n```\n\nThis will create `m1-crt.pem` and `m1-key.pem`. You will also need to copy the cluster's certificate authority file, located at `/var/lib/rancher/k3s/agent/client-ca.crt` on your `k3s` server, to your Fugaci node.\n\n#### 5\\. Add macOS VM SSH credentials for testing\n\n```\nkubectl create secret generic fugaci-ssh-secret \\\n  --from-literal=FUGACI_SSH_USERNAME=agent \\\n  --from-literal=FUGACI_SSH_PASSWORD=password\n```\n\n#### 6\\. Configure Fugaci\n\nCreate a configuration file for Fugaci at `/etc/fugaci/config.yaml`. This file tells Fugaci where to find everything it needs.\n\n```yaml\n# A unique name for your Mac node in the Kubernetes cluster\nnodeName: mac-m1\n\n# Path to the kubeconfig file you configured in step 2\nkubeConfigPath: /Users/your_username/.kube/config\n\n# Where to store logs from the macOS VMs\ncontainerLogsDirectory: /var/logs/fugaci \n\n# Settings for the 'curie' virtualization tool\ncurieVirtualization:\n  binaryPath: /usr/local/bin/curie\n  dataRootPath: /Users/your_username/.curie\n\n# The IP address of this Mac node, must be reachable from `k3s` VM\ninternalIP: 192.168.1.99\n\n# Paths to the security certificates you generated and copied\nTLS:\n  keyPath: /Users/your_username/.fugaci/m1-key.pem\n  certPath: /Users/your_username/.fugaci/m1-crt.pem\n  certificateAuthorityPath: /Users/your_username/.kube/client-ca.crt\n```\n\n**Note**: Make sure to replace `your_username` and the IP addresses with your actual information.\n\n#### 7\\. Start the Fugaci Daemon\n\nFinally, bootstrap and start the Fugaci service. This command will set up Fugaci to run automatically in the background.\n\n```bash\nsudo /usr/local/bin/fugaci daemon bootstrap\n```\n\n-----\n\n## Usage\n\nOnce Fugaci is running, your Mac will appear as a new node in your Kubernetes cluster. Fugaci applies a special **taint** to this node (`fugaci.macvm.io=true:NoSchedule`). This is a Kubernetes mechanism that prevents regular Linux workloads from being accidentally scheduled on your Mac.\n\nTo run a job on the Mac node, you need to add a corresponding **toleration** to your pod's configuration. This tells Kubernetes that your pod is \"aware\" of the taint and is allowed to run there.\n\n### Example: Scheduling a macOS Pod\n\nHere is a simple example of a Kubernetes pod designed to run a command inside a macOS VM.\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: macos-workload\nspec:\n  # This selector tells Kubernetes to only schedule this pod on a node\n  # that identifies as a 'darwin' (macOS) operating system.\n  nodeSelector:\n    kubernetes.io/os: darwin\n\n  # This toleration allows the pod to be scheduled on the Fugaci node,\n  # overriding the 'NoSchedule' taint.\n  tolerations:\n    - key: \"fugaci.macvm.io\"\n      operator: \"Equal\"\n      value: \"true\"\n      effect: \"NoSchedule\"\n\n  containers:\n    - name: macos-container\n      # This is the macOS VM image to run.\n      image: ghcr.io/macvmio/macos-sonoma:14.5-agent-v1.6\n      imagePullPolicy: IfNotPresent\n      # This secret should contain SSH credentials (user/password)\n      # that allow Kubernetes to execute commands inside the VM.\n      envFrom:\n        - secretRef:\n            name: fugaci-ssh-secret\n```\n#### Verification\n\nYou can verify by running `kubectl exec --stdin --tty macos-workload -- /bin/bash` and typing `sw_vers`\n\n\n-----\n\n## License\n\nFugaci is licensed under the Apache License 2.0. You are free to use, modify, and distribute the software. See the [LICENSE](https://www.google.com/search?q=LICENSE) file for more details.\n\n## Credits\n\nFugaci is developed and maintained by the team at [macvm.io](https://macvm.io). We welcome and appreciate contributions from the open-source community.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacvmio%2Ffugaci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacvmio%2Ffugaci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacvmio%2Ffugaci/lists"}