CLI, API & MCP

Everything the app does can also be driven without its window. The app binary — bromure-ac, inside Bromure Agentic Coding.app/Contents/MacOS/ — is also a multi-command CLI, an HTTP control plane, an MCP server for outside AI tools, and an AppleScript target. Inside every VM, a set of built-in MCP servers gives the agents their own view of Bromure. This chapter is the reference for all of them.

The surfaces, from the outside in:

• The bromure-cli command line — a Docker/kubectl-style CLI for machines, VMs, terminals, commands, traces, models, remote access, and enrollment.
• The control plane — the same operations as JSON over HTTP, on an owner-only Unix socket and, optionally, on a loopback TCP port.
• The AC MCP server (bromure-ac mcp) — lets an AI tool on your Mac (Claude Code, Claude Desktop) manage the app.
• The in-guest MCP servers — built into every VM: the browser, automations, infrastructure, delegation, and, for specific sessions, the task board and the Switchboard.
• AppleScript — the Bromure AC Suite dictionary.

Throughout this chapter, and in the CLI, a machine is called a workspace (its name in the settings editor and in the command line). Sessions in the sense of agent conversations are reached through the /agent-sessions routes; the older /sessions routes and the session wording in the CLI and AppleScript refer to a machine's window.

The control plane: socket and API

Every surface speaks HTTP to the running app over one of two transports:

The CLI never talks to a VM directly. Each subcommand is a thin HTTP client over the control socket, so the same commands work locally and — when the socket is tunneled over SSH — against a remote instance from a rich client. If no agent is running when you invoke a command that needs one, the CLI autostarts a windowless background agent (bromure-ac run --headless) and waits up to 40 seconds for it to answer /health. Read-only commands (vm ls, describe, trace …) do not autostart; they print No bromure-ac agent running. instead.

Note: The control socket is always available while the app runs and is independent of the Enable automation server switch. That switch only governs the TCP listener on port 9223. You do not need to enable the automation API to use the CLI.

The bromure-cli command line

You can call the binary by its full bundle path, but the short name is more convenient. Choose Bromure Agentic Coding › Install Command-Line Tool… in the app menu. The alert Install the “bromure-cli” command-line tool? explains that it creates a symlink at /usr/local/bin/bromure-cli and needs your admin password once; click Install (or Cancel). On success, Command-line tool installed tells you to run bromure-cli --help. The app never offers this at launch any more — the menu item is the only way in, and you can run it again at any time (for example after moving the app).

The same binary behaves differently depending on the name it is called by:

• As bromure-cli it hides the app-internal commands — image management (init, info, reset, and the publish-pipeline tools), the mcp server, and the GUI run default — and exposes only the terminal-facing groups (Workspaces, Tracing, Local inference, Enterprise features, remote). A bare bromure-cli prints help instead of launching the app.
• As bromure-ac (the binary inside the app bundle) everything is available and the default subcommand is run, which launches the GUI.

The examples below use bromure-cli; use the full …/MacOS/bromure-ac path for the commands only it exposes.

Commands accept a workspace id, a short-id prefix, or its name wherever a workspace argument is shown. The vm and workspaces command groups are aliases for each other. What a machine is, and how it relates to sessions, is covered in Machines.

The app and the background agent

Image management

The base image is installed once. These commands exist only under the bromure-ac name.

Note: If no base image exists, launching the GUI routes you into the onboarding wizard, which installs the image in place — see Installation.

Workspace and VM control

This is the core group. vm run is deliberately Docker-shaped: it boots a workspace and hands your terminal to the guest's shared bromure tmux session.

A few operational details worth knowing:

• vm run flags. --tool takes an agent id: claude, codex, grok, kimi, or omp. --auth is token, subscription, bedrock, or local. An unrecognized value is an error that lists the valid values, for example Invalid --tool “gpt” — expected one of: claude | codex | grok | kimi | omp.; workspaces create checks --tool and --auth the same way. -v/--volume <hostdir> mounts a host folder at ~/<basename> in the guest (repeatable, up to 8). -d/--detach boots the VM and returns instead of attaching. --rm deletes the workspace and its disk when the VM stops. Detach from an attached tmux with Ctrl-b d — that leaves the VM running.
• Agents come from Models. The tool and auth flags only seed a new workspace. Which model and provider each agent actually uses comes from Preferences › Models and the workspace's own Models pane — see Models & Providers.
• TTY-aware. The Docker-style default of handing the terminal to tmux applies only on a real terminal; piped or scripted invocations behave as if you passed -d.
• workspaces create values. Colors are blue, red, green, orange, purple, pink, teal, or gray.
• Blank-keep on edit. workspaces edit exports the whole config with secrets blanked; a saved-back document with a blank secret keeps the stored value, so a round-trip can never wipe your keys. An unchanged buffer saves nothing; invalid JSON aborts.
• Exec waits. vm exec waits up to 10 seconds for the guest shell agent; a 502 means the VM may not be running or the name did not match. Approval prompts that fire during an attached session are rendered on your terminal (see Consent over attached terminals), never inside the guest.

Checking a disk from the command line

vm fsck is the scriptable twin of the ext4 browser's Run fsck… and of the Repair Disk button the app shows when a boot stops on filesystem errors. It uses Bromure's own ext4 checker, so nothing needs to be installed.

bromure-cli vm kill "Web app"            # the workspace must be stopped
bromure-cli vm fsck "Web app"            # check the system disk, report only
bromure-cli vm fsck "Web app" --repair   # replay the journal, clear the error flag
bromure-cli vm fsck "Web app" --home     # check the home image instead

It refuses to run while the workspace is running. The output ends with one of these summaries: "Filesystem is clean.", "Filesystem repaired; it is now consistent.", or "Filesystem has errors this checker cannot repair." A check without --repair that finds problems suggests re-running with --repair. The command exits with status 4 while errors remain. The checker's scope and limits are described in Advanced.

Models, routing, and Fusion

Model and provider settings are covered in Models & Providers and multi-model synthesis in Fusion; the CLI toggles are:

Trace inspection

These read the per-workspace proxy traces. They return nothing unless the workspace has tracing enabled — see Tracing settings — and the full story is in Tracing & Audit.

Remote access

The optional SSH front door is disabled by default and documented fully in Remote Access & Clients. All operations go through the running app over the control socket.

Enterprise enrollment

CLI counterparts of the Log in to bromure.io… sheet, for scripted device provisioning. See Enterprise.

Integration and internal commands

The remote TUI (__remote-menu)

When SSH remote access is enabled, every remote login is forced (via ForceCommand) into a hand-rolled ANSI terminal UI rather than a shell — an alternate-screen, 256-color menu driven by arrow keys and digits that works over any SSH PTY (use ssh -t). It mirrors the CLI as menus:

• Workspaces — create with a single-screen form (Name, Tool, Auth, API key, Memory, Color, Folders, Generate SSH, Full settings…, Create), per-workspace actions (Attach, New tab, Describe, Configure…, Fusion, Routing, Worktrees…, Reboot…, Suspend, Kill for running workspaces; Start, Describe, Configure…, Delete for off ones), and a raw table view. Configure… offers the settings editor's panes as text forms; its Models form is read-only (the server's providers, and whether the workspace overrides them), since models are chosen in the app.
• Models — installed models and the download catalog; picking an uninstalled model offers to model pull it inline with live progress.
• Trace — Summary / Hostnames / Leaks / Recent / Clear.

While you are attached to a workspace's tmux, a magic keychord (default Ctrl-], shown in the banner) pops a host-drawn controller overlay: a tab tree, New tab, Worktrees…, Fusion, Routing, Edit settings…, Reboot…, Suspend, Disconnect. The guest never sees the trigger key — override it with the remote/overlay-key file or $BROMURE_OVERLAY_KEY. Ctrl-b d disconnects from tmux back to the menu. The remote TUI works on machines and their terminals; agent sessions, rooms and the Switchboard are reached from the rich client instead. The full remote story is in Remote Access & Clients.

The loopback automation API

The control plane can also be exposed as JSON over HTTP on TCP, for scripting from any language. It is off by default.

Enabling it

Open Preferences… › Automation (⌘,) — the Automation API & MCP server pane.

1. Turn on Enable automation server. When it is on, the pane reads Listening on 127.0.0.1:9223; turning it off stops the server immediately.
2. Optionally set Port (captioned (default: 9223)) and Bind address (default 127.0.0.1). Port and bind address take effect the next time the server starts — toggle the switch off and on to apply them now.

You can also flip the switch without the GUI:

defaults write io.bromure.agentic-coding automation.enabled -bool true

Warning: Setting Bind address to anything other than 127.0.0.1 exposes the API — and the MCP server it backs — to the network, and the pane warns Non-loopback bind exposes the API to the network. The MCP server has no auth. There is no authentication on the TCP listener beyond the loopback boundary and the BROMURE_DEBUG_CLAUDE gate below. Leave the bind address on loopback unless you have a specific, trusted reason not to.

Authentication model

The TCP listener and the control socket serve the same routes, but with different access:

In other words: the control socket is the full-access, owner-only path; the TCP API opens the safe read subset on loopback and gates everything else behind the debug flag. Path segments are single percent-encoded (so workspace names with spaces work).

Endpoints for scripting

The most useful routes:

Because the control socket path contains spaces, capture it in a variable first:

SOCK="$HOME/Library/Application Support/BromureAC/control.sock"

# Full mirror snapshot (control socket only)
curl --unix-socket "$SOCK" http://localhost/state

# List running VMs
curl --unix-socket "$SOCK" http://localhost/vms

# Boot a workspace by name
curl --unix-socket "$SOCK" -X POST http://localhost/vms \
  -d '{"profile":"Web app"}'

# Answer a queued lifecycle prompt with one of its offered button labels
curl --unix-socket "$SOCK" -X POST http://localhost/prompts/PROMPT_ID/answer \
  -d '{"choice":"Not Now"}'

The safe subset works over the TCP API once you have enabled it — for example, listing workspaces and opening a machine's window needs no debug flag:

curl http://127.0.0.1:9223/profiles
curl -X POST http://127.0.0.1:9223/sessions -d '{"profile":"Web app"}'

Note: The control-plane routes are an integration surface shared with the rich client, not a versioned public API; their request and response shapes can change between releases. The CLI commands above are the stable way to script Bromure. Debug-only routes, environment variables, and file locations are catalogued in the Appendix.

The AC MCP server (bromure-ac mcp)

bromure-ac mcp runs a stdio JSON-RPC MCP server (server name bromure-ac) that lets an AI tool on your Mac manage the app. It wraps the automation HTTP API and AppleScript, so enable the automation server first — the listing and window tools call the HTTP API at --api-url (default http://127.0.0.1:9223). It is not available under the bromure-cli name.

The tools it exposes:

• bromure_ac_list_profiles, bromure_ac_list_sessions
• bromure_ac_open_session (opens a workspace's window; waits up to 30 seconds), bromure_ac_close_session
• bromure_ac_get_profile, bromure_ac_set_profile (atomic JSON replace, id preserved)
• bromure_ac_get_profile_setting, bromure_ac_set_profile_setting

With --debug (and BROMURE_DEBUG_CLAUDE set on the app) it adds bromure_ac_app_state, bromure_ac_vm_exec, bromure_ac_vm_read_file, and bromure_ac_vm_write_file.

To wire it into Claude Code, add the following to ~/.config/claude-code/.mcp.json (or your client's equivalent). This is the exact snippet the MCP client configuration section of the Automation pane shows:

{
  "mcpServers": {
    "bromure-ac": {
      "command": "/Applications/Bromure Agentic Coding.app/Contents/MacOS/bromure-ac",
      "args": ["mcp"]
    }
  }
}

Note: The get/set profile tools shell out to osascript (AppleScript against the running app), so the GUI app must be running and macOS may prompt once for Automation permission. Profile JSON travels with secrets blanked unless BROMURE_DEBUG_CLAUDE is set.

MCP servers inside the VMs

Separately from the AC MCP server, Bromure gives the agents inside every VM a set of built-in MCP servers — no configuration needed. Each is a small Python stdio shim staged read-only into the guest under /mnt/bromure-meta/; the shim dials the host over vsock and reconnects forever on drops, so the agent never loses its tools. The host serves the tools, and every call is checked there: an agent can only see and act on what its own machine and session are entitled to.

The browser, automations, infrastructure and delegation servers are written into each agent's own MCP configuration alongside the servers you add in the machine's MCP pane (MCP settings). The task-board and Switchboard servers are passed only to the runs that need them.

The browser server

The browser server drives the machine's embedded Chromium, which runs in its own disposable VM. Its 23 tools cover navigation and inspection — browser_navigate, browser_new_tab, browser_list_tabs, browser_activate_tab, browser_close_tab, browser_back, browser_forward, browser_reload, browser_screenshot (with a full-page option), browser_evaluate, browser_get_text, browser_get_html, browser_get_links, browser_click, browser_fill, browser_type, browser_press_key, browser_wait_for, browser_network, browser_network_summary, browser_clear_network, browser_console, and browser_pick_element (an interactive 60-second element picker).

A tool call against a closed browser opens it and waits for the cold boot. Because the browser is a separate VM, the server's instructions tell agents to reach a dev server on their machine by the machine's LAN IP (hostname -I), never localhost. The full story is in The Embedded Browser.

Note: On a rich client, the agents' browser-MCP stream can be carried over the SSH connection so a remote agent drives the browser pane you see locally. See Remote Access & Clients.

OAuth for MCP servers you add

HTTP MCP servers you add in the editor can authenticate through the host-side OAuth broker: it performs RFC 8414 discovery and RFC 7591 dynamic client registration (as Bromure AC), runs a PKCE authorization-code flow in your system browser, and serves the callback on a loopback listener (ports 28500–28599). The success page reads Authorized — You can close this tab and return to Bromure AC. The whole flow runs on the host, so the VM never sees real OAuth credentials.

AppleScript (Bromure AC Suite)

A scripting dictionary, the Bromure AC Suite, is another automation surface — useful for orchestration and for screenshot tooling that needs window IDs. Target application "Bromure Agentic Coding" from Script Editor or osascript. It covers:

• Profiles — list profiles, create ac profile <name> [color <c>] (returns a UUID), delete ac profile <name|uuid>, and full-document round-trip via get profile json / set profile json (the whole profile; id preserved; stored secrets merged under blank fields).
• Per-field settings — get profile setting … key … / set profile setting … key … to value ….
• Editor windows — open profile manager, open ac profile editor, close ac profile editor, select editor category <key>, and get editor window id / get main window id (a CGWindowID for screencapture -l).
• Machine windows — open ac session, close ac session, list ac sessions.
• App state and settings — get app state (JSON), plus get ac app setting / set ac app setting for keys automation.enabled, automation.port, automation.bindAddress, remoteAccess.enabled, remoteAccess.port, remoteAccess.bindAddress, managed.serverURL, and managed.acIngestURL. Setting automation.enabled toggles the HTTP server live.

For example, to open a machine's window:

osascript -e 'tell application "Bromure Agentic Coding" to open ac session "Web app"'

Note: Profile JSON travels with secrets scrubbed unless BROMURE_DEBUG_CLAUDE is set. Setting apiKey to an empty string via set profile setting clears the key rather than keeping it — unlike the blank-keep behavior of the JSON round-trip bridges. Locale switching is deliberately not scriptable; relaunch the app with, for example, -AppleLanguages "(fr)" instead.

Scheduled automations

A scheduled automation is a recurring, unattended agent run bound to one machine. Automations are created and managed from the automation board (⇧⌘A, or the sidebar's Automations section), and agents can manage their own machine's automations through the automations MCP server above. The whole feature — triggers, schedules, chaining, the mandatory injection screen, run history — is documented in Automations. This section covers the control-plane surface: driving automations over the API, answering the decision prompts an unattended start can raise, and how consent works over an attached terminal.

Controlling automations over the API

Answering pending prompts

Some lifecycle decisions — the base-image upgrade offer, a disk that fails its boot-time check, a compromise alert, a compromise wipe — normally appear as a local alert. When there is nobody at the Mac to answer (a headless agent, or a launch requested by a remote rich client), they are queued instead: they surface in GET /state under pendingPrompts (each with an id, profileID, title, message, and button labels) and are answered with POST /prompts/<id>/answer:

SOCK="$HOME/Library/Application Support/BromureAC/control.sock"
curl --unix-socket "$SOCK" -X POST http://localhost/prompts/PROMPT_ID/answer \
  -d '{"choice":"Remind me later"}'

Pass one of the prompt's own button labels as choice. If no client answers before the prompt's timeout, it resolves to its safe fallback — never the destructive option (a compromise alert, for instance, falls back to shutting the VM down). If no client is connected at all, it falls back immediately. A rich client renders these prompts as ordinary alerts.

Note: Automations, delegations and other unattended starts never wait on a prompt. A start that would need an answer from you — a machine marked compromised, or a local model still downloading — is refused with a clear reason in the run's history instead ("The workspace is marked compromised — start it yourself to confirm the wipe."). A suspended machine whose saved state can't be restored boots fresh.

Consent over attached terminals

While a terminal is interactively attached to a machine — through vm exec -it, vm attach, or an SSH attach — host-side approval prompts (credential use, and similar) are rendered on your terminal, not inside the guest. The prompt reads 🔒 Bromure — approval required with numbered choices and Choice [1-N] (Enter or timeout = deny). Enter, timeout, EOF, or detaching all mean deny, so a compromised guest can never forge an approval. The guest tmux is repainted afterward.

Debug endpoints (BROMURE_DEBUG_CLAUDE)

Launching the app with BROMURE_DEBUG_CLAUDE set lifts the debug gate on the TCP automation API, so the routes in the middle row of the authentication table work over TCP too, including these debug routes (always available on the control socket, except where noted):

• GET /debug/ui-shot?path=…&which=… — the app renders its own window to a PNG (no Screen Recording permission needed) and returns a subview-frame dump; the default output is /tmp/bromure-ui-shot.png.
• POST /debug/editor — drives the settings editor for the screenshot tool.
• POST /detect/prompt-injection — runs the real detectors and returns their verdict (this route requires the debug flag even on the control socket).

The flag also lets secrets travel verbatim through the AppleScript and MCP profile-JSON bridges and is required by bromure-ac mcp --debug's VM tools. GET /health reports debugEnabled so you can tell which mode the app is in.

Warning: BROMURE_DEBUG_CLAUDE removes the safety gate that normally keeps exec, VM control, and raw profile secrets off the loopback TCP API. Run the app with it only on a machine you control, and never combine it with a non-loopback bind address — doing so would expose full VM shell access, unredacted secrets, and window captures to anyone who can reach the port. It is distinct from BROMURE_AC_DEBUG (stderr event logging) and BROMURE_CLI_DEBUG (CLI socket diagnostics), which are harmless logging switches.