claudeers.
// DevOps & CI/CD

macbox

iOS Simulator on Linux: a full macOS VM in Docker with GPU acceleration (Metal via Reims vGPU), Xcode and a pool of iOS Simulators for AI coding agents (Clau…

// DevOps & CI/CD[ api ][ desktop ][ web ][ mobile ][ claude ]#claude#agent-skills#ai-agents#claude-code#codex#coding-agents#docker#docker-osx#devops◷ NOASSERTION$open-sourceupdated 14 days ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up macbox (git-clone project) into my current project.
Found on https://claudeers.com/macbox
Repo: https://github.com/TUNA-NOPE/macbox
Homepage/docs: https://tuna-nope.github.io/macbox/
Detected install method: git-clone → git clone https://github.com/TUNA-NOPE/macbox
Category: devops. Platforms: api, desktop, web, mobile.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or clone
git clone https://github.com/TUNA-NOPE/macbox

// compatibility

Platformsapi, desktop, web, mobile
Operating systems—
AI compatibilityclaude
LicenseNOASSERTION
Pricingopen-source
LanguageShell

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

macbox: macOS, Xcode and the iOS Simulator on Linux, GPU-accelerated, for AI coding agents

Run the real iOS Simulator on a Linux machine, without a Mac and without a cloud service. macbox runs a full macOS VM in Docker with real GPU acceleration (Metal, through Reims vGPU on your Vulkan GPU), with Xcode, a pool of iOS Simulators, T3 Code's Device panel, and the tools AI coding agents (Claude Code, Codex, T3 Code) need to build, run, drive and check iOS apps on their own. One command, macbox, sets it up and runs it.

Website and guides: tuna-nope.github.io/macbox: macOS, Xcode and the iOS Simulator on Linux, Expo apps, the GPU path, and AI coding agents with T3 Code.

The macOS 26 desktop in macbox on Linux: Simulator.app shows an iPhone 17 Pro running Nimbus, a weather app, next to Nimbus's website in Safari

macOS 26 Tahoe's desktop in macbox on an Intel iGPU, captured as it is: Simulator.app with an iPhone 17 Pro on iOS 26.5 running Nimbus, a weather app, beside its website in Safari.

Linux host (KVM + a Vulkan GPU + Docker)
└─ container macbox
   └─ QEMU with Reims vGPU ──► metal2vulkan ──► Vulkan (Mesa) on your GPU
      └─ macOS 26 Tahoe (x86-64), drawn with Metal
         ├─ Xcode, CocoaPods, Node
         ├─ iOS Simulators: a pool, one per agent checkout (mac-sim)
         └─ T3 Code's device hub (Intel build)  ──► the Device panel, live
  • macOS draws on your GPU. Reims vGPU gives QEMU Apple's paravirtual GPU, and macOS's own driver talks to it, so Metal works with no guest driver. metal2vulkan runs Metal's work on Vulkan. macbox builds both, with patches that took a 3x iOS Simulator from 17 to 50 fps on the GPU it was measured on, and to 70 with the experimental Coherent switch (see Performance).
  • The screen opens in a window on your Linux desktop, or in a browser tab (Selkies: H.264 on the GPU, its bitrate following the link). Agents can see it and click and type into it (macbox screenshot, click, type), so an agent can drive the macOS installer too.
  • iOS Simulators for agents. mac-sim gives each checkout its own simulator from a pool: slim ones for most work, a full one for widgets, Live Activities and the Dynamic Island, a sharp one for real-iPhone pixels. It builds the app on the Mac, runs Metro on the host, taps, types, takes lossless screenshots and records video. sim-fps checks that a recording held 60 fps with no dropped frames. A skill (skills/simulators) teaches Claude Code and Codex to use it after every UI change.
  • T3 Code. macbox t3 register adds the VM to T3 Code's Device panel, and macbox t3 fix-hub rebuilds T3's device hub for Intel, so the panel streams the simulator live and takes taps.
  • Android too, optionally: android-sim runs a pool of Android emulators on the host itself.

What you need

CPUx86-64 with VT-x or AMD-V, and AVX2
GPUone with a Mesa Vulkan driver: Intel (measured: Arrow Lake iGPU) or AMD (supported by Reims, untested here). NVIDIA works with Reims but macbox's image doesn't ship NVIDIA's driver yet
RAM16 GB or more (the VM takes 8 to 16)
Diskabout 150 GB free, on an SSD or NVMe
OSLinux with KVM (/dev/kvm), a render node (/dev/dri/renderD*), Docker (rootless is fine) or Podman

macOS for Intel ends with macOS 26 Tahoe, and Apple ships iOS 27's simulators for Apple silicon only. So macbox runs macOS 26, Xcode 26 and iOS 26 simulators, and that is the ceiling on x86-64.

Quick start

git clone <this repo> macbox && cd macbox
./macbox init         # config in ~/.config/macbox/macbox.env, an SSH key, the ssh alias "macbox"
./macbox doctor       # checks KVM, the GPU, vm.max_map_count, Docker, disk space
./macbox build        # the image, then Reims vGPU + metal2vulkan + QEMU (20 to 60 minutes)
./macbox create       # a VM; macOS downloads from Apple
./macbox up           # then open http://127.0.0.1:6081/ (or: ./macbox view local)
./macbox next         # what's done and the next step, until everything is ticked

Installing macOS takes a few steps inside the VM: erase the disk and install, set Metal's error mode once from Recovery, create a user, turn on SSH. macbox next prints each one, and docs/setup.md walks through all of it. After that it's commands again:

./macbox provision                    # passwordless sudo, no sleep, Node, Ruby + CocoaPods, simslim...
./macbox xcode ~/Downloads/Xcode_26.6.xip   # Xcode and the iOS Simulator runtime
./macbox disk nvme                    # the system disk on NVMe (faster)
./macbox pool                         # the iOS Simulator pool
./macbox t3 register                  # T3 Code's Device panel (then: macbox t3 fix-hub)
./macbox agents install               # mac-sim, sim-fps, android-sim, the skills

Setting up with an agent: point it at AGENTS.md.

Performance

Measured on an Intel Core Ultra 7 265 (its Arrow Lake iGPU), Mesa 26.2.4, macOS 26.7.1, iOS 26.5, 8 vCPUs and 12 GB. GlassBench is a table scrolling under Liquid Glass bars and a floating glass toolbar, counted at the simulator's own screen (frames per second; two runs).

iOS Simulator at 3x, Liquid Glass benchmark: 17.2 fps as upstream shipped it, 39.0 with the October 28 macbox build, 50.6 with the cohwl build, 70.0 with Coherent on
iOS Simulator at 3x (1206x2622, an iPhone's pixels), glassfps
Reims 2ce3209, as upstream shipped it on 2026-10-2617.2
macbox, 2026-10-28: rendering guest-RAM textures in place38.5 / 39.5
macbox build now (cohwl, 2026-11-05)50.6 (p95 21 ms)
macbox build with MACBOX_COHERENT=on (experimental)70.0 (p95 18 ms)
Reims 2ce3209macbox, 2026-10-28macbox now, Coherent on
iOS Simulator 1x (402x874), glass53.595.8 / 92.5not measured yet
iOS Simulator 2x (804x1748), glass33.567.8 / 60.5not measured yet
macOS desktop, dragging a window (presents/s)105 (Coherent off)130
macOS desktop, Safari scrolling (presents/s)75–79 (Coherent off)110
macOS desktop, Genie minimize at 3440x1440 (frames per animation)~1219.529.5 / 30.5

Coherent keeps the GPU's image of the simulator's and the desktop's surfaces ahead of guest RAM, and syncs a page only when the guest's CPU touches it: the copies that were left are gone, and the GPU drops from 97% to 70% busy at 3x. It is off by default for now: it hung the GPU once on its first day of daily use (the next boot came up without it, as designed), and the cause isn't settled. docs/performance.md has the details.

The GPU is the limit: without Coherent a 3x simulator keeps this iGPU 96 to 98% busy. On a faster GPU every number moves up. docs/performance.md has what the patches do, the method, what didn't help, and the known limits (an idle macOS display gets no vblank from its driver, so an animation starts about 0.1 s late: reims-vgpu#141).

Questions people ask

Can I run the iOS Simulator on Linux? Not by itself: it's part of Xcode, which needs macOS. macbox runs macOS in a VM on Linux with the GPU attached, so the real Simulator runs on your own machine, with no Mac, no cloud account and no per-minute bill.

How do I give Claude Code or Codex an iOS Simulator on a Linux server? Set up macbox, then macbox agents install. Agents get mac-sim (a simulator per checkout: build, run, tap, screenshot, record), sim-fps (did that animation hold 60 fps?), and a skill that tells them when and how to use them. docs/agents.md.

Docker-OSX or OSX-KVM, but with GPU acceleration? Those boot macOS in QEMU too, but macOS gets Metal only when you pass a GPU it has drivers for through to the VM (VFIO), which takes that GPU away from the host. Otherwise the desktop and the Simulator draw in software. macbox uses Reims vGPU instead: Apple's own paravirtual GPU device, run on the host's Vulkan driver. The host keeps its GPU, macOS gets Metal, and an integrated GPU is enough.

Can I build and run an Expo or React Native iOS app on Linux? Yes. mac-sim run copies the checkout into macOS, builds it with Xcode and CocoaPods, and installs it in the simulator. Metro runs on Linux, so JavaScript edits arrive by Fast Refresh. MODE=release gives a Release build, and MODE=go opens the app in Expo Go.

Does it work with T3 Code's Device panel? Yes: the simulators stream live into the panel and take taps (docs/t3-code.md).

Real iPhones and TestFlight? phone-build makes .ipa builds (EAS's free cloud builds first, then locally in the VM) and uploads to TestFlight. Signing for devices needs Apple's paid Developer Program (skills/phone-builds).

What can't it do? Run macOS 27, Xcode 27 or iOS 27's simulators, which Apple ships for Apple silicon only. It also can't run macOS legally on non-Apple hardware (see below).

How it compares

macboxDocker-OSX, OSX-KVMCloud simulatorsA Mac, or a remote Mac
Runs onyour Linux hostyour Linux hostthe provider's Macsa Mac
Metal in macOSyes, on the host's GPU through Vulkanonly with a GPU passed through to the VMyesyes
Costyour hardwareyour hardwareusually per minute or a planthe Mac
Built for agents (a simulator per checkout, screenshots, recordings, a 60 fps check, a skill)yesnovarieswith tools such as agent-device
Newest iOS Simulator26.x (the x86-64 ceiling)26.xthe newestthe newest
Apple's macOS licensenot on non-Apple hardwarenot on non-Apple hardwareyesyes

Contributions welcome

macbox is open to ideas, fixes, and improvements of every kind. If you're using it and find a bug, have a feature request, add support for something new, make it faster, improve the docs, or build your own enhancement, please share it. Big changes, small fixes, experimental solutions, and reports of what didn't work are all valuable.

Open an issue to report a problem, suggest an idea, or share your findings. If you've already built a solution, open a pull request so we can review it for inclusion. You don't need a finished implementation to start a conversation.

Using an AI coding agent? Contributions from agent-assisted workflows are welcome too. If your agent finds a problem or creates a useful improvement, ask it to prepare an issue or PR. See CONTRIBUTING.md for a few simple guidelines.

Docs

docs/setup.mda new install, step by step
docs/architecture.mdhow the parts fit: container, QEMU, display, network, guest, simulators, T3
docs/performance.mdthe GPU patches, measurements, tuning, limits
docs/t3-code.mdT3 Code's Device panel for iOS and Android
docs/agents.mdthe agent tools, the skill, the instructions to give agents
docs/troubleshooting.mdwhen something doesn't work
guest/README.mdwhat runs inside macOS
patches/README.mdthe patch series on Reims vGPU, metal2vulkan and QEMU
site/the website's source: the guides at https://tuna-nope.github.io/macbox/guides/

Credits

macbox is glue and tuning around other people's work, above all Reims vGPU, metal2vulkan, reims-util and their QEMU fork by Anees Iqbal (steelbrain). CREDITS.md lists every project macbox builds, runs or downloads, and its license.

License

macbox's own code and documents are under the PolyForm Noncommercial License 1.0.0. Use it, change it and share it for any noncommercial purpose: yourself, a hobby, research, teaching, a school, a charity, a public body. Commercial use needs the author's permission: open an issue to ask.

The patches in patches/ modify Reims vGPU and metal2vulkan, and stay under those projects' terms, GPL-2.0-or-later OR LGPL-3.0-or-later; those in patches/qemu modify QEMU and are GPL-2.0-or-later (patches/README.md). Everything macbox builds or downloads keeps its own license (CREDITS.md).

Disclaimer

macbox comes as is, with no warranty of any kind, and its authors accept no liability for anything that comes of using it (the license's "No Liability" section). It runs a virtual machine with direct access to your GPU, and can lose the VM's data, for example with MACBOX_DISK_CACHE=unsafe and a crash of the host.

macbox ships no Apple software. macOS, Xcode and the simulator runtimes download from Apple, under Apple's terms, and you alone are responsible for complying with them. Apple's software license agreement for macOS allows it to run only on Apple-branded hardware; running it in a VM on other hardware breaches that agreement. macbox is not affiliated with, sponsored or endorsed by Apple Inc. macOS, iOS, Xcode and Metal are trademarks of Apple Inc.

// faq

What is macbox?

iOS Simulator on Linux: a full macOS VM in Docker with GPU acceleration (Metal via Reims vGPU), Xcode and a pool of iOS Simulators for AI coding agents (Claude Code, Codex, T3 Code). Build and test Expo / React Native iOS apps without a Mac or a cloud service.. It is open-source on GitHub.

Is macbox free to use?

macbox is open-source under the NOASSERTION license, so it is free to use.

What category does macbox belong to?

macbox is listed under devops in the Claudeers registry of Claude-compatible tools.

18 views
★ 10 stars
unclaimed
updated 14 days ago

// embed badge

macbox on Claudeers
[![Claudeers](https://claudeers.com/api/badge/macbox.svg)](https://claudeers.com/macbox)

// retro hit counter

macbox hit counter
[![Hits](https://claudeers.com/api/counter/macbox.svg)](https://claudeers.com/macbox)

// reviews

// guestbook

0/500

// related in DevOps & CI/CD

🔓

⭐AI-driven public opinion & trend monitor with multi-platform aggregation, RSS, and smart alerts.🎯 告别信息过载,你的 AI 舆情监控助手与热点筛选工具!聚合多平台热点 + RSS 订阅,支持关键词精准筛选。AI…

// devopssansan0/⟨Python⟩★ 63,435◷ GPL-3.0[ claude ]
🔓

Use Claude Code as the foundation for coding infrastructure, allowing you to decide how to interact with the model while enjoying updates from Anthropic.

// devopsmusistudio/⟨TypeScript⟩★ 38,038◷ MIT[ claude ]
🔓

Professional Antigravity Account Manager & Switcher. One-click seamless account switching for Antigravity Tools. Built with Tauri v2 + React (Rust).专业的 Antig…

// devopslbjlaq/⟨Rust⟩★ 33,402◷ NOASSERTION[ claude ]
→ see how macbox connects across the ecosystem