Developers

Headless runs

Run Arx without windows from scripts, agents and CI, with a local MCP endpoint and only the grants you pass.

This page is a first draft. It may change before the public beta.

Arx --headless starts the browser without windows, a Dock icon or a menu bar. It runs the same browser and the same local MCP server as the app, and gives its own MCP client only the grants you pass. Every run ends with a clean stopped event.

Start a run

/Applications/Arx.app/Contents/MacOS/Arx --headless --allow read,screenshots,content --viewport 1280x800
OptionMeaning
--allowComma-separated grants for the run's MCP client: read (required), screenshots, content, interaction, manage. Default read. The client sees the run's whole profile: every space, including spaces added while it runs, and its Favorites. manage approves changes in advance for the whole run, or until --timeout.
--profile <absolute path>Use and keep a persistent profile. By default each run gets a fresh private profile that is deleted at exit.
--viewport <W>x<H>Page size in points, 320×240 to 3840×2160. Default 1280×800. Screenshots are this size times the run's deviceScale.
--timeout <seconds>Optional deadline, 10 to 86,400. The run exits with 75 when it's reached. Default: none.
--mcp-configuration <absolute path>Where to write the MCP client configuration. The file must not exist yet; it's created readable only by you. Default: mcp.json in the run's directory.
--url <url>First page for a new profile: http(s) or about:blank (default).

Start your MCP client with the mcpServers.arx entry of that configuration file. It launches Arx's bundled helper with the run's one-time credential.

Events

Stdout carries only events, one JSON object per line:

EventFields
readyconfiguration, profile, viewport, deviceScale, grants, grantsExpireAt, timeoutSeconds, pid
stoppingreason: signal, timeout, failure, parentExited, launcherExited or inputClosed
errorcode, message, exitCode
diagnosticcode, for example shutdownSlow (with seconds), authenticationProtected, or startupSlow (with phase and seconds) when the run isn't ready after 30 or 90 seconds: engine, window or automation says what it's still waiting for
rendererFailedtabID of a page whose renderer died. A reload recovers it.
authenticationRequiredtabID of a page that hit an HTTP authentication challenge
userActionRequiredtabID and prompts (webAuthentication, federatedSignIn)
stoppedexitCode, suppressedDialogs
{"event":"ready","grants":["read","screenshots","content"],"viewport":"1280x800", …}
{"event":"stopping","reason":"signal"}
{"event":"stopped","exitCode":0,"suppressedDialogs":0}

Wait for ready before connecting. Diagnostics from Arx and Chromium go to stderr.

Stopping

Send SIGTERM or SIGINT. A run without --timeout also stops when:

  • the process that started it exits;
  • an outer launcher in a chain such as npx → node → Arx exits;
  • stdin was a pipe at startup and reaches end of file. Keep the pipe open for as long as the run should last.

However it stops, a run on a persistent profile saves its tabs and history first, so a tab opened just before the stop is there next time.

Exit codes

CodeMeaning
0Stopped on request
64Invalid options
69Engine or MCP endpoint unavailable
70Startup failure (startupFailed), including no logged-in session and a key Arx can't read from the Keychain (ARX_SAFE_STORAGE_UNAVAILABLE on stderr)
73Profile in use or can't be created
75--timeout reached
2Shutdown hung and was forced to exit

Nobody is watching

A headless run never waits for a person:

  • A change outside the run's grant fails with userActionRequired.
  • Page alert, confirm and prompt dialogs get Chromium's default answer, and permission requests are denied.
  • HTTP authentication, passkey and federated sign-in prompts are cancelled and reported as events. Sign-in handoffs aren't available.
  • Arx writes no screenshot files. browser_capture returns the image to the client.
  • Casting is off. Arx doesn't look for Chromecasts on the network, and a site's Cast button fails at once.
  • Background tabs can be frozen, as in Chrome: once a loaded tab falls outside the five most recently shown or opened, its timers and scripts stop until it's selected or loads again. Reading, capturing or waiting on it doesn't wake it, so select a tab (selectTab) before waiting for it to change.
  • Arx doesn't ask sites for missing tab icons, since nobody sees the sidebar.

A persistent profile is locked for the run: a second run on it, or Arx already open on it, is rejected with profileInUse.

macOS draws pages through the window server, so a headless run needs a logged-in graphical session for the same user. It doesn't work from a plain SSH login with nobody logged in, or from a launchd daemon, so CI needs a runner that is logged in. Arx checks for the session before it starts anything: without one it reports startupFailed, says it needs a logged-in macOS session, and exits with 70 at once.

Macs without a display

A display is optional. A headless run works on a Mac mini with no monitor, a MacBook with its lid closed, or a Mac you reach only through Screen Sharing, as long as someone stays logged in. Start it from that session, for example from Terminal or an agent running there.

Arx renders pages at the main screen's scale, whether the screen is a real display or the one macOS or Screen Sharing provides, and at 2× when there's no screen at all. The scale is fixed when the run starts and reported as deviceScale in ready, so screenshots keep their size while a Screen Sharing session connects or ends.

Planned
Headless runs without a logged-in graphical session, such as from SSH or launchd.