Get started with macbox

macbox runs Xcode and the iOS simulator on a real Mac in the cloud, so your coding agent can build, test, run, and tap through iOS apps from any machine, including Linux and cloud sandboxes.

To set it up, tell your agent: "Set up macbox by following https://api.macbox.build/guide/". You'll sign in with GitHub when it asks. New accounts start with $10 of credit.

Setup (for the agent)

Do these steps for the user, in order, and tell them what you did at the end.

1. Install the CLI

command -v macbox || curl -fsSL https://api.macbox.build/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
macbox version

2. Log in

First check: macbox status. If it shows credit, skip to step 3.

Otherwise run macbox login. It prints a link and a code, then exits without waiting. Give the user the link. They open it, check the code matches, and sign in with GitHub; a new user gets an account with $10 of credit on the way. When they say they're done, run macbox login again. It finishes and shows their minutes left.

• If the user already has an API key (from an invite email), they can run macbox login --key <key> themselves (in Claude Code, ! macbox login --key <key>). Never ask for a key in the chat or write it into the repo.
• In a cloud agent (Claude Code on the web, Codex cloud, Cursor background agents), a login doesn't last past the session. Ask the user to get a key at https://api.macbox.build/signup?key=1, add it as the MACBOX_API_KEY secret in the agent's environment settings, and add the install line from step 1 to the environment's setup script.

Then check: macbox status shows their credit and their Mac, which should say online.

3. Connect to macbox

From the root of the user's iOS project:

macbox setup
claude mcp add macbox -- macbox mcp      # Claude Code
codex mcp add macbox -- macbox mcp       # Codex

macbox setup installs the macbox skill for Claude Code and Codex, adds a Cursor rule, and adds a short marked note to the project's CLAUDE.md and AGENTS.md (anything already in them is kept). The note is how every agent that opens the repo, including cloud agents and teammates' agents, knows to use macbox. Offer to commit CLAUDE.md, AGENTS.md, and .cursor/rules/macbox.mdc. For other agents (Gemini CLI, OpenCode, and more), npx skills add opslane/macbox-agent installs the same skill.

Run the MCP lines for the agents the user has. They give you build, test, screenshot, and run, plus describe, tap, type, swipe, and look for the running app. The MCP tools appear after the agent restarts; until then, use the CLI.

4. Try it

macbox build --dry-run    # what would be sent
macbox build
macbox test
macbox run                # launches the app and prints a live link: give it to the user
macbox ui describe        # what is on screen, with element ids
macbox ui tap --id <id>
macbox stop

Using macbox well

• Exit codes. 0 it worked. 1 the build or tests failed: read the errors, fix the code, run again. 2 bad usage or a problem on this machine. 3 a problem on macbox's side or with the account; the message says which. Don't retry 3 in a loop; tell the user.
• Live sessions. macbox run builds the app, launches it on a simulator, and leaves it running. Always give the user the live link: they can watch the app and click, drag, and type to use it themselves. Use it through macbox ui (describe, tap --id, type, swipe, button home, screen out.png) or the MCP tools. A session ends with macbox stop, a new build, test, or run in the same folder, 10 minutes with nobody using or watching it, or the 30-minute job limit.
• Setup scripts. If the repo needs a step before Xcode can build (downloading prebuilt frameworks, copying a template .xcconfig), write it as a bash script at .macbox/setup. It runs from the repo root on the Mac before the first build, and again only when it changes. What it makes stays on the Mac.
• Stuck on something that looks like macbox's fault? macbox feedback "what happened" sends a note to the macbox team with the last job. Agents have a report_problem MCP tool for the same thing. A person reads every one.

Xcode tools (MobileBuildMCP)

For deeper work: LLDB debugging (breakpoints, stack, variables), Swift package builds and tests, simulator location and appearance, video. It is MobileBuildMCP (Sentry's open-source MCP server for Xcode), running on the macbox Mac:

claude mcp add macbox-xcode -- macbox mcp --xcode
codex mcp add macbox-xcode -- macbox mcp --xcode

• Use paths in the repo as usual. macbox maps them to the Mac's copy and back.
• Edits are synced to the Mac before every tool call; the session (and a debugger attached to the app) keeps running.
• The Mac starts on the first tool call (about a minute), not when the agent starts. macbox_live_link gives the user a link to watch the simulator.
• Telemetry to Sentry is off. Tools for physical devices, the Xcode app, and creating new projects are left out.

Several folders at once (git worktrees)

macbox runs two of your folders at the same time, on your one Mac. Each folder keeps its own code and build cache, and each running folder gets its own simulator. A third folder waits until one finishes; if both are busy with sessions, the older session ends to make room. Builds and tests are never cut short. In one folder, jobs take turns.

Where your code goes

• macbox sends your folder to one Mac mini, the same one every time, into your own macOS VM. Only you use that VM. It can reach the internet (to fetch packages), but not other VMs or our network.
• Only changed files are sent after the first time. Code and build cache stay there between runs; that is what makes the second build fast.
• If you don't run anything for 14 days, we delete all of it. macbox purge --yes deletes it now. Your own files are never touched.

What gets sent

• Files git tracks (submodules too), new files git doesn't ignore, and .xcconfig files.
• Not .env files (pass --include .env if the build needs one), .git, Pods, .build, DerivedData, or node_modules. Pods and Swift packages are fetched on the Mac.
• Generated files that git ignores: --include path/to/them. macbox build --dry-run lists every file.

What it costs

$0.05 per Mac minute. Each job pays for the whole minutes it ran; the part of a minute left over is free, so a job under a minute costs nothing. You pay only while a build, tests, a screenshot, or a live session runs. Uploading, waiting in line, and starting the VM are free. If something breaks on our side, you are not charged. Two folders at once cost twice as much per minute and finish sooner. macbox status shows what's left.

What works today

• Native iOS apps: Xcode projects, workspaces, Swift packages, CocoaPods, XcodeGen.
• The iOS simulator, on one Xcode version (the latest, Xcode 27), so the oldest iOS target is 15.0.
• Mac apps: build and test (unsigned). No screenshots or sessions.
• Not yet: signing, TestFlight, React Native, Flutter, private packages that need SSH keys.

What we log

So we can help before you have to ask, macbox records what each command did and how it ended: the command or MCP tool, exit code, how long it took, the job, the first error line (it may name a file), the CLI version, your OS, and which agent ran it. Never your code or file contents. We may read a job's output on the Mac when debugging it.

Help

Ask in the Discord (https://discord.gg/zukPCGsTnw), reply to your invite email, or run macbox feedback "...". We read every one.