macbox 0.6.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Opslane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+<p align="center"><img src="https://raw.githubusercontent.com/opslane/macbox-agent/main/logo.png" width="96" alt="macbox"></p>
+
+# macbox
+
+**A real Mac for your coding agent.** macbox lets Claude Code, Codex, Cursor, or any MCP
+client build, test, run, and tap through native iOS apps on a real Mac in the cloud, from
+any machine, including Linux boxes and cloud agent sandboxes.
+
+- **Build and test:** `xcodebuild` and your XCTest and UI tests, on a Mac mini running the
+  latest Xcode. Your agent gets the results and the error lines.
+- **Run and drive the app:** launch it on the iOS simulator, read what's on screen, tap,
+  type, and swipe, so your agent can check its own work.
+- **Watch live:** every running app gets a browser link where you can watch and use it too.
+
+Pay per Mac minute, whole minutes only: $0.05, and a job under a minute is free. Get access
+and free credit at **[macbox.build](https://macbox.build)**.
+
+## Set up
+
+The quickest way: tell your agent
+
+> Set up macbox by following https://api.macbox.build/guide/
+
+Or pick your client:
+
+**Claude Code (plugin: skill + MCP tools)**
+
+```sh
+claude plugin marketplace add opslane/macbox-agent
+claude plugin install macbox@macbox
+```
+
+**Any MCP client** (Codex, Cursor, Claude Desktop, VS Code, ...), with Node 18+:
+
+```json
+{
+  "mcpServers": {
+    "macbox": { "command": "npx", "args": ["-y", "macbox", "mcp"] }
+  }
+}
+```
+
+**The CLI** (macOS or Linux):
+
+```sh
+curl -fsSL https://api.macbox.build/install.sh | sh
+macbox login
+macbox setup      # installs the skill for Claude Code and Codex, and notes in CLAUDE.md / AGENTS.md
+```
+
+Log in with `macbox login`, or set `MACBOX_API_KEY` (in a cloud agent, as an environment
+secret).
+
+## What your agent gets
+
+| MCP tool | CLI | What it does |
+|---|---|---|
+| `build` | `macbox build` | Build for the iOS simulator (or macOS, for a Mac app) |
+| `test` | `macbox test` | Run tests on a fresh simulator; one PASS/FAIL line per test |
+| `screenshot` | `macbox screenshot` | Launch the last build and return a picture |
+| `run` | `macbox run` | Launch the app and keep it running; returns a live link |
+| `describe`, `tap`, `type`, `swipe`, `press_button`, `look` | `macbox ui ...` | Use the running app like a person |
+| `stop` | `macbox stop` | End the running app |
+| `report_problem` | `macbox feedback` | Tell the macbox team when something on our side is wrong |
+
+For deeper work there is also `macbox mcp --xcode`: Sentry's open-source
+[MobileBuildMCP](https://www.mobilebuildmcp.com/) Xcode tools (LLDB debugging, Swift packages,
+simulator settings), running on the macbox Mac.
+
+## How it works
+
+`macbox` sends the files git tracks (never `.env` files unless you ask) to one Mac mini,
+into your own macOS VM that only you use and that can't reach other VMs or our network.
+Only changed files are sent after the first time, and the build cache stays, so the second
+build is fast. Native iOS apps work today: Xcode projects and workspaces, Swift packages,
+CocoaPods, XcodeGen. Not yet: signing, TestFlight, React Native, Flutter.
+
+Full guide: https://api.macbox.build/guide/ · Questions: [Discord](https://discord.gg/zukPCGsTnw)
+
+## This repository
+
+The open parts of macbox: the Claude Code plugin (`.claude-plugin/`, `skills/`, `.mcp.json`),
+the `macbox` npm package (`npm/`, which downloads the CLI from api.macbox.build and checks
+it against the published SHA256SUMS), and the MCP Registry entry (`server.json`). The macbox
+service itself runs on our Macs.
+
+MIT licensed.

package/bin/macbox.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// macbox on npm: runs the macbox CLI, downloading it on first use.
+//
+// The CLI is a single Go binary served from https://api.macbox.build/dl/. This wrapper
+// fetches the build for this OS and CPU, checks it against the published SHA256SUMS,
+// keeps it in ~/.macbox/bin/<version>/, and runs it with the same arguments, stdin,
+// stdout, and exit code. That makes `npx -y macbox mcp` work as an MCP server.
+//
+// Everything the wrapper itself prints goes to stderr: on stdout, an MCP client expects
+// nothing but protocol messages.
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const BASE = process.env.MACBOX_DOWNLOAD_URL || "https://api.macbox.build/dl";
+const HOME = process.env.MACBOX_HOME || path.join(os.homedir(), ".macbox");
+const BIN_DIR = path.join(HOME, "bin");
+
+function target() {
+  const plat = { darwin: "darwin", linux: "linux" }[process.platform];
+  const arch = { x64: "amd64", arm64: "arm64" }[process.arch];
+  if (!plat || !arch) {
+    throw new Error(`macbox runs on macOS and Linux (x64 or arm64), not ${process.platform} ${process.arch}`);
+  }
+  return `macbox-${plat}-${arch}`;
+}
+
+async function get(url, timeoutMs) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), headers: { "user-agent": "macbox-npm" } });
+  if (!res.ok) throw new Error(`${url}: ${res.status} ${res.statusText}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+// newestCached is the highest version already downloaded, for when the network is down.
+function newestCached(name) {
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(BIN_DIR).filter((v) => fs.existsSync(path.join(BIN_DIR, v, name)));
+  } catch {}
+  dirs.sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  return dirs.length ? path.join(BIN_DIR, dirs[dirs.length - 1], name) : null;
+}
+
+async function binary() {
+  const name = target();
+  let version;
+  try {
+    version = (await get(`${BASE}/VERSION`, 5000)).toString().trim();
+  } catch (e) {
+    const cached = newestCached(name);
+    if (cached) return cached; // offline: run what we have
+    throw new Error(`could not reach ${BASE} to download macbox: ${e.message}`);
+  }
+  if (!/^[0-9A-Za-z._-]+$/.test(version)) throw new Error(`unexpected version ${JSON.stringify(version)}`);
+  const file = path.join(BIN_DIR, version, name);
+  if (fs.existsSync(file)) return file;
+
+  process.stderr.write(`macbox: downloading macbox ${version} for ${name.slice(7)}\n`);
+  const [bin, sums] = await Promise.all([get(`${BASE}/${name}`, 120000), get(`${BASE}/SHA256SUMS`, 15000)]);
+  const want = sums
+    .toString()
+    .split("\n")
+    .map((l) => l.trim().split(/\s+/))
+    .find(([, f]) => f === name);
+  const got = crypto.createHash("sha256").update(bin).digest("hex");
+  if (!want || want[0] !== got) throw new Error(`checksum mismatch for ${name}; not running it`);
+
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, bin, { mode: 0o755 });
+  fs.renameSync(tmp, file); // atomic, so a second process never runs half a file
+  return file;
+}
+
+binary()
+  .then((file) => {
+    const child = spawn(file, process.argv.slice(2), { stdio: "inherit" });
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(sig, () => child.kill(sig));
+    child.on("exit", (code, signal) => process.exit(signal ? 128 + (os.constants.signals[signal] || 0) : code ?? 0));
+    child.on("error", (e) => {
+      process.stderr.write(`macbox: ${e.message}\n`);
+      process.exit(2);
+    });
+  })
+  .catch((e) => {
+    process.stderr.write(`macbox: ${e.message}\n`);
+    process.exit(2);
+  });

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "macbox",
+  "version": "0.6.2",
+  "description": "A real Mac for your coding agent: build, test, run, and tap through iOS apps from any machine. CLI and MCP server.",
+  "mcpName": "io.github.opslane/macbox",
+  "bin": {
+    "macbox": "bin/macbox.js"
+  },
+  "files": [
+    "bin/macbox.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "ios",
+    "xcode",
+    "simulator",
+    "claude-code",
+    "codex",
+    "cursor",
+    "agents"
+  ],
+  "homepage": "https://macbox.build",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opslane/macbox-agent.git"
+  },
+  "license": "MIT",
+  "author": "Opslane (https://macbox.build)"
+}