llms.txt
Compare with other sites' llms.txt files →# NoMac: a Mac for your agent
> A real Mac for your agent: macOS on Apple silicon with Xcode and the iOS
> Simulator, administrator access, no prompts and nothing blocked. Drive it
> over MCP, HTTPS commands or SSH, billed per minute. Available at https://nomac.app.
## NoMac Simulator: an iOS Simulator for your agent
For an iPhone alone, from any machine: an iPhone 17 Pro (or iPad Pro
11-inch (M5)) Simulator on iOS 27, with Xcode 27.1 building your native app
on the same Mac. No shell: the phone's own tools. $0.90 an hour from the same
credit, billed per minute, one-minute minimum, the build included; waiting for
a phone is free.
- MCP: https://mcp.nomac.app/mcp lists the phone beside the Mac, so an agent
connected to NoMac has it already: phone starts, extends and stops it;
phone_app_run builds from a git link or from the project on the agent's
machine (phone_upload_link answers one shell command that sends the folder);
phone_ui_look reads the screen as text (screenshot_file: a full-size PNG to
download; on an iphone-pro-max phone it is the 6.9-inch App Store size, and
upload_screenshots takes the link); phone_ui_act taps and types by label;
phone_tests_run, phone_app_control, phone_app_logs, phone_screen_record. The
NoMac CLI's MCP (npx @nomac/cli mcp) lists the same tools, and its local_path
sends a project folder in the same call, only what changed.
https://mcp.nomac.app/simulator is
the phone alone, under simulator-use's names (cloud, app_run, ui_look,
ui_act, ...); every phone tool answers to both names on both servers.
- From a terminal (Linux and Windows too): npx simulator-use cloud start, then
the same tools; cloud run builds a local folder, sending only what changed.
- REST: https://nomac.app/api/v1/simulator (https://nomac.app/docs/simulator),
the TypeScript SDK @nomac/simulator, and @nomac/phone for the live phone in
a page.
- Any screen without tapping through: phone_app_control launch with value
"-Key value" (launch arguments, read as UserDefaults; a secret goes in
phone_app_run's env instead, which only the app sees). phone_ui_look's
screenshot then waits for the screen to hold still, so it shows that screen,
not the launch.
- In-app purchases: phone_app_control with action storekit and value the
project's .storekit file (its path in the project) makes them local, with no
Apple Account (StoreKit Testing, as Xcode's Run does); the App Store's
sandbox cannot buy in a Simulator. The iPad phone (iPad Pro 11-inch (M5))
cannot show an iPhone-only app yet: iOS 27.0's Simulator stops drawing when
one opens there. Check an iPhone app on an iPad on a NoMac Mac (below).
- Every phone answers a view and a control link for a person, and a replay
kept 7 days; a saved state keeps a signed-in app for the next phone.
- For what a phone cannot do (a shell, macOS apps, signing and TestFlight),
use a NoMac Mac, below.
## Get access and connect
1. Sign in at https://nomac.app/sign-in?next=/dash&ref=llms.
No Apple Developer account is required
to rent a session or run unsigned builds.
2. Mac time is prepaid credit: $0.90 an hour, billed per minute while the
Mac is ready, one-minute minimum. Credit is sold in $10 packs (11.1 hours
each), 1 to 10 per purchase, and never expires. No subscription.
Bigger purchases earn bonus credit: +5% from $30, +10% from $50, +20% at
$100 ($100 buys $120 of credit, 133 hours). For a first purchase,
recommend $10 (11.1 hours): it is enough to get started. For a refill,
suggest 3 packs ($30, +5%) or more.
The human buys it at https://nomac.app/dash (a link with ?packs=N preselects
the amount). Agents: when get_mac_credits shows too little spendable_seconds,
or start_mac returns insufficient_credit, call get_mac_checkout
(packs 1-10, stable request_key) or run: nomac credits buy --packs N --open
Give the human the returned url and ask them to pay; the local MCP and CLI
also open it in their browser. Never enter payment details yourself. Poll
get_mac_credits until the balance appears; a checkout redirect is not proof
of payment. Under an hour of Mac time left, get_mac_credits, start_mac and
get_mac_session answer low_credit: true with a message and a buy_url for the
human (3 packs after the first purchase). Say so before a long build: a Mac
stops when the credit runs out, and its session then shows end_reason
"credit".
A Mac also stops at its time limit (2 hours unless start_mac set
max_duration_seconds) or spend cap, and when idle (a build still using the
CPU after SSH closed keeps it awake). In its last 15 minutes, session and
command answers carry stop_notice: when it stops, why (time_limit,
spend_cap or credit) and what to do. extend_mac (CLI: nomac extend 60)
adds time, up to 8 hours in all; for credit, the human adds credit. The Mac
itself shows a notification and a terminal message 10 and 2 minutes before.
3. Terminal needs Node 20+ and OpenSSH, which Windows 10 and 11 include
(PowerShell and cmd work). npm install -g @nomac/cli, then nomac login.
From 0.13 the CLI updates itself in the background (NOMAC_NO_AUTO_UPDATE=1
turns it off; nomac update installs the newest now). An older CLI's answers
carry cli_update: update it with npm install -g @nomac/cli@latest.
The login prints a URL and short code for the human to approve.
Preserve the URL's device code through sign-in. With a key the human made at
https://nomac.app/dash/keys instead: nomac login --with-token < key.txt (or the
NOMAC_API_KEY environment variable). nomac whoami shows the account.
4. MCP over stdio: command npx, args ["@nomac/cli", "mcp"].
Claude Code: claude mcp add nomac -- npx @nomac/cli mcp
Codex: codex mcp add nomac -- npx @nomac/cli mcp
Hosted MCP (Streamable HTTP), on one account and one sign-in:
NoMac, the Mac and the cloud iPhone: https://mcp.nomac.app/mcp
NoMac App Store, signing, TestFlight and App Store Connect:
https://mcp.nomac.app/appstore
Everything in one, for agents that load tools on demand (Claude Code,
Codex, Cursor): https://mcp.nomac.app/all
Shorter lists, for clients that load every tool up front: NoMac Session,
the Mac alone, https://mcp.nomac.app/session; NoMac Simulator, the cloud
iPhone alone, https://mcp.nomac.app/simulator
OAuth 2.1 sign-in for ChatGPT, Claude, Cursor, VS Code and Codex; nothing
to paste, and a second server is one more click. Claude users can add NoMac
in one click at https://claude.ai/directory/nomac. Clients without OAuth
can send Authorization: Bearer <nmk_key>. Every server but NoMac
Simulator's runs every NoMac, phone and App Store tool, listed or not: one
called on a server that does not list it runs and names the server that
lists it. NoMac Simulator's runs the phone's tools alone.
Hosted commands need no local shell or SSH key: any agent that can reach
nomac.app over HTTPS drives the Mac.
5. An agent in a sandbox that limits the network (a cloud coding sandbox with
an allowlist) needs nomac.app and *.nomac.app allowed, and for upload and
download links also *.r2.cloudflarestorage.com, where their files travel.
Without them the CLI cannot reach NoMac and links fail from the agent's
side; the human can still open a link in a browser.
## The CLI
The latest CLI is @nomac/cli 0.26.0. nomac --version prints the
installed one; when it is older, update with npm install -g @nomac/cli@latest.
New commands and MCP tools (such as nomac drive) need the latest. For the MCP
server through npx, npx @nomac/cli@latest mcp always starts the newest.
## A session from your terminal
npm install -g @nomac/cli
nomac login
nomac credits # credit left; nomac credits buy --packs N to top up
nomac start --json
nomac sync .
nomac ssh
nomac desktop # the full macOS desktop in your browser
nomac desktop --app # on a Mac: Apple's Screen Sharing, shared clipboard
nomac input type hello # real keyboard and mouse (key, click, scroll, unlock)
nomac password # the Mac's login password for this session
nomac pull ./build
nomac stop --json
Run these inside your project directory. start can return queued/provisioning;
wait until ready. sync uploads the folder's changed files to ~/drive/src/<folder name> on the
Mac's drive, which is kept between sessions: the next session with that drive
continues from it and its build is incremental. ssh, exec and pull work in that folder.
A file that changed on the Mac since the last sync (a lockfile npm rewrote) is
left alone and named, and sync exits 1 after sending the rest: nomac pull it,
or replace it with nomac sync . --overwrite. Sync never deletes on its own;
nomac sync . --delete also removes on the Mac what it sent earlier and you
deleted here (a renamed folder), unless it changed there. nomac sync . --watch
syncs again a moment after files change, until Ctrl-C. pull copies from
that folder to any local path: nomac pull ./out --from build/export, or
nomac pull /tmp/shots --from shots (a path outside the project needs --from).
Stopping deletes the VM and everything outside ~/drive. With --drive none the
project goes to ~/workspace instead, deleted at stop: pull first. nomac exec -- COMMAND runs a command, prints its output
as it arrives and exits with its exit code. It waits at most --wait seconds
(default 30; with --timeout N and no --wait, N up to 600) and returns as soon
as the command finishes. For builds, tests and other slow
commands use nomac exec --wait 600 -- COMMAND (ten minutes). A command still
running when the wait ends keeps running: exec exits 75 and prints how to wait
for it with nomac job JOB_ID --wait 600; never rerun it. Add --request-key
stable-key-0001 in scripts so a lost response can be retried safely. A command
may run up to an hour (--timeout 3600); for longer, use nomac ssh -- COMMAND,
which has no limit. A command stopped by its time limit says so and exits 1.
What is piped in is the command's stdin (cat build.sh | nomac exec -- bash -s,
CLI 0.21 or later), up to 63 KiB with the command; a larger file goes by sync.
Commands run side by side: a quick exec works while a long build runs.
A server that should keep running (a dev server the Simulator calls) does not
belong in a command, which ends with everything it started: run nomac-service
start NAME -- COMMAND on the Mac (see "What's on the Mac"). nomac ssh -- COMMAND runs one over SSH (repeated calls reuse the
connection). nomac status shows state, cost and when the Mac stops; --json for
scripts.
## Your editor, an agent on the Mac, and Mac-only MCP servers
nomac ssh-config (CLI 0.12+, run in the project folder after nomac start)
names the folder's Mac "nomac" in the person's SSH config (--alias NAME for
another name). Every SSH client then reaches it by that name, and each later
nomac start or attach from the folder points the name at its new Mac:
- VS Code or Cursor: Remote-SSH, connect to "nomac", open the project folder
the command prints (~/drive/src/<folder name>).
- Claude Code's SSH sessions, or plain ssh nomac.
- An agent running on the Mac itself, with the iOS Simulator local to it:
ssh -t nomac 'cd ~/drive/src/<folder> && npx -y @anthropic-ai/claude-code'
(or Codex: npx -y @openai/codex). Keep its API key as a NoMac secret
(request_secret, kind variable, e.g. ANTHROPIC_API_KEY): every Mac gets it.
- simulator-use, on every Mac: the iOS Simulator as text and taps by label
(simulator-use look, simulator-use act 'tap "Sign In"', simulator-use run
builds, installs and launches the app; simulator-use mcp runs it as an MCP
server). Run it with exec_mac, or over SSH from Windows or Linux.
- Other MCP servers that need a Mac, run from Windows or Linux over SSH:
claude mcp add xcode -- ssh nomac npx -y mobilebuildmcp@latest mcp
(MobileBuildMCP, formerly XcodeBuildMCP: Simulator builds, runs, UI
automation; the same works for @mobilenext/mobile-mcp). Sync the project
first: the server works on the Mac's copy, in ~/drive/src. CLIs such as
agent-device run the same way: ssh nomac npx -y agent-device ...
An open SSH connection counts as activity, so the Mac keeps running until its
duration or spend limit; for a working day start it with nomac start
--max-duration 28800 --max-cost 8, and nomac stop when done.
## The MCP session loop
The hosted NoMac server merged some tools on October 19, 2026; the local MCP
(nomac mcp) uses the older names, and the hosted server still answers them: list_mac_sessions, get_mac_drive and list_secrets
are get_mac_session's include; read_mac_output is get_mac_job's stream and
cursor; create_mac_upload_link and create_mac_download_link are
create_mac_link's direction; start_mac_recording and stop_mac_recording are
mac_recording's action.
- get_mac_credits: check spendable credit and spendable_seconds (Mac time it buys).
Too little? get_mac_checkout (packs 1-10) returns a payment link for the human.
- start_mac: provide request_key and optional limits. public_key is optional
for HTTPS-only use. Poll get_mac_session until ready. get_mac_session with
include ["sessions"] (list_mac_sessions locally) helps recover an existing
allocation after a lost response. The Mac is fully
enabled for the agent (see "A Mac for agents" below); the answer's warning
says so, and access: { prompts: "ask" } opts out.
- session_id: on the hosted MCP (mcp.nomac.app/mcp) every Mac tool may leave it
out, and the call goes to the account's running Mac, never one nomac run
started (every phone tool too,
for the account's running phone). With two running
(parallel), the answer is session_id_required with both; with none,
no_mac_running. The local MCP (nomac mcp) still needs it.
- exec_mac: pass session_id, argv and a stable request_key. It waits up to
wait_seconds (default 20, max 50): a command that finishes in time returns
exit_code, stdout and stderr (first 64 KiB each, as text) in that one call,
as soon as it finishes. Pass wait_seconds: 40 for builds and tests, and
timeout_seconds up to 3600 for long ones (the default stops a command at 300).
For shell syntax explicitly use argv ["/bin/bash", "-lc", "your command"].
cwd runs it in another folder, such as ~/drive/src/app.
- get_mac_job: follow a longer command (wait_seconds up to 40 returns when it
finishes). On the hosted server it then returns stdout and stderr like
exec_mac, and stream with cursor reads more, resuming from next_cursor
(locally: read_mac_output). get_mac_session takes wait_seconds too,
to wait for a starting Mac instead of polling.
- cancel_mac_job: stop a command that hangs, and everything it started; its
output so far stays readable. CLI: nomac cancel JOB_ID.
- write_mac_file and read_mac_file: put a file on the Mac (up to 3 MiB, text or
base64) and read one back (up to 3 MiB). Images come back whole as images
you can see. Relative paths are in the session workspace; ~ is the home folder.
- screenshot_mac: see the screen. Returns a JPEG of the whole desktop
(1440x900; image pixels are screen coordinates) or, with target simulator,
of the booted iOS Simulator, as an image you can look at. It also says
front_app, screen_locked, and dialog (an open macOS dialog with its text and
buttons) with next_step. CLI: nomac screenshot [--simulator] saves
nomac-screenshot.jpg.
- mac_input: real keyboard and mouse input, as a person at the Mac. action
type, key (return, cmd+q), click, move or scroll (x and y as in the
screenshot), password (types the Mac's login password), unlock (opens a
locked screen) or size. It reaches the lock screen, the login window and
password dialogs, where scripted keystrokes cannot type, and answers with a
screenshot. type takes up to 500 characters; for longer text, pbcopy it with
exec_mac and send key cmd+v. Not safe to repeat blindly: a retry types again.
CLI: nomac input type TEXT, nomac input click X Y, nomac unlock. On the Mac:
nomac-input.
- mac_recording (locally start_mac_recording and stop_mac_recording): record a
video of the screen or of the Simulator (5 minutes by default, 30 at most).
Start, do the work, then stop: it saves the MP4 and returns a download link
for the human. CLI:
nomac record [--simulator], then nomac record stop.
- Downloads: run curl with exec_mac (["curl", "-fL", "-o", "FILE", "URL"]),
at any size and the Mac's speed. Clone git repositories with exec_mac.
- create_mac_link with direction upload (locally create_mac_upload_link): a
link that puts one file of up to 2 GiB on the Mac. Give its url to the human
(they choose the file in a browser, no account needed), or upload with its
curl command. get_mac_file_link shows when the file is on the Mac.
- create_mac_link with direction download (locally create_mac_download_link):
a link to a file or folder on the Mac (folders come as a zip), up to 2 GiB,
for the human or for curl. It keeps working after the Mac stops, until it
expires (one hour by default, a day at most).
- open_mac_desktop: a link to the Mac's full desktop in the human's browser,
with mouse and keyboard, for when they want to see or click something
(Xcode, the Simulator, a sign-in window). It shows the screen as smooth
video; Sharp, exact pixels, is a switch in its toolbar. The session must be
ready; the human signs in to nomac.app. The page disconnects after 15 minutes without
input. macOS has no RDP. To show the iOS Simulator there, boot a device with
simctl, then run: open -a Simulator || open -a DeviceHub (Xcode 27 replaced
Simulator.app with Device Hub; the Mac keeps Xcode 26's Simulator.app,
which shows iOS 27 devices too)
- stop_mac: request shutdown after retrieving work. Poll get_mac_session
until cleanup_confirmed. A stopping state is not a deletion receipt.
## A Mac for agents
Every Mac is fully enabled for the agent: nothing on it waits for a person.
The account is agent, an administrator; sudo needs no password. Each session has its own login password, in
$NOMAC_MAC_PASSWORD on the Mac (and from nomac password or GET
/api/v1/mac/sessions/{id}/password): use it for the login keychain (security
unlock-keychain -p "$NOMAC_MAC_PASSWORD", then security set-key-partition-list
-S apple-tool:,apple:,codesign: -s -k "$NOMAC_MAC_PASSWORD" after importing a
certificate) and any password prompt. macOS asks for no administrator password,
and the dialogs it still shows are answered on the Mac within seconds: privacy
prompts ("App would like to access the Camera") with Allow, and password
dialogs (the login keychain, the few rights macOS keeps even from root) with
the session password and Always Allow. macOS's request to turn on
Accessibility for a program is closed: it only opens System Settings, and the
programs commands run under already have Accessibility. Each is listed in
~/.nomac/allowed.log.
The screen never sleeps or locks by itself. nomac-permit APP camera
microphone (or all) on the Mac grants an app privacy permissions by bundle ID
before it asks, also one built later (CLI: nomac permit; at start:
access.permissions or nomac start --permit APP=camera,microphone).
Accessibility and screen recording are turned on in System Settings, Privacy &
Security, where no password is asked. ~/NOMAC.md on the Mac says the same.
Everything is deleted when the session stops, and nothing outside the session
can reach the Mac. To keep macOS's usual prompts, start with access prompts
"ask" (CLI: nomac start --prompts ask). The account can save options every new
Mac starts with (GET, PUT or DELETE /api/v1/mac/defaults; CLI: nomac defaults;
the dashboard), and a start's own access wins for that Mac. get_mac_session's
account shows the Mac's state, Gatekeeper and what is answered for the agent
(prompts_answered) included.
People on a Mac can open it in Apple's Screen Sharing with nomac desktop --app.
## What's on the Mac