diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..b88edc6 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,59 @@ +# Builds the website (site/) and publishes it to GitHub Pages: https://tuna-nope.github.io/macbox/ +# Pull requests only build and check it; pushes to main deploy it, then tell IndexNow (Bing and +# others) which pages exist. Google reads the sitemap through Search Console. +name: Website + +on: + push: + branches: [main] + paths: ["site/**", "docs/images/**", "llms.txt", "macbox", "sims/bin/mac-sim", ".github/workflows/pages.yml"] + pull_request: + paths: ["site/**", "docs/images/**", "llms.txt", "macbox", "sims/bin/mac-sim", ".github/workflows/pages.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: pages-${{ github.ref }} + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-python@v7 + with: + python-version: "3.13" + - name: Build and check + run: python3 site/build.py + - uses: actions/upload-pages-artifact@v5 + if: github.event_name != 'pull_request' + with: + path: site/_site + + deploy: + if: github.event_name != 'pull_request' + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v5 + - name: Submit the sitemap's URLs to IndexNow + continue-on-error: true + env: + SITE: https://tuna-nope.github.io/macbox + KEY: d0f80829b645869eb473963b6ad2dd95 + run: | + sleep 30 # let the new deployment reach the CDN + urls=$(curl -fsS "$SITE/sitemap.xml" | grep -o '[^<]*' | sed 's///' | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read().split()))') + body=$(printf '{"host":"tuna-nope.github.io","key":"%s","keyLocation":"%s/%s.txt","urlList":%s}' "$KEY" "$SITE" "$KEY" "$urls") + curl -sS -o /dev/null -w 'IndexNow: HTTP %{http_code}\n' -X POST https://api.indexnow.org/indexnow \ + -H 'Content-Type: application/json; charset=utf-8' -d "$body" diff --git a/README.md b/README.md index aea215a..c7fd14c 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,9 @@ your Vulkan GPU), with Xcode, a pool of iOS Simulators, T3 Code's Device panel, 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](https://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 desktop in macbox, with two iOS 26.5 Simulators: a Liquid Glass benchmark at 1x and Safari](docs/images/hero.jpg) macOS 26 Tahoe's desktop in macbox on an Intel iGPU, with two of its iOS 26.5 Simulators in front @@ -159,6 +162,7 @@ silicon only. It also can't run macOS legally on non-Apple hardware (see below). | [docs/troubleshooting.md](docs/troubleshooting.md) | when something doesn't work | | [guest/README.md](guest/README.md) | what runs inside macOS | | [patches/README.md](patches/README.md) | the patch series on Reims vGPU and metal2vulkan | +| [site/](site/README.md) | the website's source: the guides at https://tuna-nope.github.io/macbox/guides/ | ## Credits diff --git a/llms.txt b/llms.txt index dfc54a5..27828c2 100644 --- a/llms.txt +++ b/llms.txt @@ -26,3 +26,16 @@ Requirements: an x86-64 Linux host with KVM, AVX2, an Intel or AMD GPU with a Me - [Patches](https://github.com/TUNA-NOPE/macbox/blob/main/patches/README.md) - [Troubleshooting](https://github.com/TUNA-NOPE/macbox/blob/main/docs/troubleshooting.md) - [Credits](https://github.com/TUNA-NOPE/macbox/blob/main/CREDITS.md) + +## Website + +The same project as a website, with task guides. Each page has a Markdown copy at `index.md` in the same folder. + +- [Overview](https://tuna-nope.github.io/macbox/index.md): what macbox is, features, measured performance, comparison, requirements, quick start +- [How to run macOS on Linux with GPU acceleration](https://tuna-nope.github.io/macbox/guides/run-macos-on-linux/index.md) +- [How to run Xcode on Linux](https://tuna-nope.github.io/macbox/guides/xcode-on-linux/index.md) +- [iOS Simulator on Linux](https://tuna-nope.github.io/macbox/guides/ios-simulator-on-linux/index.md) +- [Expo and React Native iOS apps on Linux](https://tuna-nope.github.io/macbox/guides/expo-react-native-ios-on-linux/index.md) +- [iOS Simulators for AI coding agents: Claude Code, Codex, T3 Code](https://tuna-nope.github.io/macbox/guides/ios-simulator-for-ai-coding-agents/index.md) +- [GPU-accelerated macOS VM on Linux, without passthrough](https://tuna-nope.github.io/macbox/guides/gpu-accelerated-macos-vm-on-linux/index.md) +- [macbox vs Docker-OSX and OSX-KVM](https://tuna-nope.github.io/macbox/guides/macbox-vs-docker-osx-and-osx-kvm/index.md) diff --git a/site/.gitignore b/site/.gitignore new file mode 100644 index 0000000..57510a2 --- /dev/null +++ b/site/.gitignore @@ -0,0 +1 @@ +_site/ diff --git a/site/README.md b/site/README.md new file mode 100644 index 0000000..42fbbe3 --- /dev/null +++ b/site/README.md @@ -0,0 +1,32 @@ +# The website + +The source of https://tuna-nope.github.io/macbox/, built by `build.py` (Python's standard library, +nothing to install) and published to GitHub Pages by `.github/workflows/pages.yml` on every push +to main that touches it. + +```sh +python3 site/build.py # build into site/_site and check it +python3 site/build.py --serve # the same, then http://127.0.0.1:8000/macbox/ +``` + +| | | +|---|---| +| `pages/` | one HTML fragment per page. A header of `key: value` lines, then `---`. The file's path is the URL: `pages/guides/xcode-on-linux.html` is `/guides/xcode-on-linux/` | +| `layout.html`, `style.css` | the frame around every page; the CSS is inlined | +| `static/` | copied as is: the favicon, the IndexNow key, search engines' verification files, and the home page's pictures in `static/images/`: `desk-*` is a real, uncropped capture of the macOS VM's whole screen (1600x1200: Simulator.app running Nimbus, a demo weather app made for these pictures, next to its website in Safari), saved as `-quality 84 desk-1600.webp`, `-resize 800x -quality 82 desk-800.webp` and `-quality 84 -interlace JPEG desk-1600.jpg`; `phone-today.webp` and `phone-cities.webp` are Nimbus's two screens from `mac-sim shot` on the 3x `sharp` simulator, `-resize 600x -quality 86`. The logos on the home page are inline SVG: Claude's from Simple Icons, OpenAI's and T3 Code's from T3 Code's repository) | + +The repo stays the source of truth. The guides answer one question each and link to `docs/` for the +full reference; pictures (`docs/images`) and `llms.txt` are copied from the repo at build time, not +kept twice. When a command or a number changes in the docs, change it in the guides that show it. + +**Adding a guide:** a new file in `pages/guides/` with `title`, `short` (the breadcrumb), +`description` (50 to 165 characters, unique), `kind: guide`, `order` and `updated: YYYY-MM-DD`. +The guide lists, the sitemap and the structured data pick it up. Add it to `llms.txt` too. + +**The build fails on:** a broken internal link or `#anchor`, a missing or duplicate title or +description, a page without exactly one `

`, and a `macbox ` or `mac-sim ` in +a code sample that the CLI doesn't have. + +Every page also gets a Markdown copy (`index.md` beside `index.html`) for language models, as +llmstxt.org suggests. robots.txt can't be set here: crawlers read it only at the host's root +(`tuna-nope.github.io/robots.txt`), which this repo doesn't control. Pages carry robots meta tags. diff --git a/site/build.py b/site/build.py new file mode 100644 index 0000000..5df4a0f --- /dev/null +++ b/site/build.py @@ -0,0 +1,373 @@ +#!/usr/bin/env python3 +"""Builds macbox's website (GitHub Pages) into site/_site. Standard library only. + + python3 site/build.py build, then check the output (fails on any problem) + python3 site/build.py --serve build, then serve it at http://127.0.0.1:8000/macbox/ (PORT=... for another port) + +Pages are HTML fragments in site/pages/, each with a header of `key: value` lines ended by `---` +(title, description, and for guides: kind: guide, short, updated). A page's URL is its path: +pages/guides/xcode-on-linux.html -> /guides/xcode-on-linux/. Links inside pages are written from +the site's root (href="/guides/"); the build prefixes BASE_PATH. Pictures and llms.txt come +from the repo itself (docs/images, llms.txt), so they have one source. +""" +import datetime, html, json, os, re, shutil, sys +from pathlib import Path + +SITE_URL = os.environ.get("MACBOX_SITE_URL", "https://tuna-nope.github.io/macbox").rstrip("/") +BASE_PATH = "/" + SITE_URL.split("://", 1)[1].partition("/")[2] if "/" in SITE_URL.split("://", 1)[1] else "" +BASE_PATH = BASE_PATH.rstrip("/") +REPO_URL = "https://github.com/TUNA-NOPE/macbox" +NAME = "macbox" + +HERE = Path(__file__).resolve().parent +ROOT = HERE.parent +OUT = HERE / "_site" +FROM_REPO = { # repo file -> path in the site + "docs/images/social-preview.jpg": "images/social-preview.jpg", + "docs/images/fps-light.svg": "images/fps-light.svg", + "docs/images/fps-dark.svg": "images/fps-dark.svg", + "llms.txt": "llms.txt", +} +NAV = [("/", "Overview"), ("/guides/", "Guides"), ("/#performance", "Performance"), + (REPO_URL + "/blob/main/docs/setup.md", "Docs")] + + +def read_page(path): + text = path.read_text() + head, sep, body = text.partition("\n---\n") + if not sep: + sys.exit(f"{path}: no header (key: value lines, then ---)") + meta = dict(line.split(": ", 1) for line in head.strip().splitlines()) + rel = path.relative_to(HERE / "pages").with_suffix("") + if rel.name == "index": + url = "/" + (str(rel.parent) + "/" if str(rel.parent) != "." else "") + elif rel.name == "404": + url = "/404.html" + else: + url = f"/{rel}/" + meta.update(url=url, body=body, src=path) + return meta + + +def link(url): # a path from the site's root -> one under BASE_PATH + return BASE_PATH + url + + +def absolute(url): + return SITE_URL + url + + +def json_ld(page, guides): + graph = [] + crumbs = [("/", "macbox")] + if page["url"] == "/": + graph.append({ + "@type": "WebSite", "@id": absolute("/#website"), "url": absolute("/"), "name": NAME, + "description": page["description"], "inLanguage": "en"}) + graph.append({ + "@type": "SoftwareSourceCode", "@id": absolute("/#software"), "name": NAME, + "description": page["description"], "url": absolute("/"), "codeRepository": REPO_URL, + "programmingLanguage": ["Bash", "Python", "Swift"], "runtimePlatform": "Linux (x86-64, KVM, Docker)", + "targetProduct": {"@type": "SoftwareApplication", "name": NAME, "operatingSystem": "Linux", + "applicationCategory": "DeveloperApplication"}, + "license": "https://polyformproject.org/licenses/noncommercial/1.0.0/", + "image": absolute("/images/social-preview.jpg")}) + return graph + if page.get("kind") == "guide": + crumbs.append(("/guides/", "Guides")) + graph.append({ + "@type": "TechArticle", "headline": page["title"], "description": page["description"], + "url": absolute(page["url"]), "mainEntityOfPage": absolute(page["url"]), + "datePublished": page["published"] + "T00:00:00Z", "dateModified": page["updated"] + "T00:00:00Z", + "inLanguage": "en", "image": absolute("/images/social-preview.jpg"), + "author": {"@type": "Organization", "name": "macbox", "url": REPO_URL}, + "about": {"@type": "SoftwareSourceCode", "@id": absolute("/#software"), "name": NAME, + "codeRepository": REPO_URL, "url": absolute("/")}, + "isPartOf": {"@type": "WebSite", "@id": absolute("/#website"), "name": NAME, "url": absolute("/")}}) + crumbs.append((page["url"], page.get("short", page["title"]))) + graph.append({"@type": "BreadcrumbList", "itemListElement": [ + {"@type": "ListItem", "position": i + 1, "name": n, "item": absolute(u)} for i, (u, n) in enumerate(crumbs)]}) + return graph + + +def guide_list(guides, exclude=None): + items = [] + for g in guides: + if g["url"] == exclude: + continue + items.append(f'
  • {html.escape(g["title"])}' + f'{html.escape(g["description"])}
  • ') + return '
      ' + "".join(items) + "
    " + + +def render(page, guides, layout, css): + body = page["body"].replace("{{guides}}", guide_list(guides)) + body = re.sub(r"&(?![a-zA-Z]+;|#\d+;|#[xX][0-9a-fA-F]+;)", "&", body) # `&&` in commands, written plainly in the pages + body = re.sub(r".*?", lambda m: m.group(0).replace("", '').replace('.*?", lambda m: m.group(0).replace("", ''), body, flags=re.S) + is_guide = page.get("kind") == "guide" + if is_guide: + crumbs = (f'') + updated = page["updated"] + stamp = (f'

    Updated · ' + f'Source of truth: the repository and its docs

    ') + body = body.replace("

    ", crumbs + "

    ", 1).replace("{{meta}}", stamp, 1) + body += ('") + current = ' aria-current="page"' + nav = "".join(f'{n}' for u, n in NAV) + title = page["title"] if page["url"] == "/" else f'{page["title"]} · macbox' + ld = json.dumps({"@context": "https://schema.org", "@graph": json_ld(page, guides)}, ensure_ascii=False) \ + if page["url"] != "/404.html" else None + out = (layout + .replace("{{css}}", css) + .replace("{{title}}", html.escape(title)) + .replace("{{description}}", html.escape(page["description"], quote=True)) + .replace("{{og_type}}", "article" if is_guide else "website") + .replace("{{robots}}", "noindex" if page["url"] == "/404.html" else "index, follow, max-image-preview:large") + .replace("{{verification}}", verification_meta()) + .replace("{{markdown}}", f'' + if page["url"].endswith("/") else "") + .replace("{{json_ld}}", f'' if ld else "") + .replace("{{nav}}", nav) + .replace("{{repo}}", REPO_URL) + .replace("{{year}}", str(datetime.date.today().year)) + .replace("{{body}}", body)) + canonical = absolute(page["url"]) if page["url"] != "/404.html" else "" + out = out.replace("{{canonical}}", f'' if canonical else "") + out = out.replace("{{url}}", canonical or SITE_URL + "/") + out = out.replace("{{site}}", SITE_URL) + # links from the site's root get the base path; external and #-links stay as they are + out = re.sub(r'(href|src)="/(?!/)', lambda m: f'{m.group(1)}="{BASE_PATH}/', out) + # srcset holds a list ("/a.webp 800w, /b.webp 1600w"): prefix every candidate, not just the first + out = re.sub(r'srcset="([^"]+)"', lambda m: 'srcset="' + re.sub(r'(^|,\s*)/(?!/)', rf'\1{BASE_PATH}/', m.group(1)) + '"', out) + return out + + +def verification_meta(): + tags = [] + for env, name in (("GOOGLE_SITE_VERIFICATION", "google-site-verification"), ("BING_SITE_VERIFICATION", "msvalidate.01")): + token = (HERE / "verification" / env.lower()).read_text().strip() if (HERE / "verification" / env.lower()).exists() else "" + if token: + tags.append(f'') + return "".join(tags) + + +class Markdown(__import__("html.parser").parser.HTMLParser): + """The subset of HTML the pages use -> Markdown, for the .md copy of each page (llmstxt.org).""" + BLOCK = {"p", "h1", "h2", "h3", "li", "pre", "summary", "figcaption", "details", "div", "figure"} + + def __init__(self): + super().__init__(convert_charrefs=True) + self.out, self.href, self.lists, self.pre, self.cells, self.row, self.skip = [], [], [], False, None, 0, 0 + + def handle_starttag(self, tag, attrs): + a = dict(attrs) + if tag in ("script", "style", "svg") or (tag == "nav" and a.get("class") == "crumbs"): + self.skip += 1 + if self.skip: + return + if tag in self.BLOCK or tag in ("ul", "ol", "table"): + self.out.append("\n\n") + if tag in ("h1", "h2", "h3"): + self.out.append("#" * int(tag[1]) + " ") + elif tag in ("ul", "ol"): + self.lists.append([tag, 0]) + elif tag == "li": + kind = self.lists[-1] if self.lists else ["ul", 0] + kind[1] += 1 + self.out[-1] = "\n" + " " * (len(self.lists) - 1) + self.out.append(f"{kind[1]}. " if kind[0] == "ol" else "- ") + elif tag == "pre": + self.pre = True + self.out.append("```sh\n") + elif tag == "code" and not self.pre: + self.out.append("`") + elif tag in ("strong", "b") and not self.pre: + self.out.append("**") + elif tag == "a": + self.href.append(a.get("href", "")) + self.out.append("[") + elif tag == "img" and a.get("alt"): + self.out.append(f"![{a['alt']}]({a.get('src', '')})") + elif tag == "tr": + self.cells, self.row_start = [], len(self.out) + elif tag in ("td", "th") and self.cells is not None: + self.out.append("\x00") + elif tag == "summary": + self.out.append("### ") + + def handle_endtag(self, tag): + if tag in ("script", "style", "svg", "nav") and self.skip: + self.skip -= 1 + return + if self.skip: + return + if tag in ("ul", "ol") and self.lists: + self.lists.pop() + elif tag == "pre": + self.pre = False + self.out.append("\n```\n\n") + elif tag == "code" and not self.pre: + self.out.append("`") + elif tag in ("strong", "b") and not self.pre: + self.out.append("**") + elif tag == "a" and self.href: + self.out.append(f"]({self.href.pop()})") + elif tag == "tr": + text = "".join(self.out[self.row_start:]) + cells = [c.strip().replace("\n", " ").replace("|", "\\|") for c in text.split("\x00")[1:]] + del self.out[self.row_start:] + line = "| " + " | ".join(cells) + " |" + if self.row == 0: + line += "\n|" + "---|" * len(cells) + self.row += 1 + self.out.append(line + "\n") + self.cells = None + elif tag == "table": + self.row = 0 + + def handle_data(self, data): + if self.skip: + return + self.out.append(data if self.pre else re.sub(r"\s+", " ", data)) + + def text(self): + md = "".join(self.out) + md = re.sub(r"\n[ \t]+\n", "\n\n", md) + md = re.sub(r"\n{3,}", "\n\n", md) + lines, fenced = [], False + for line in md.strip().splitlines(): + if line.startswith("```"): + fenced = not fenced + elif not fenced and not re.match(r"\s+(- |\d+\. )", line): + line = line.lstrip() + lines.append(line.rstrip()) + return re.sub(r"\n{3,}", "\n\n", "\n".join(lines)) + "\n" + + +def markdown_copy(page, rendered_body): + m = Markdown() + m.feed(rendered_body) + head = f"\n\n" + return head + m.text() + + +def sitemap(pages): + rows = [] + rank = lambda p: (p["url"] != "/", p["url"] != "/guides/", int(p.get("order", 99)), p["url"]) + for p in sorted(pages, key=rank): + if p["url"] == "/404.html": + continue + rows.append(f" {absolute(p['url'])}{p['updated']}") + return ('\n\n' + + "\n".join(rows) + "\n\n") + + +def build(): + pages = [read_page(p) for p in sorted((HERE / "pages").rglob("*.html"))] + for p in pages: + p.setdefault("updated", "2026-10-29") + p.setdefault("published", p["updated"]) + guides = sorted((p for p in pages if p.get("kind") == "guide"), key=lambda p: int(p.get("order", 99))) + layout = (HERE / "layout.html").read_text() + css = (HERE / "style.css").read_text() + css = re.sub(r"/\*.*?\*/", "", css, flags=re.S) + css = re.sub(r"\s*\n\s*", "\n", css).strip() + if OUT.exists(): + shutil.rmtree(OUT) + OUT.mkdir() + for p in pages: + dest = OUT / (p["url"].lstrip("/") + ("index.html" if p["url"].endswith("/") else "")) + dest.parent.mkdir(parents=True, exist_ok=True) + page_html = render(p, guides, layout, css) + dest.write_text(page_html) + if p["url"].endswith("/"): + main = page_html.split('
    ', 1)[1].split("
    ", 1)[0] + main = re.sub(r'(href|src)="/(?!/)', lambda m: f'{m.group(1)}="{SITE_URL[:-len(BASE_PATH)] if BASE_PATH else SITE_URL}/', main) + (dest.parent / "index.md").write_text(markdown_copy(p, main)) + for src, dst in FROM_REPO.items(): + (OUT / dst).parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(ROOT / src, OUT / dst) + shutil.copytree(HERE / "static", OUT, dirs_exist_ok=True) + (OUT / "sitemap.xml").write_text(sitemap(pages)) + (OUT / ".nojekyll").write_text("") + return pages + + +# ---- checks: run on every build, so a broken link or a command that doesn't exist fails CI ---- + +def cli_commands(script): # the subcommands a script's top-level `case` dispatches + found = re.findall(r"^ ([a-z0-9|-]+)\) ?", (ROOT / script).read_text(), flags=re.M) + return {w for line in found for w in line.split("|")} + + +def check(pages): + problems = [] + seen_titles, seen_desc = {}, {} + macbox_cmds = cli_commands("macbox") + macsim_cmds = cli_commands("sims/bin/mac-sim") + files = {str(f.relative_to(OUT)) for f in OUT.rglob("*") if f.is_file()} + for p in pages: + for key in ("title", "description"): + if key not in p: + problems.append(f"{p['src'].name}: no {key}") + if not 50 <= len(p.get("description", "")) <= 165: + problems.append(f"{p['src'].name}: description is {len(p.get('description', ''))} characters (50 to 165)") + for key, seen in (("title", seen_titles), ("description", seen_desc)): + if p.get(key) in seen: + problems.append(f"{p['src'].name}: same {key} as {seen[p[key]]}") + seen[p.get(key)] = p["src"].name + if p["url"] != "/404.html" and p["body"].count("") + # every command the page shows must exist in the CLI it names + for block in re.findall(r"]*>(.*?)", p["body"], flags=re.S): + text = html.unescape(re.sub(r"<[^>]+>", "", block)) + for tool, known in (("macbox", macbox_cmds), ("mac-sim", macsim_cmds)): + # in command position: a line's start, after && ; | & or ./ (not `ssh macbox ...`, the SSH alias) + pattern = rf"(?:^|&&|;|\||&|\./)\s*(? + + + + +{{title}} + + +{{canonical}} + + + + + +{{markdown}} + + + + + + + + + + +{{verification}} +{{json_ld}} + + + + +
    +
    + macbox + + GitHub +
    +
    +
    +{{body}} +
    + + + + diff --git a/site/pages/404.html b/site/pages/404.html new file mode 100644 index 0000000..3bae94d --- /dev/null +++ b/site/pages/404.html @@ -0,0 +1,13 @@ +title: Page not found +description: This page doesn't exist on macbox's site. Try the guides, or the repository on GitHub, for macOS, Xcode and the iOS Simulator on Linux. +--- +
    +

    404

    +

    That page isn't here

    +

    It may have moved. Everything macbox has is one of these:

    + +
    diff --git a/site/pages/guides/expo-react-native-ios-on-linux.html b/site/pages/guides/expo-react-native-ios-on-linux.html new file mode 100644 index 0000000..3e737aa --- /dev/null +++ b/site/pages/guides/expo-react-native-ios-on-linux.html @@ -0,0 +1,76 @@ +title: Build and Test Expo and React Native iOS Apps on Linux +short: Expo and React Native iOS on Linux +description: Build an Expo or React Native iOS app on Linux and run it in the real iOS Simulator, with Metro and Fast Refresh on Linux, Release builds and Expo Go. +kind: guide +order: 4 +--- +
    +

    Build and test Expo and React Native iOS apps on Linux

    +

    Expo and React Native let you write an iOS app on Linux, but building and running it needs Xcode, which needs macOS. With macbox, one command copies your checkout into a macOS VM on the same machine, builds it there with Xcode and CocoaPods, and opens it in a real iOS Simulator, while Metro keeps running on Linux.

    +{{meta}} +
    +

    In short

    +
      +
    • mac-sim up && mac-sim run from the app's checkout: a Debug build in the simulator, with Fast Refresh from Linux.
    • +
    • MODE=release mac-sim run for a Release build; MODE=go mac-sim run for Expo Go.
    • +
    • The first build takes 2 to 15 minutes; later ones are incremental.
    • +
    +
    + +

    Before you start

    +
      +
    • A macbox VM with Xcode and the simulator pool, and the agent tools installed: macOS on Linux, Xcode on Linux, then ./macbox pool and ./macbox agents install.
    • +
    • The app's dependencies installed on Linux too (npm install, bun install, …), because Metro runs there.
    • +
    + +

    Run the app

    +
    cd ~/code/my-app
    +mac-sim up                    # claim a simulator for this checkout and boot it
    +mac-sim run                   # build on the Mac, install, open; Metro runs here
    +mac-sim shot /tmp/home.png    # look at it
    +

    What mac-sim run does:

    +
      +
    1. Copies the checkout to the Mac, without node_modules, .git and generated ios/ and android/ folders. Uncommitted changes are included; nothing needs to be pushed. A gitignored .env is copied too.
    2. +
    3. Installs dependencies there with the project's package manager, and runs expo prebuild and pod install when the app config or dependencies changed.
    4. +
    5. Builds with xcodebuild for that simulator (x86_64, since the VM is an Intel Mac), installs and opens the app.
    6. +
    7. Starts Metro on Linux from your checkout. The app reaches it through an SSH tunnel, so saving a file updates the app by Fast Refresh.
    8. +
    +

    Run mac-sim run again after native changes: a new native dependency, a config plugin, app.json.

    + +

    Release builds and Expo Go

    +
    + + + + + + +
    CommandWhat you get
    mac-sim runa Debug build with Metro on Linux and Fast Refresh
    MODE=release mac-sim runa Release build with the JavaScript inside and no Metro: what users get. Check performance here; Debug builds and Expo Go add jank of their own
    MODE=go mac-sim runthe app in Expo Go, at the version matching the project's SDK, installed for you. Only for apps without custom native code
    + +

    Other project shapes

    +
      +
    • Bare React Native with its own ios/ folder in git: built as it is, with pod install but no prebuild.
    • +
    • Monorepos with several apps: run from inside the app's folder, or set APP_DIR.
    • +
    • Old libraries that import React Native's old headers ('RCTBridge.h' file not found): RN_FROM_SOURCE=1 mac-sim run builds React Native from source, slower.
    • +
    • Don't run npx expo run:ios on the Mac: it opens Simulator.app, which doubles the GPU's work for every simulator.
    • +
    + +

    Check the UI, not just the build

    +
    mac-sim snapshot               # the accessibility tree, refs like @e4
    +mac-sim ad press @e4           # tap; also fill, scroll, swipe, back...
    +mac-sim open myapp://settings  # a deep link
    +mac-sim record /tmp/flow.mp4 10 &
    +mac-sim ad press @e4           # drive the flow while it records
    +wait; sim-fps /tmp/flow.mp4    # 60 fps and no dropped frames in every stretch?
    +

    Measure motion on the default 1x simulator; the 3x ones (mac-sim up --sharp) are for screenshots at a real iPhone's pixels. Need widgets, Live Activities, the Dynamic Island or push? mac-sim up --full. mac-sim logs shows the build, Metro and tunnel output when something fails.

    + +

    Android from the same checkout

    +

    android-sim up && android-sim run does the same with an Android emulator on the host, if the Android SDK is set up (docs/agents.md).

    + +

    Real phones and TestFlight

    +

    phone-build (the phone-builds skill) makes an .ipa for an iPhone or TestFlight with your eas.json profiles. It uses Expo's free monthly EAS cloud builds first, then builds locally: iOS in the macbox VM, Android on the host. Signing for a device needs Apple's paid Developer Program. See skills/phone-builds.

    + +

    When you're done

    +
    mac-sim down    # stop Metro and free the simulator
    +mac-sim clean   # optional: delete this checkout's copy and build on the Mac (1 to 2 GB)
    +
    diff --git a/site/pages/guides/gpu-accelerated-macos-vm-on-linux.html b/site/pages/guides/gpu-accelerated-macos-vm-on-linux.html new file mode 100644 index 0000000..370ad8e --- /dev/null +++ b/site/pages/guides/gpu-accelerated-macos-vm-on-linux.html @@ -0,0 +1,77 @@ +title: GPU-Accelerated macOS VM on Linux, Without GPU Passthrough +short: GPU-accelerated macOS VM +description: How macbox gives a macOS VM on Linux Metal acceleration on the host's own Intel or AMD GPU, with Reims vGPU and metal2vulkan instead of VFIO passthrough. +kind: guide +order: 6 +--- +
    +

    A GPU-accelerated macOS VM on Linux, without GPU passthrough

    +

    macOS in QEMU usually means software rendering, unless you give the VM a whole GPU it has drivers for. macbox takes a different path: Apple's own paravirtual GPU device, answered on the host by Reims vGPU and translated from Metal to Vulkan. The host keeps its GPU, macOS gets Metal, and an integrated GPU is enough.

    +{{meta}} +
    +

    In short

    +
      +
    • No VFIO, no second GPU, no guest driver: macOS's built-in driver talks to the paravirtual device.
    • +
    • Works with a Mesa Vulkan driver: Intel (measured on Arrow Lake) or AMD (supported by Reims, untested with macbox).
    • +
    • macbox's patches raised the iOS Simulator's frame rate 1.8 to 2.3 times on the measured GPU.
    • +
    +
    + +

    Why macOS VMs are usually slow

    +

    macOS draws its desktop, its apps and the iOS Simulator with Metal. In a QEMU VM with an emulated display adapter there is no Metal device, so everything falls back to software rendering. The common fix is VFIO passthrough: give the VM a physical GPU that macOS has drivers for. That takes the GPU away from the host, needs a card macOS has a driver for (recent NVIDIA cards have none), rarely works with an integrated GPU, and is fiddly to set up.

    + +

    The path macbox uses

    +
    macOS 26 (guest): Metal ──► Apple's paravirtual GPU driver (built in)
    +   │  apple-gfx-pci device in QEMU
    +   ▼
    +Reims vGPU (host) ──► metal2vulkan ──► Vulkan (Mesa: ANV for Intel, RADV for AMD) ──► your GPU
    +
      +
    • Reims vGPU implements, on the host, the device Apple uses for its own virtual machines (apple-gfx-pci). macOS ships a driver for it, so the guest needs nothing installed.
    • +
    • metal2vulkan executes the Metal command streams that arrive at that device on Vulkan.
    • +
    • The display: Reims draws each guest display into its own window. macbox puts it in a headless compositor and streams it with Selkies (H.264 on the GPU), or opens it directly on your Wayland desktop. QEMU's VNC is never used: it reads every frame back from the GPU and manages 2 to 3 frames a second.
    • +
    +

    Reims vGPU, metal2vulkan, reims-util and their QEMU fork are the work of Anees Iqbal (steelbrain). macbox builds them from pinned commits, applies its patches, and runs them in a container.

    + +

    What macbox's patches change

    +

    On every GPU measured so far the GPU is the bottleneck, so what matters is how much extra work translation adds per frame. Before the patches, most of it was copies: macOS's framebuffer and the simulator's display surface live in guest RAM, and metal2vulkan copied each into a GPU image and back around every render pass. Those shadow copies were 51% of all GPU time with the simulator and 67% with the desktop. The patch series renders those textures in place, adds Arrow Lake-specific device facts, and a file of live switches for experiments. Details: patches/README.md.

    + +

    Results

    +

    Intel Core Ultra 7 265 (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; frames counted at the simulator's screen, two runs each.

    +
    + + + + + + + +
    WorkloadReims 2ce3209Reims 7198fe6macbox build
    Simulator 1x (402×874)53.557.095.8 / 92.5
    Simulator 2x (804×1748)33.537.667.8 / 60.5
    Simulator 3x (1206×2622)17.219.238.5 / 39.5
    Safari at 3x, blurred floating barn/a39.566.4 / 64.2
    +

    Frames per second. A Genie minimize on a 3440×1440 desktop went from about 12 to 19.5 frames per animation. At 1x the GPU spends 8.0 ms per frame; at 3x, 25.0 ms. Measure your own GPU with the tools in bench/.

    + +

    Which GPUs

    +
    + + + + + + +
    GPUStatus
    Intel (Mesa ANV)measured: an Arrow Lake iGPU. The Arrow Lake facts are set only on Arrow Lake PCI ids; other Intel GPUs use in-place rendering where its per-memory-kind check passes
    AMD (Mesa RADV)supported by Reims, untested with macbox. Needs /dev/udmabuf
    NVIDIAworks with Reims, but macbox's image doesn't ship NVIDIA's driver yet
    + +

    Settings that matter

    +
      +
    • Simulator scale. 1x simulators are 4 to 9 times cheaper than 3x. macbox's pool is mostly 1x.
    • +
    • Desktop resolution and refresh. 1920×1080 costs about half of 3440×1440; MACBOX_REFRESH=60 keeps macOS from asking for 100 or 120 Hz.
    • +
    • Simulator.app closed. It doubles the GPU's work.
    • +
    • CPU pinning on hybrid CPUs (MACBOX_CPUSET), and the VM's disk on NVMe (./macbox disk nvme).
    • +
    • MACBOX_GPU_TUNING=off turns macbox's runtime GPU tuning off; ./macbox build --upstream builds Reims as upstream ships it, for comparison.
    • +
    + +

    Known limits

    +
      +
    • Animations start about 0.1 s late on an idle display: macOS's driver for this device sends no vblank while nothing presents (reims-vgpu#141).
    • +
    • 3x is GPU-bound at about 35 to 40 fps in heavy Liquid Glass scenes on this iGPU.
    • +
    • Tried without gain: answering as an Intel or AMD Mac GPU, compressed heap textures, newer Mesa, hugepages (impossible: Reims maps guest RAM in 16 KiB views). The full list is in docs/performance.md.
    • +
    +

    To set it up, follow How to run macOS on Linux.

    +
    diff --git a/site/pages/guides/index.html b/site/pages/guides/index.html new file mode 100644 index 0000000..5d21624 --- /dev/null +++ b/site/pages/guides/index.html @@ -0,0 +1,10 @@ +title: Guides: macOS, Xcode and the iOS Simulator on Linux +short: Guides +description: Technical guides for macbox: run macOS, Xcode and the iOS Simulator on Linux with GPU acceleration, for Expo apps and AI coding agents. +--- +
    + +

    Guides

    +

    Each guide answers one question, with the commands macbox actually ships. The step-by-step reference stays in the repository's docs; these pages link to it where it goes deeper.

    +{{guides}} +
    diff --git a/site/pages/guides/ios-simulator-for-ai-coding-agents.html b/site/pages/guides/ios-simulator-for-ai-coding-agents.html new file mode 100644 index 0000000..5acbd1b --- /dev/null +++ b/site/pages/guides/ios-simulator-for-ai-coding-agents.html @@ -0,0 +1,75 @@ +title: iOS Simulators for AI Coding Agents and T3 Code +short: iOS Simulators for AI agents +description: Give Claude Code, Codex and T3 Code agents their own iOS Simulator on a Linux host: macbox's officially supported tools, skill and T3 Code Device panel. +kind: guide +order: 5 +--- +
    +

    Running iOS Simulators with AI coding agents

    +

    An agent that changes an iOS screen should see it running, not guess from the code. macbox officially supports AI coding agents (Claude Code and Codex) and T3 Code: it gives every agent checkout its own iOS Simulator on your Linux machine, the commands to build, tap, screenshot and record it, a 60 fps check, and a skill that tells the agent when to use them.

    +{{meta}} +
    +

    In short

    +
      +
    • ./macbox agents install installs mac-sim, sim-fps, android-sim, and the simulators skill for Claude Code and Codex.
    • +
    • ./macbox t3 register and ./macbox t3 fix-hub put the simulators in T3 Code's Device panel, streamed live.
    • +
    • Each checkout gets its own simulator, so agents in parallel worktrees don't wait for each other.
    • +
    +
    + +

    What's supported

    +

    These integrations are part of macbox and maintained in its repository. "Supported" here means macbox's own support; macbox isn't affiliated with or endorsed by Anthropic, OpenAI or T3.

    +
    + + + + + + + +
    ToolWhat macbox gives it
    Claude Codethe simulators, phone-builds and macbox skills in ~/.claude/skills; a "Simulators" section in ~/.claude/CLAUDE.md; an optional hook that reminds it of the skill when a prompt mentions a simulator
    Codexthe same skills in ~/.agents/skills, and the same section in ~/.codex/AGENTS.md
    T3 Codethe VM as a device host in the Device panel (macbox t3 register), T3's device hub rebuilt for the Intel VM (macbox t3 fix-hub), and mac-sim t3 to print the ids for device_open
    Any agent with a shellmac-sim, sim-fps and android-sim are plain commands; the skill files are Markdown any agent can read
    + +

    Install

    +

    With a working macbox VM, Xcode and the pool (iOS Simulator on Linux):

    +
    ./macbox agents install
    +

    It links mac-sim, mac-sim-remote, sim-fps, android-sim, android-gpu-desktop, phone-build and macbox into ~/.local/bin; links the skills into ~/.claude/skills and ~/.agents/skills; writes the simulators section between <!-- macbox:simulators --> markers in ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md (each backed up first); and enables the timer that shuts idle simulators down. ./macbox agents uninstall removes the links and the timer.

    + +

    What an agent does with it

    +

    From the app's checkout:

    +
    mac-sim up                     # claim a simulator from the pool and boot it
    +mac-sim run                    # copy the checkout to the Mac, build, install, open; Metro on Linux
    +mac-sim snapshot               # the screen as an accessibility tree, refs like @e12
    +mac-sim ad press @e12          # tap (any agent-device command)
    +mac-sim shot /tmp/a.png        # a lossless screenshot to look at
    +mac-sim record /tmp/a.mp4 10 & # record while driving the flow...
    +wait; sim-fps /tmp/a.mp4       # ...then: 60 fps in every stretch of motion? dropped frames?
    +mac-sim down                   # give it back
    +

    The simulators skill is the agent's rulebook. After every UI change it runs the app, screenshots and looks, records the whole flow, and checks with sim-fps that motion held 60 fps with no dropped frames. It re-checks on a Release build (MODE=release mac-sim run) before calling the work done. sim-fps exits non-zero when a stretch drops frames, so the check is a pass or a fail, not an impression.

    +

    Measure motion on a 1x simulator (the default). On a modest GPU, 3x simulators can't reach 60 fps in heavy scenes, and that's the machine, not the app. On an Intel Arrow Lake iGPU a 1x simulator reached 92 to 96 fps in a heavy Liquid Glass benchmark.

    + +

    Several agents at once

    +

    mac-sim keys each simulator to a checkout's git root. Two agents in two worktrees get two simulators, and mac-sim status shows who holds what. The default pool has two slim simulators plus full, sharp and small. Simulators nobody has used for 20 minutes shut down on their own.

    + +

    T3 Code's Device panel

    +

    T3 Code shows simulators and emulators in its Device panel, and its agents can call device_open, device_screenshot and device_list. iOS needs a Mac, which T3 reaches over SSH; macbox's VM is that Mac.

    +
    ./macbox t3 register   # add the VM to T3's deviceHosts (settings backed up first)
    +                       # open T3's Device panel once: T3 installs its device hub on the Mac
    +./macbox t3 fix-hub    # rebuild the hub's native parts for the Intel VM
    +./macbox t3 status
    +

    T3's hub ships its native parts for Apple silicon only; fix-hub rebuilds them for x86-64 from the hub's own source, including a fix that makes the VM's software H.264 encoder deliver each frame at once. Run it again after T3 updates its hub. Then:

    +
      +
    • mac-sim t3 prints hostId=macbox deviceId=<udid>; the agent passes them to device_open, and the user watches every tap live.
    • +
    • On iOS the agent keeps driving with mac-sim ad …. Using the agent-device command device_open returns as well would start a second session on the same simulator, and the two refuse each other (DEVICE_IN_USE).
    • +
    • From a tap to the first new frame on the stream: a median of 66 ms inside the Mac.
    • +
    • Android emulators started with android-sim show up in the panel by themselves (hostId local, the serial from android-sim serial).
    • +
    + +

    Letting an agent set up macbox itself

    +

    An agent can do the whole installation, including the steps inside macOS's GUI. It looks at the VM's screen with ./macbox screenshot and acts with click, type, key and wait. Point it at AGENTS.md: it lists the sequence and the ground rules, such as asking before changing the host and never handling the user's passwords or Apple Account.

    + +

    Android and real phones

    +
      +
    • android-sim has the same shape for Android emulators on the host: up, run, snapshot, ad, shot, record, down. It needs the Android SDK; see docs/agents.md.
    • +
    • The phone-builds skill and phone-build make an .ipa, a TestFlight upload or an .apk: Expo's free EAS cloud builds first, then locally (iOS in the VM). Device signing needs Apple's paid Developer Program.
    • +
    +
    diff --git a/site/pages/guides/ios-simulator-on-linux.html b/site/pages/guides/ios-simulator-on-linux.html new file mode 100644 index 0000000..9a63892 --- /dev/null +++ b/site/pages/guides/ios-simulator-on-linux.html @@ -0,0 +1,79 @@ +title: iOS Simulator on Linux: Run the Real Simulator Locally +short: iOS Simulator on Linux +description: Run Apple's real iOS 26 Simulator on a Linux host, GPU-accelerated, with no Mac or cloud service: a simulator pool, mac-sim commands and frame rates. +kind: guide +order: 3 +--- +
    +

    iOS Simulator on Linux

    +

    The iOS Simulator is part of Xcode, and Xcode needs macOS, so there is no native Linux version. Web-based "iOS emulators" only imitate the look. To run the real Simulator with your own app on a Linux machine, run macOS in a VM with the GPU attached, and the Simulator inside it. macbox does that, and gives you a command, mac-sim, to drive it from Linux.

    +{{meta}} +
    +

    In short

    +
      +
    • macbox runs macOS 26 with Xcode on your Linux host; the Simulator draws with Metal on your GPU.
    • +
    • ./macbox pool makes five simulators tuned for the VM; mac-sim up claims one per checkout.
    • +
    • On an Intel Arrow Lake iGPU, a 1x simulator renders a heavy Liquid Glass scene at 92 to 96 fps.
    • +
    +
    + +

    Set it up

    +

    You need a macbox VM with Xcode (macOS on Linux, then Xcode on Linux). Then, on the host:

    +
    ./macbox pool             # create the simulator pool in macOS
    +./macbox agents install   # mac-sim, sim-fps, android-sim in ~/.local/bin, the idle timer
    + +

    The pool

    +

    Instead of many default simulators, macbox keeps a small pool built for a VM. Each one is named <iPhone> (macbox <kind>), for example iPhone 17 Pro (macbox slim 1).

    +
    + + + + + + + +
    KindPixelsUse it for
    slim-1, slim-21xmost work. About 170 background iOS services are off (about 0.6 GB of memory instead of about 2), and it animates fastest
    full1xwidgets, Live Activities, the Dynamic Island, push notifications: every iOS service runs
    sharp3xscreenshots at a real iPhone's pixels
    small3xsmall-phone layouts (the "e" iPhone)
    +

    The 1x simulators have the same layout in points as a real iPhone with a quarter of 2x's pixels, which is why they are the default. Use the 3x ones for stills, not for judging frame rates.

    + +

    Use it

    +

    Run mac-sim from inside an app's checkout. Each checkout (git root) gets its own simulator and keeps it until down, so parallel worktrees don't wait for each other.

    +
    mac-sim up                  # claim a slim simulator and boot it (--full, --sharp, --small)
    +mac-sim run                 # build the app on the Mac, install and open it; Metro runs here
    +mac-sim snapshot            # the screen as an accessibility tree, refs like @e12
    +mac-sim ad press @e12       # tap; any agent-device command
    +mac-sim open myapp://path   # a deep link
    +mac-sim shot /tmp/home.png  # a lossless screenshot, copied to Linux
    +mac-sim record /tmp/a.mp4 10   # 10 s of video
    +sim-fps /tmp/a.mp4          # fps and dropped frames per stretch of motion
    +mac-sim status              # every simulator and who holds it
    +mac-sim down                # give it back
    +

    mac-sim install path/To.app installs any simulator build, and mac-sim mac '<command>' runs a shell command on the Mac with $UDID set to your simulator, so plain xcrun simctl works too.

    + +

    See the screen

    +
      +
    • Screenshots and recordings from mac-sim shot and record arrive on Linux, at the simulator's own pixels.
    • +
    • T3 Code's Device panel streams the simulator live and takes taps: ./macbox t3 register, then ./macbox t3 fix-hub. docs/t3-code.md has the details.
    • +
    • The macOS desktop in a browser tab (http://127.0.0.1:6081/) or a local window, if you want Simulator.app. Keep it closed otherwise: it opens a window per simulator and doubles the GPU's work.
    • +
    + +

    How fast it is

    +

    Measured with GlassBench, a table scrolling under Liquid Glass bars and a floating glass toolbar, counted at the simulator's own screen, on an Intel Core Ultra 7 265 (Arrow Lake iGPU) with Mesa 26.2.4, macOS 26.7.1 and iOS 26.5:

    +
    + + + + + + +
    SimulatorReims upstream (2ce3209)macbox build
    1x (402×874)53.5 fps95.8 / 92.5 fps
    2x (804×1748)33.5 fps67.8 / 60.5 fps
    3x (1206×2622)17.2 fps38.5 / 39.5 fps
    +

    The GPU sets the ceiling: a 3x simulator keeps that iGPU 96 to 98% busy. Simulators animating at the same time share it. Recording uses the VM's software H.264 encoder, about 50 fps with one simulator animating. Full method: docs/performance.md.

    + +

    Limits

    +
      +
    • iOS 26 Simulators are the newest on x86-64; iOS 27's simulators are Apple silicon only.
    • +
    • Simulator resolutions are fixed once created; pick a different pool simulator instead.
    • +
    • Don't restart CoreSimulatorService while simulators run: it shuts down every one of them.
    • +
    • Pool simulators idle for 20 minutes (no mac-sim command, no viewer) are shut down by a timer.
    • +
    +

    Next: build an Expo or React Native app, or hand the simulator to an AI coding agent.

    +
    diff --git a/site/pages/guides/macbox-vs-docker-osx-and-osx-kvm.html b/site/pages/guides/macbox-vs-docker-osx-and-osx-kvm.html new file mode 100644 index 0000000..981218c --- /dev/null +++ b/site/pages/guides/macbox-vs-docker-osx-and-osx-kvm.html @@ -0,0 +1,52 @@ +title: macbox vs Docker-OSX and OSX-KVM: macOS on Linux with GPU +short: macbox vs Docker-OSX and OSX-KVM +description: How macbox compares with Docker-OSX, OSX-KVM, cloud simulators and a real Mac for running macOS, Xcode and the iOS Simulator on Linux, GPU included. +kind: guide +order: 7 +--- +
    +

    macbox vs Docker-OSX and OSX-KVM

    +

    Docker-OSX and OSX-KVM are the well-known ways to run macOS on Linux, and macbox stands on the same foundation: QEMU, KVM and OpenCore. The difference is the GPU, and what the VM is for. macbox gives macOS Metal on the host's own GPU without passthrough, and it is built around Xcode, the iOS Simulator and AI coding agents.

    +{{meta}} +
    +

    In short

    +
      +
    • Pick macbox to develop and test iOS apps on a Linux machine, with Metal on an Intel or AMD GPU you keep using on the host, and with agent tooling.
    • +
    • Pick Docker-OSX or OSX-KVM for a range of macOS versions, a GPU you can pass through, or a general-purpose macOS VM.
    • +
    • Pick a Mac or a cloud service for the newest Xcode and iOS, or where Apple's license must be met.
    • +
    +
    + +

    Side by side

    +
    + + + + + + + + + + + + +
    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
    The host keeps its GPUyesnot with passthroughn/an/a
    macOS versionsmacOS 26 Tahoea range of releasesthe provider'sthe Mac's
    Newest iOS Simulator26.x, the x86-64 ceiling26.xthe newestthe newest
    Xcode and simulators set up for youyes: macbox xcode, macbox poolby handyesby hand
    Built for agentsa simulator per checkout, screenshots, recordings, a 60 fps check, a skill, T3 Code's Device panelnovarieswith tools such as agent-device
    Costyour hardwareyour hardwareusually per minute or a planthe Mac
    Apple's macOS licensenot on non-Apple hardwarenot on non-Apple hardwareyesyes
    + +

    The GPU difference

    +

    Docker-OSX and OSX-KVM give macOS an emulated display adapter. macOS has no Metal driver for it, so the desktop, Xcode and the iOS Simulator draw in software, unless you pass a physical GPU through with VFIO. Passthrough needs a card macOS has drivers for, and that card then belongs to the VM, not the host.

    +

    macbox gives QEMU Apple's paravirtual GPU device through Reims vGPU. macOS's built-in driver talks to it, and metal2vulkan runs the Metal work on the host's Vulkan driver. On an Intel Arrow Lake iGPU, that is enough for a 1x iOS Simulator to render a heavy Liquid Glass scene at 92 to 96 fps. How it works, with measurements.

    + +

    The scope difference

    +

    Docker-OSX and OSX-KVM aim to boot macOS, across many versions, for whatever you need it for. macbox does less and goes further along one path: macOS 26, then Xcode, a pool of simulators tuned for a VM (mostly 1x, with background services trimmed), Metro on Linux for Expo and React Native, T3 Code's Device panel, and mac-sim and sim-fps for agents. One CLI, macbox, runs it, and macbox next always says what's left to do.

    + +

    When macbox isn't the right tool

    +
      +
    • You need Xcode 27, iOS 27 Simulators or anything newer: Apple ships those for Apple silicon only. Use a Mac or a cloud service.
    • +
    • You need an older macOS release, or a GPU passed through for other reasons: Docker-OSX or OSX-KVM.
    • +
    • Your host has only an NVIDIA GPU: macbox's image doesn't ship NVIDIA's driver yet.
    • +
    • You need to stay within Apple's macOS license: it allows macOS only on Apple-branded hardware.
    • +
    • Commercial use: macbox's own code is under the PolyForm Noncommercial License, so commercial use needs the author's permission.
    • +
    +

    Ready to try it? How to run macOS on Linux with macbox.

    +
    diff --git a/site/pages/guides/run-macos-on-linux.html b/site/pages/guides/run-macos-on-linux.html new file mode 100644 index 0000000..56af118 --- /dev/null +++ b/site/pages/guides/run-macos-on-linux.html @@ -0,0 +1,92 @@ +title: How to Run macOS on Linux with GPU Acceleration +short: Run macOS on Linux +description: Run macOS 26 Tahoe in a VM on a Linux host with KVM, QEMU and Metal on your own GPU, step by step with macbox: requirements, install, daily use. +kind: guide +order: 1 +--- +
    +

    How to run macOS on Linux with GPU acceleration

    +

    macOS runs well in a KVM virtual machine on Linux. The usual catch is graphics: without a GPU passed through to the VM, macOS draws in software, and anything built on Metal is slow or broken. macbox solves that with Reims vGPU, and wraps the whole setup in one command-line tool.

    +{{meta}} +
    +

    In short

    +
      +
    • You need an x86-64 Linux host with KVM, AVX2, an Intel or AMD GPU with a Mesa Vulkan driver, 16 GB of RAM, about 150 GB of SSD, and Docker.
    • +
    • ./macbox init, doctor, build, create, up, then a short install in the VM's screen. ./macbox next always prints the next step.
    • +
    • The result is macOS 26 Tahoe with Metal on your GPU, reachable as ssh macbox and as a window or browser tab.
    • +
    +
    + +

    How it works

    +

    macbox runs QEMU inside a Docker container, with KVM for the CPU. Booting macOS on a PC goes through OpenCore, which reims-ctl sets up. The part that is different from other macOS-on-Linux setups is the GPU:

    +
      +
    • Reims vGPU gives QEMU Apple's paravirtual GPU device (apple-gfx-pci). macOS already has a driver for it, so no guest driver is needed.
    • +
    • metal2vulkan runs the Metal work that device receives on Vulkan, through Mesa on your GPU.
    • +
    • The host keeps its GPU. Nothing is passed through, and an integrated GPU is enough.
    • +
    +

    macbox builds both from pinned commits with its own patches, which made the iOS Simulator 1.8 to 2.3 times faster on the GPU they were measured on. The GPU guide explains the path in detail.

    + +

    Requirements

    +
    + + + + + + + +
    CPUx86-64 with VT-x or AMD-V, and AVX2
    GPUIntel (measured: Arrow Lake iGPU) or AMD (supported by Reims, untested here), with a Mesa Vulkan driver. 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
    SoftwareKVM (/dev/kvm), a render node (/dev/dri/renderD*), Docker (rootless works well) or Podman (untested)
    +

    The guest is macOS 26 Tahoe. Apple's last macOS for Intel is 26, so that is also the newest macOS that runs on x86-64.

    +

    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 ships no Apple software; macOS downloads from Apple, and complying with Apple's terms is up to you.

    + +

    1. Prepare the host

    +

    Your user needs to open /dev/kvm and the GPU's render node, and Reims needs a much higher vm.max_map_count than the default 65530:

    +
    sudo usermod -aG kvm,render $USER        # then log in again
    +echo vm.max_map_count=2097152 | sudo tee /etc/sysctl.d/60-macbox.conf && sudo sysctl --system
    +

    With more than one GPU, choose the render node in the config (MACBOX_RENDER_NODE). An AMD GPU also needs access to /dev/udmabuf.

    + +

    2. Configure, check and build

    +
    git clone https://github.com/TUNA-NOPE/macbox ~/macbox && cd ~/macbox
    +./macbox init      # ~/.config/macbox/macbox.env, an SSH key, a "Host macbox" alias
    +./macbox doctor    # fix every FAIL; WARN lines are advice
    +./macbox build     # the image, then Reims vGPU + metal2vulkan + QEMU: 20 to 60 minutes, ~25 GB
    +

    init sizes the VM for your machine (half the cores, a third of the RAM, within limits). Look at ~/.config/macbox/macbox.env before you build: the resolution, CPU pinning for hybrid CPUs, and where everything is stored (MACBOX_HOME) are all set there.

    + +

    3. Create the VM and install macOS

    +
    ./macbox create          # the newest macOS 26 Tahoe, through Apple's recovery image
    +./macbox boot-picker on  # OpenCore's boot menu, needed for one Recovery step
    +./macbox up
    +

    Open the screen at http://127.0.0.1:6081/ in a browser on the host, or run ./macbox view local from a Wayland desktop on the host for a window with no encoding at all. Then, in the VM:

    +
      +
    1. In Recovery, open Disk Utility, choose View › Show All Devices, and erase QEMU HARDDISK Media as APFS with a GUID partition map.
    2. +
    3. Choose Reinstall macOS and install onto that disk. It downloads macOS from Apple and restarts a few times (30 to 60 minutes).
    4. +
    5. When Setup Assistant or a broken desktop appears, restart the VM (./macbox down && ./macbox up), choose Recovery in OpenCore's menu, open Utilities › Terminal, and run ./macbox recovery-fix on the host. It sets the Metal error mode macOS 26 needs under Reims.
    6. +
    7. Go through Setup Assistant: skip the Apple Account and create an administrator named dev.
    8. +
    9. Open Terminal in macOS and run ./macbox ssh-bootstrap on the host. Then ssh macbox sw_vers should answer.
    10. +
    +

    Each of these steps is spelled out, with what to do when one goes wrong, in docs/setup.md. An AI agent can do them too: it sees the screen with ./macbox screenshot and acts with click, type and key (AGENTS.md).

    + +

    4. Finish over SSH

    +
    ./macbox down && ./macbox disk nvme && ./macbox boot-picker off && ./macbox up
    +./macbox provision                            # passwordless sudo, no sleep, Node, Ruby + CocoaPods
    +./macbox xcode ~/Downloads/Xcode_26.6.xip     # optional: Xcode and the iOS Simulator runtime
    +./macbox pool                                 # optional: the iOS Simulator pool
    +./macbox agents install                       # optional: mac-sim, sim-fps and the skills
    +

    Moving the system disk to NVMe makes small reads about a third faster and app launches up to twice as fast. ./macbox next ticks off each step as it's done.

    + +

    Day to day

    +
    ./macbox up | down | status
    +./macbox ssh                       # a shell on the Mac
    +./macbox logs qemu                 # or selkies, sway
    +./macbox resolution 2560x1440      # macOS's screen size (restarts a running VM)
    +./macbox backup before-update      # a copy of the disk, with the VM stopped
    +

    To watch from another machine, forward the port (ssh -L 6081:127.0.0.1:6081 <host>) or publish it on a private tailnet. The stream has no password of its own, so never expose it on the open internet.

    + +

    Limits

    +
      +
    • macOS 26 is the ceiling on x86-64; macOS 27 and iOS 27's simulators are Apple silicon only.
    • +
    • NVIDIA GPUs aren't supported by macbox's image yet. AMD should work through Reims, but hasn't been tested with macbox.
    • +
    • An idle macOS display gets no vblank from its driver, so the first frame of an animation starts about 0.1 s late (reims-vgpu#141).
    • +
    +

    When something doesn't work, start with ./macbox doctor and docs/troubleshooting.md.

    +
    diff --git a/site/pages/guides/xcode-on-linux.html b/site/pages/guides/xcode-on-linux.html new file mode 100644 index 0000000..0c24b6d --- /dev/null +++ b/site/pages/guides/xcode-on-linux.html @@ -0,0 +1,65 @@ +title: How to Run Xcode on Linux +short: Xcode on Linux +description: Xcode needs macOS, but you can run the real Xcode 26 on a Linux machine inside a GPU-accelerated macOS VM. Install it, build with xcodebuild over SSH. +kind: guide +order: 2 +--- +
    +

    How to run Xcode on Linux

    +

    There is no Xcode for Linux, and no Linux tool that replaces it for iOS: building, signing and simulating Apple apps needs Apple's SDKs, which run on macOS. What you can do is run macOS itself on your Linux machine, and the real Xcode inside it. This guide does that with macbox.

    +{{meta}} +
    +

    In short

    +
      +
    • Set up a macOS VM with macbox (guide).
    • +
    • Download Xcode 26's .xip from Apple, then ./macbox xcode ~/Downloads/Xcode_26.6.xip.
    • +
    • Build from Linux with ssh macbox xcodebuild …, or use Xcode's window in the VM's screen.
    • +
    +
    + +

    Your options

    +
    + + + + + + +
    OptionXcode versionTrade-off
    A Mac, or a rented remote Macthe newestthe supported route; costs the Mac or a monthly fee
    A cloud CI or simulator servicethe newestbilled per minute or by plan; your code and builds leave your machine
    A macOS VM on Linux (macbox)Xcode 26your own hardware, GPU-accelerated; macOS 26 is the x86-64 ceiling; outside Apple's license on non-Apple hardware
    +

    Cross-compiling Swift on Linux works for server-side Swift and command-line tools, but it doesn't give you UIKit, SwiftUI, the iOS SDK, Interface Builder or the Simulator.

    + +

    Which Xcode runs

    +

    Xcode 26, with iOS 26 Simulators. macbox's macOS guest is x86-64, and macOS 26 Tahoe is the last macOS for Intel. Apple ships macOS 27, Xcode 27 and iOS 27's simulators for Apple silicon only, so they can't run on an x86-64 Linux host. macbox is used day to day with Xcode 26.6 and iOS 26.5.

    + +

    Install Xcode

    +
      +
    1. Set up the VM as in How to run macOS on Linux, through ./macbox provision. You need ssh macbox working.
    2. +
    3. Download Xcode's .xip from developer.apple.com/download/all. Any free Apple Account can sign in there. macbox never handles your Apple ID, so this one step is yours, on the host.
    4. +
    5. Install it: +
      ./macbox xcode ~/Downloads/Xcode_26.6.xip
      +./macbox xcode     # afterwards: the version, license and first-launch status
      +It copies the file into the VM, expands and installs it, selects it with xcode-select, accepts the license, runs the first launch, and adds the iOS Simulator runtime. Expect 30 to 60 minutes.
    6. +
    + +

    Build from Linux

    +

    The VM is an SSH host named macbox, so Xcode's command-line tools are one hop away:

    +
    ssh macbox xcodebuild -version
    +ssh macbox xcrun simctl list devices available
    +

    Copy a project in with rsync or git clone it on the Mac, then run xcodebuild as you would on a Mac. For Expo and React Native apps, mac-sim run does the copy, the CocoaPods install, the build and the install into a simulator for you, with Metro on Linux: see the Expo guide.

    +

    To use Xcode's own window, open the VM's screen at http://127.0.0.1:6081/ or run ./macbox view local. Xcode draws with Metal on your GPU like the rest of macOS.

    + +

    Simulators and devices

    +
      +
    • ./macbox pool creates a small pool of iOS Simulators tuned for the VM, mostly at 1x pixels, which is 4 to 9 times cheaper to draw than 3x. See iOS Simulator on Linux.
    • +
    • Keep Simulator.app closed when you can. It opens a window per booted simulator and doubles the GPU's work; mac-sim and T3 Code read the simulator's screen directly.
    • +
    • For an .ipa on a real iPhone or TestFlight, the phone-build tool builds in the VM (after Expo's free EAS cloud builds). Signing for devices needs Apple's paid Developer Program.
    • +
    + +

    Common questions

    +

    Do I need an Apple Account inside macOS?

    +

    No. Setup Assistant can skip it. You only sign in at developer.apple.com, in your own browser, to download the .xip.

    +

    Is it fast enough to use?

    +

    On an Intel Arrow Lake iGPU, a 1x iOS Simulator renders a heavy Liquid Glass scene at 92 to 96 fps. Builds use the VM's vCPUs (8 in that setup); a first Expo build takes 2 to 15 minutes and later builds are incremental. Other hardware hasn't been measured yet.

    +

    Is it legal?

    +

    Apple's macOS license allows macOS only on Apple-branded hardware, so running it in a VM on a PC breaches that agreement. macbox ships no Apple software, and compliance with Apple's terms is your responsibility.

    +
    diff --git a/site/pages/index.html b/site/pages/index.html new file mode 100644 index 0000000..bf0025d --- /dev/null +++ b/site/pages/index.html @@ -0,0 +1,222 @@ +title: macbox: give your AI agents a Mac and iOS Simulators on Linux +description: macbox runs macOS, Xcode and iOS Simulators on your Linux machine with your own GPU, so Claude Code, Codex and T3 Code can build, tap and test your iPhone app. +--- +
    +
    +

    macbox

    +

    Give your agents a Mac.

    +

    macOS, Xcode and real iPhone simulators, on your Linux machine. Your coding agent builds the app, taps through it and checks it for itself.

    + +

    Works with

      +
    • Claude Code
    • +
    • Codex
    • +
    • 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 + +
    The full, uncropped screen of macOS 26 in macbox, running on Linux with an Intel integrated GPU. Nimbus is a demo app built for this page.
    +
    +
    + +
    +
    +
    +

    Everything an agent needs to test an iPhone app.

    +

    Coding agents write iPhone apps well, but they can't see them run. macbox gives each one a real simulator and the tools to use it like a developer.

    +
    +
    +
    +
    +

    A real iOS Simulator.

    +

    Xcode builds the app and installs it in an iOS 26 Simulator. Then the agent taps, types, scrolls and takes screenshots, just like you would. Expo and React Native work too.

    +
    + +
    +
    +

    60 fps

    +

    Smooth, measured.

    +

    The agent records the animation and counts its frames. Done means none were dropped.

    +
    +
    +

    One simulator per checkout.

    +

    Several agents work side by side, each on its own simulator.

    +
      +
    • slim 1feature/checkout
    • +
    • slim 2fix/login
    • +
    • sharpFree
    • +
    • fullWidgets, Dynamic Island
    • +
    +
    +
    + +

    Live in T3 Code.

    +

    The simulator streams into T3 Code's Device panel while the agent works. Tap in yourself whenever you like.

    +
    +
    +

    No Mac.

    +

    Just your own GPU.

    +

    macOS draws with Metal on your Intel or AMD graphics, and Linux keeps the GPU. An integrated one is enough.

    +
    +
    +
    +
    + +
    +
    +
    +

    Works with the agents you already use.

    +

    The integrations ship with macbox and are maintained with it.

    +
    +
    +

    Claude Code

    Gets the tools, and a skill that says when to open a simulator and how to test on it.

    +

    Codex

    The same skill and tools, and a Simulators section in its AGENTS.md.

    +

    T3 Code

    Shows each simulator live in the Device panel, and takes your taps.

    +
    +
    ./macbox agents install   # Claude Code and Codex
    +./macbox t3 register      # T3 Code's Device panel
    +

    macbox isn't affiliated with or endorsed by Anthropic, OpenAI or T3. Their names and logos belong to them. How agents use macbox

    +
    +
    + +
    +
    +
    +

    Performance

    +

    92–96 fps

    +

    Smooth enough to judge an animation.

    +

    An iPhone simulator running a heavy Liquid Glass screen on an Intel integrated GPU. That's almost twice as fast as the GPU code macbox builds on.

    +
    +
    + iOS Simulator frame rate in a Liquid Glass benchmark. 1x: 53.5 fps upstream, 94.2 with the macbox build. 2x: 33.5 and 64.2. 3x: 17.2 and 39.0. +
    +
    + The exact numbers +
    + + + + + + + + +
    WorkloadReims 2ce3209, upstreammacbox build (two runs)
    iOS Simulator 1x (402×874), Liquid Glass53.5 fps95.8 / 92.5 fps
    iOS Simulator 2x (804×1748), Liquid Glass33.5 fps67.8 / 60.5 fps
    iOS Simulator 3x (1206×2622, an iPhone's pixels)17.2 fps38.5 / 39.5 fps
    Safari at 3x, a page under a blurred floating barn/a66.4 / 64.2 fps
    macOS desktop, Genie minimize at 3440×1440~12 frames19.5 frames
    +

    Intel Core Ultra 7 265 (Arrow Lake iGPU), Mesa 26.2.4, macOS 26.7.1, iOS 26.5, a VM with 8 vCPUs and 12 GB. Frames counted at the simulator's own screen, after a warm-up, one simulator animating. The GPU is the limit, so a faster GPU moves every number up; other GPUs haven't been measured yet. Method and patches: docs/performance.md.

    +
    +
    +
    + +
    +
    +
    +

    A real Mac, in a box on Linux.

    +

    macbox runs macOS in a virtual machine inside one Docker container. Unlike other ways of doing that, macOS draws with your machine's graphics card.

    +
    +
      +
    1. 1

      Install it on Linux.

      A PC or server with an Intel or AMD GPU. Your agent can do the whole setup.

    2. +
    3. 2

      Connect your agent.

      One command adds the tools and skills for Claude Code, Codex and T3 Code.

    4. +
    5. 3

      Let it test.

      Before it calls a UI change done, it builds, runs, taps, looks and measures.

    6. +
    +
    + Under the hood +

    QEMU gives macOS Apple's own paravirtual GPU through Reims vGPU, and metal2vulkan runs macOS's Metal work on the host's Vulkan driver (Mesa). No GPU is passed through, so an integrated GPU is enough. After a short install in the VM's screen, everything else runs over SSH: macbox xcode installs the Xcode you download from Apple, macbox pool creates the simulators, and mac-sim copies a checkout into macOS, builds it there and runs Metro on Linux.

    +
    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  ──► the Device panel, live
    +

    How the GPU path works

    +
    +
    +
    + +
    +
    +

    Instead of a Mac, a cloud, or a slow VM.

    +
    +

    Instead of buying a Mac

    Use the Linux machine your agents already run on. One box, one copy of the code, no second computer to keep in sync.

    +

    Instead of cloud simulators

    Everything runs on your hardware. No per-minute bill, and your code never leaves the machine.

    +

    Instead of Docker-OSX or OSX-KVM

    Those draw macOS in software unless you hand a whole GPU to the VM. macbox gets macOS onto your GPU while Linux keeps it.

    +
    +

    The full comparison

    +
    +
    + +
    +
    +
    +

    Let your agent set it up.

    +

    macbox is written so an agent can do the whole install, the clicks in macOS's setup screens included. Paste this into Claude Code, Codex or T3 Code:

    +
    +
    Set up macbox on this machine: https://github.com/TUNA-NOPE/macbox. Follow its AGENTS.md and ask me before changing the host.
    +

    It asks before it installs anything on the host, and needs two things from you: a macOS password, which you type into the VM's screen, and the Xcode download from Apple, which needs your Apple Account. Plan on an afternoon, mostly downloads and builds.

    +
    +

    You'll need

    +
      +
    • Linux on an x86-64 CPU with KVM and AVX2
    • +
    • An Intel or AMD GPU with Mesa's Vulkan driver
    • +
    • 16 GB of RAM and about 150 GB free on an SSD
    • +
    • Docker (rootless is fine) or Podman
    • +
    +

    macbox runs macOS 26 and iOS 26 simulators: the last versions Apple makes for Intel. NVIDIA isn't packaged yet, and AMD is supported upstream but untested here.

    +
    +
    + Or do it yourself +
    git clone https://github.com/TUNA-NOPE/macbox && cd macbox
    +./macbox init      # config and an SSH key
    +./macbox doctor    # checks KVM, the GPU, Docker, disk
    +./macbox build     # the GPU stack (20 to 60 min)
    +./macbox create    # a VM; macOS downloads from Apple
    +./macbox up        # the screen: http://127.0.0.1:6081/
    +./macbox next      # what's done, and the next step
    +

    ./macbox next always says what's done and what's next. The walkthrough

    +
    +
    +
    + +
    +
    +

    Guides.

    Start from what you're trying to do.

    + {{guides}} +
    +
    + +
    +
    +

    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 run 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. See the agents guide.

    +
    Does it work with T3 Code's Device panel?

    Yes: macbox t3 register adds the VM as a device host, and the simulators stream live into the panel and take taps.

    +
    Is this Docker-OSX or OSX-KVM 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. 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. The Expo guide covers Release builds and Expo Go.

    +
    Real iPhones and TestFlight?

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

    +
    What can't it do?

    Run macOS 27, Xcode 27 or iOS 27's simulators, which Apple ships for Apple silicon only. And it can't make running macOS on non-Apple hardware compliant with Apple's license: see below.

    +
    Is it free?

    For noncommercial use, yes: macbox's own code is under the PolyForm Noncommercial License 1.0.0 (yourself, a hobby, research, teaching, a charity). Commercial use needs the author's permission: open an issue to ask.

    +
    +

    Apple's license. 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 comes as is, with no warranty.

    +
    +
    +
    + +
    +
    +

    Give your agents a Mac.

    +

    Hand your agent the repo, and let it set up the rest.

    + +
    +
    diff --git a/site/static/d0f80829b645869eb473963b6ad2dd95.txt b/site/static/d0f80829b645869eb473963b6ad2dd95.txt new file mode 100644 index 0000000..782e314 --- /dev/null +++ b/site/static/d0f80829b645869eb473963b6ad2dd95.txt @@ -0,0 +1 @@ +d0f80829b645869eb473963b6ad2dd95 \ No newline at end of file diff --git a/site/static/favicon.svg b/site/static/favicon.svg new file mode 100644 index 0000000..1b9c242 --- /dev/null +++ b/site/static/favicon.svg @@ -0,0 +1 @@ + diff --git a/site/static/google2a79202c4df40a46.html b/site/static/google2a79202c4df40a46.html new file mode 100644 index 0000000..da278df --- /dev/null +++ b/site/static/google2a79202c4df40a46.html @@ -0,0 +1 @@ +google-site-verification: google2a79202c4df40a46.html \ No newline at end of file diff --git a/site/static/images/desk-1600.jpg b/site/static/images/desk-1600.jpg new file mode 100644 index 0000000..7dc4f60 Binary files /dev/null and b/site/static/images/desk-1600.jpg differ diff --git a/site/static/images/desk-1600.webp b/site/static/images/desk-1600.webp new file mode 100644 index 0000000..5bee269 Binary files /dev/null and b/site/static/images/desk-1600.webp differ diff --git a/site/static/images/desk-800.webp b/site/static/images/desk-800.webp new file mode 100644 index 0000000..6a0849f Binary files /dev/null and b/site/static/images/desk-800.webp differ diff --git a/site/static/images/phone-cities.webp b/site/static/images/phone-cities.webp new file mode 100644 index 0000000..fad8312 Binary files /dev/null and b/site/static/images/phone-cities.webp differ diff --git a/site/static/images/phone-today.webp b/site/static/images/phone-today.webp new file mode 100644 index 0000000..1930013 Binary files /dev/null and b/site/static/images/phone-today.webp differ diff --git a/site/style.css b/site/style.css new file mode 100644 index 0000000..4c13b17 --- /dev/null +++ b/site/style.css @@ -0,0 +1,240 @@ +/* macbox's site: one stylesheet, inlined into every page by build.py. No web fonts: the system's own. */ +:root { + --bg: #ffffff; --alt: #f5f5f7; --card: #f5f5f7; --ink: #1d1d1f; --ink2: #424245; --ink3: #6e6e73; + --line: #d2d2d7; --link: #0066cc; --btn: #0071e3; --btn-hover: #0077ed; --code: #1d1d1f; --code-ink: #f5f5f7; --good: #1f8a52; + --grad: linear-gradient(95deg, #0a84ff 0%, #5e5ce6 45%, #bf5af2 100%); + --display: -apple-system, BlinkMacSystemFont, "SF Pro Display", "Helvetica Neue", Inter, "Segoe UI Variable Display", "Segoe UI", Roboto, Arial, sans-serif; + --sans: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Inter, "Segoe UI Variable Text", "Segoe UI", Roboto, Arial, sans-serif; + --mono: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace; + --frame: 1080px; --read: 720px; --gap: clamp(88px, 12vw, 150px); --r: 18px; --tile: 28px; +} +@media (prefers-color-scheme: dark) { + :root { --bg: #000000; --alt: #121214; --card: #1d1d1f; --ink: #f5f5f7; --ink2: #d2d2d7; --ink3: #a1a1a6; + --line: #38383d; --link: #2997ff; --code: #1c1c1e; --good: #30d158; } +} +* { box-sizing: border-box; } +html { -webkit-text-size-adjust: 100%; scroll-padding-top: 64px; } +body { margin: 0; background: var(--bg); color: var(--ink); font: 17px/1.5 var(--sans); letter-spacing: -0.01em; text-rendering: optimizeLegibility; -webkit-font-smoothing: antialiased; } +a { color: var(--link); text-decoration: none; } +a:hover { text-decoration: underline; text-underline-offset: 3px; } +/* links inside running text keep a thin underline, so they don't rely on color alone */ +p a:not(.more-link), li a:not(.cards a), td a, .callout a { text-decoration: underline; text-decoration-thickness: 1px; text-underline-offset: 3px; text-decoration-color: color-mix(in srgb, currentColor 45%, transparent); } +p a:not(.more-link):hover, li a:not(.cards a):hover { text-decoration-color: currentColor; } +img, svg { max-width: 100%; height: auto; } +h1, h2, h3 { font-family: var(--display); font-weight: 600; line-height: 1.08; letter-spacing: -0.025em; margin: 0 0 .45em; } +h1 { font-size: clamp(2.6rem, 6vw, 4rem); } +h2 { font-size: clamp(2.1rem, 4.6vw, 3.3rem); } +h3 { font-size: 1.3rem; letter-spacing: -0.015em; line-height: 1.25; } +p { margin: 0 0 1em; } +code { font: .86em/1.5 var(--mono); background: var(--alt); border-radius: 6px; padding: .1em .38em; letter-spacing: 0; } +pre { position: relative; margin: 0 0 1.4em; background: var(--code); color: var(--code-ink); border-radius: var(--r); padding: 20px 22px; overflow-x: auto; font: 14px/1.7 var(--mono); letter-spacing: 0; } +pre:not(.diagram) { padding-right: 76px; } +pre code { background: none; padding: 0; font: inherit; color: inherit; } +pre .c, .c { color: #8e8e93; } +.copy { position: absolute; top: 12px; right: 12px; font: 12px var(--sans); color: #d2d2d7; background: rgba(255, 255, 255, .1); border: 0; border-radius: 999px; padding: 4px 11px; cursor: pointer; } +.copy:hover { color: #fff; background: rgba(255, 255, 255, .18); } +.skip { position: absolute; left: -999px; } +.skip:focus { left: 12px; top: 12px; z-index: 9; background: var(--bg); padding: 8px 12px; border-radius: 8px; } +.wrap { max-width: calc(var(--frame) + 48px); margin-inline: auto; padding-inline: clamp(20px, 4vw, 24px); } +.wrap.narrow { max-width: calc(var(--read) + 48px); } +.read { max-width: calc(var(--read) + 48px); } +.muted, .lead { color: var(--ink3); } +.note { font-size: 14px; color: var(--ink3); } +.center-text { text-align: center; } +.grad { background: var(--grad); -webkit-background-clip: text; background-clip: text; color: transparent !important; } +.eyebrow { font: 600 1.2rem/1.2 var(--display); color: var(--ink3); margin: 0 0 12px; letter-spacing: -0.01em; } + +/* header: a thin, translucent bar */ +.top { position: sticky; top: 0; z-index: 5; background: color-mix(in srgb, var(--bg) 78%, transparent); backdrop-filter: saturate(1.8) blur(20px); -webkit-backdrop-filter: saturate(1.8) blur(20px); border-bottom: 1px solid color-mix(in srgb, var(--line) 60%, transparent); } +.bar { display: flex; align-items: center; gap: 32px; height: 52px; } +.brand { display: inline-flex; align-items: center; gap: 8px; font: 600 17px var(--display); color: var(--ink); letter-spacing: -0.02em; } +.brand:hover { text-decoration: none; } +.brand svg { flex-shrink: 0; } +.nav { display: flex; gap: 28px; flex: 1; justify-content: center; } +.nav a { color: var(--ink2); font-size: 13.5px; letter-spacing: 0; } +.nav a:hover, .nav a[aria-current] { color: var(--ink); text-decoration: none; } +.gh { display: inline-flex; align-items: center; gap: 4px; height: 28px; border-radius: 999px; padding: 0 13px; font-size: 13.5px; white-space: nowrap; color: #fff; background: var(--btn); letter-spacing: 0; } +.gh:hover { background: var(--btn-hover); text-decoration: none; } +@media (max-width: 680px) { .nav { justify-content: flex-start; } .nav a:nth-child(n+3) { display: none; } .bar { gap: 20px; } } +@media (max-width: 420px) { .bar { gap: 14px; } .nav { gap: 16px; } } + +/* buttons */ +.ctas { display: flex; flex-wrap: wrap; gap: 14px 30px; align-items: center; justify-content: center; } +.btn { display: inline-flex; align-items: center; height: 46px; border-radius: 999px; padding: 0 24px; font-size: 17px; color: #fff; background: var(--btn); } +.btn:hover { background: var(--btn-hover); text-decoration: none; } +.more-link { font-size: 17px; } +.more-link::after { content: "›"; display: inline-block; margin-left: 5px; font-size: 1.15em; line-height: 1; } + +/* sections: full width, alternating white and grey */ +.band { padding-block: var(--gap); } +.alt { background: var(--alt); --card: #ffffff; } +@media (prefers-color-scheme: dark) { .alt { --card: #232325; } } +.head { max-width: 820px; margin: 0 auto 56px; text-align: center; } +.head h2 { margin-bottom: .35em; } +.head p { color: var(--ink3); font-size: clamp(1.1rem, 1.6vw, 1.3rem); line-height: 1.45; margin: 0 auto; max-width: 40em; } + +/* hero */ +.hero { padding-top: clamp(64px, 10vw, 120px); text-align: center; overflow: hidden; } +.hero .eyebrow { font-size: clamp(1.1rem, 1.8vw, 1.4rem); } +.hero h1 { font-size: clamp(3rem, 8.4vw, 6rem); letter-spacing: -0.035em; line-height: 1.02; margin-bottom: .28em; } +.hero .sub { font: 500 clamp(1.2rem, 2.1vw, 1.65rem)/1.35 var(--display); color: var(--ink3); max-width: 30em; margin: 0 auto 34px; letter-spacing: -0.015em; } +.works { margin-top: 44px; } +.works p { font-size: 13px; color: var(--ink3); margin: 0 0 14px; letter-spacing: .02em; } +.works ul { list-style: none; margin: 0; padding: 0; display: flex; flex-wrap: wrap; justify-content: center; gap: 14px 36px; } +.works li { display: inline-flex; align-items: center; gap: 10px; font: 500 16px var(--display); color: var(--ink); } +.works .logo { width: 26px; height: 26px; } +.logo { display: block; flex-shrink: 0; } +@media (prefers-color-scheme: dark) { .logo path[fill="#111"] { fill: #2c2c2e; } } +.shot { margin: clamp(56px, 7vw, 88px) auto 0; max-width: 1248px; padding-inline: clamp(12px, 3vw, 24px); } +.shot img { display: block; width: 100%; height: auto; border-radius: clamp(6px, .8vw, 10px); background: #2a2f8a; + box-shadow: 0 0 0 1px rgba(0, 0, 0, .06), 0 2px 6px rgba(0, 0, 0, .06), 0 40px 90px -40px rgba(20, 24, 70, .55); } +.shot figcaption, figure.chart figcaption { font-size: 13px; color: var(--ink3); margin-top: 18px; } + +/* bento: rounded tiles */ +.bento { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 20px; } +.tile { background: var(--card); border-radius: var(--tile); padding: clamp(28px, 4vw, 44px); min-width: 0; overflow: hidden; } +.tile h3 { font-size: clamp(1.4rem, 2.4vw, 1.75rem); margin-bottom: .4em; } +.tile p { color: var(--ink3); margin: 0; } +.tile.wide { grid-column: 1 / -1; } +.tile .stat { font: 700 clamp(3.4rem, 7vw, 5rem)/1 var(--display); letter-spacing: -0.04em; margin: 0 0 26px; color: var(--ink); } +.sim { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1.15fr); gap: 32px; align-items: center; padding-bottom: 0; } +.sim .text { align-self: center; padding-bottom: clamp(28px, 4vw, 44px); } +.sim .text p { font-size: 1.1rem; line-height: 1.5; } +.phones { display: flex; justify-content: center; gap: 28px; align-self: end; margin: 16px 0 -130px; } +.phones img { width: min(250px, 44%); border-radius: 34px; box-shadow: 0 0 0 7px #1d1d1f, 0 0 0 8px #3a3a3c, 0 30px 60px -20px rgba(0, 0, 0, .4); margin: 8px; } +.phones img:first-child { transform: translateY(48px); } +.pool { list-style: none; padding: 0; margin: 22px 0 0; font-size: 15px; } +.pool li { display: flex; justify-content: space-between; gap: 12px; padding: 11px 0; border-top: 1px solid var(--line); } +.pool span { font-weight: 500; color: var(--ink); } +.pool em { font-style: normal; color: var(--ink3); display: inline-flex; align-items: center; gap: 7px; text-align: right; } +.pool em::before { content: ""; width: 7px; height: 7px; border-radius: 50%; background: var(--good); flex-shrink: 0; } +.pool em.free::before { background: var(--line); } +.tile-logo .logo { width: 56px; height: 56px; margin-bottom: 26px; } +@media (max-width: 820px) { + .bento { grid-template-columns: minmax(0, 1fr); } + .sim { grid-template-columns: minmax(0, 1fr); min-height: 0; gap: 8px; } + .sim .text { padding-bottom: 8px; } + .phones { margin-bottom: -120px; } +} + +/* agents */ +.agents { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 20px; margin-bottom: 48px; } +.agents > div { background: var(--card); border-radius: var(--tile); padding: 36px 30px; text-align: center; } +.agents .logo { width: 52px; height: 52px; margin: 0 auto 22px; } +.agents p { color: var(--ink3); margin: 0; } +@media (max-width: 820px) { .agents { grid-template-columns: minmax(0, 1fr); } } +pre.center { max-width: 560px; margin-inline: auto; } + +/* performance: always dark */ +.dark { --bg: #000; --alt: #000; --card: #1d1d1f; --ink: #f5f5f7; --ink2: #d2d2d7; --ink3: #a1a1a6; --line: #38383d; --link: #2997ff; --code: #1c1c1e; + background: #000; color: var(--ink); } +.head .mega { font: 700 clamp(4.2rem, 13vw, 9.5rem)/1 var(--display); letter-spacing: -0.05em; margin: 0 0 20px !important; padding-bottom: .04em; } +.dark .head p.mega { max-width: none; } +.chart { margin: 0 auto; max-width: 960px; background: #111113; border-radius: var(--tile); padding: clamp(14px, 3vw, 32px); } +.chart img { display: block; width: 100%; } + +/* how it works */ +.steps { list-style: none; padding: 0; margin: 0; display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 20px; } +.steps li { background: var(--card); border-radius: var(--tile); padding: 34px 30px; } +.steps .n { display: grid; place-items: center; width: 40px; height: 40px; border-radius: 50%; background: var(--ink); color: var(--bg); font: 600 17px var(--display); margin-bottom: 22px; } +.steps p { color: var(--ink3); margin: 0; } +@media (max-width: 820px) { .steps { grid-template-columns: minmax(0, 1fr); } } + +/* details that open in place */ +.more { max-width: 820px; margin: 44px auto 0; } +.more > summary { cursor: pointer; color: var(--link); font-size: 17px; width: fit-content; margin-inline: auto; list-style: none; } +.more > summary::-webkit-details-marker { display: none; } +.more > summary::after { content: "+"; display: inline-block; margin-left: 8px; font-size: 1.1em; } +.more[open] > summary::after { content: "–"; } +.more[open] > summary { margin-bottom: 24px; } +.more > p { color: var(--ink2); } +.narrow .more > summary { margin-inline: 0; } +pre.diagram { font-size: 13px; line-height: 1.6; } + +/* compare */ +.trio { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 20px; margin-bottom: 40px; } +@media (max-width: 820px) { .trio { grid-template-columns: minmax(0, 1fr); } } +.trio .tile h3 { font-size: 1.3rem; } + +/* get started */ +pre.prompt { background: var(--alt); color: var(--ink); border-radius: var(--r); padding: 22px 76px 22px 24px; font: 15.5px/1.6 var(--mono); white-space: pre-wrap; } +pre.prompt .copy { color: var(--ink2); background: color-mix(in srgb, var(--ink) 8%, transparent); } +.needs { margin-top: 40px; padding-top: 32px; border-top: 1px solid var(--line); } +.checks { list-style: none; padding: 0; margin: 0 0 1.2em; } +.checks li { position: relative; padding: 6px 0 6px 30px; color: var(--ink2); } +.checks li::before { content: ""; position: absolute; left: 3px; top: 14px; width: 12px; height: 7px; border: solid var(--good); border-width: 0 0 2px 2px; transform: rotate(-45deg); } + +/* end */ +.final { text-align: center; padding-top: calc(var(--gap) * .35); } +.final h2 { font-size: clamp(2.6rem, 6.4vw, 4.6rem); letter-spacing: -0.035em; } +.final p { color: var(--ink3); font-size: 1.25rem; margin-bottom: 30px; } + +/* tables: a spec sheet */ +.table { overflow-x: auto; margin: 0 0 1.6em; border-radius: var(--r); background: var(--card); } +table { border-collapse: collapse; width: 100%; font-size: 15px; } +th, td { text-align: left; vertical-align: top; padding: 12px 16px; border-top: 1px solid var(--line); } +thead th { border-top: 0; font-size: 13px; font-weight: 500; color: var(--ink3); } +tbody th { font-weight: 500; } +td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; } +td strong { color: var(--ink); font-weight: 600; } +.us { background: color-mix(in srgb, var(--link) 8%, transparent); } + +/* cards (guide lists) */ +.cards { list-style: none; padding: 0; margin: 0 0 1em; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px; } +.cards a { display: block; height: 100%; background: var(--card); border-radius: 22px; padding: 26px 28px; color: var(--ink); transition: transform .2s ease; } +.cards a:hover { text-decoration: none; transform: translateY(-2px); } +.cards strong { display: block; font: 600 1.15rem/1.3 var(--display); margin-bottom: 6px; letter-spacing: -0.015em; } +.cards strong::after { content: " ›"; color: var(--link); } +.cards span { display: block; font-size: 15px; color: var(--ink3); line-height: 1.5; } +@media (max-width: 700px) { .cards { grid-template-columns: minmax(0, 1fr); } } +@media (prefers-reduced-motion: reduce) { .cards a { transition: none; } .cards a:hover { transform: none; } } + +/* FAQ and callouts */ +.faq h2 { text-align: center; margin-bottom: 1em; } +.faq details { border-top: 1px solid var(--line); padding: 20px 0; } +.faq details:last-of-type { border-bottom: 1px solid var(--line); } +.faq summary { cursor: pointer; font: 500 1.15rem/1.35 var(--display); list-style: none; display: flex; justify-content: space-between; gap: 16px; letter-spacing: -0.015em; } +.faq summary::-webkit-details-marker { display: none; } +.faq summary::after { content: "+"; color: var(--ink3); font-weight: 400; } +.faq details[open] summary::after { content: "–"; } +.faq details p { color: var(--ink2); margin: 12px 0 0; } +.faq .callout { margin-top: 48px; } +.callout { background: var(--alt); border-radius: var(--r); padding: 20px 24px; margin: 0 0 1.4em; color: var(--ink2); font-size: 15.5px; } +.callout p:last-child { margin: 0; } +.callout.warn strong { color: #b64400; } +@media (prefers-color-scheme: dark) { .callout.warn strong { color: #ff9f0a; } } + +/* articles */ +.article { padding-block: clamp(48px, 7vw, 88px) var(--gap); } +.read.article, .related { margin-inline: auto; } +.article h1 { font-size: clamp(2.3rem, 4.6vw, 3.3rem); letter-spacing: -0.03em; } +.article h2 { font-size: 1.75rem; margin-top: 2.1em; padding-top: .2em; } +.article h3 { margin-top: 1.6em; } +.article ul, .article ol { padding-left: 1.3em; } +.article li { margin-bottom: .35em; } +.article .lead { font-size: 1.25rem; line-height: 1.45; margin-bottom: 20px; } +.crumbs { font-size: 14px; color: var(--ink3); margin-bottom: 20px; } +.crumbs a { color: var(--ink2); } +.crumbs span { margin: 0 6px; } +.meta { font-size: 14px; color: var(--ink3); border-bottom: 1px solid var(--line); padding-bottom: 22px; margin-bottom: 30px; } +.meta a { color: var(--ink2); } +.tldr { background: var(--alt); border-radius: var(--r); padding: 22px 26px 8px; margin: 0 0 2em; } +.tldr h2 { font: 600 13px var(--sans); letter-spacing: .02em; color: var(--ink3); margin: 0 0 12px; padding: 0; } +.tldr ul { margin: 0 0 14px; } +.tldr code, .callout code { background: var(--bg); } +.article + .related { margin-top: calc(var(--gap) * -0.5); } +.related { max-width: calc(var(--read) + 48px); padding: 0 clamp(20px, 4vw, 24px) var(--gap); } +.related h2 { font-size: 1.5rem; } + +/* footer */ +.foot { background: var(--alt); border-top: 1px solid var(--line); padding-block: 44px; font-size: 13px; color: var(--ink3); } +.cols { display: grid; grid-template-columns: 2fr 1fr 1fr; gap: 40px; } +.cols nav { display: flex; flex-direction: column; gap: 8px; } +.cols nav a { color: var(--ink2); } +.label { font-size: 13px; font-weight: 600; color: var(--ink); margin-bottom: 6px; } +.brandline { color: var(--ink2); font-size: 14px; } +.brandline strong { color: var(--ink); } +.fine { color: var(--ink3); font-size: 12.5px; line-height: 1.55; max-width: 44em; } +.fine a { color: var(--ink2); } +@media (max-width: 760px) { .cols { grid-template-columns: 1fr 1fr; } .cols > div { grid-column: 1 / -1; } } +@media (prefers-reduced-motion: no-preference) { html { scroll-behavior: smooth; } }