macbox

io.github.opslanev0.6.2Updated Oct 6, 2026

A real Mac for your agent: build, test, run, and tap through iOS apps on the simulator.

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper Tools

Overview

AI-generated overview

Lets an assistant build, test, run, and drive native iOS apps on a remote cloud Mac, including simulator taps and screenshots.

What it does
macbox gives an MCP client tools to build iOS projects for the simulator, run XCTest and UI tests with one PASS/FAIL line per test, and launch the app on a simulator. It can take screenshots, read what is on screen, and tap, type, swipe, or press buttons so the agent can check its own work. A live browser link lets a person watch and use the running app. An optional mode adds Xcode tools such as LLDB debugging and simulator settings.
When to use it
Use it when an agent needs to compile, test, or interact with a native iOS app but is running on Linux or a cloud sandbox without Xcode. It suits Xcode projects, workspaces, Swift packages, CocoaPods, and XcodeGen setups; signing, TestFlight, React Native, and Flutter are not supported yet.
Requirements
A local process started with Node 18+ via npx, or the macbox CLI on macOS or Linux. Needs a macbox account and either a prior macbox login or the MACBOX_API_KEY environment variable. Network access to the macbox service is required, and it runs on desktop only.
Before you install
Builds run on a paid remote service billed per Mac minute at $0.05, with jobs under a minute free, so usage costs money. MACBOX_API_KEY is a secret and should be supplied as an environment secret rather than committed. Source files tracked by git are uploaded to the remote Mac; .env files are said to be excluded unless requested, so check what is sent. The service is closed source and the CLI is downloaded at install time.

Installation

In SourceWeft

  1. Open macbox in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[macbox]

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.

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-agentclaude 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 | shmacbox loginmacbox 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 toolCLIWhat it does
buildmacbox buildBuild for the iOS simulator (or macOS, for a Mac app)
testmacbox testRun tests on a fresh simulator; one PASS/FAIL line per test
screenshotmacbox screenshotLaunch the last build and return a picture
runmacbox runLaunch the app and keep it running; returns a live link
describe, tap, type, swipe, press_button, lookmacbox ui ...Use the running app like a person
stopmacbox stopEnd the running app
report_problemmacbox feedbackTell the macbox team when something on our side is wrong

For deeper work there is also macbox mcp --xcode: Sentry's open-source MobileBuildMCP 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

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.

Source: README.md at commit 828b055

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.6.2LatestOct 6, 2026