Bromure Agentic Coding — User Manual

Welcome to the official user manual for Bromure Agentic Coding, the macOS app that runs AI coding agents — Claude Code, Codex, Grok, Kimi Code, Oh My Pi, and ordinary shell tooling — inside isolated Linux virtual machines on your Mac, with a host-side gateway that keeps your real credentials out of the agent's reach.

This manual documents version 5.0.0. It requires macOS 14 (Sonoma) or later on Apple Silicon.

Version 5.0.0 is organized around sessions: each conversation with an agent is a row in the sidebar, and you talk to it in a chat. The Linux VMs that sessions run in are called machines in the main window. The settings editor still calls them workspaces; the two words mean the same thing.

New to the app? Start with Installation & First Run, then follow the Quick Start. Read Concepts & Architecture when you want the full picture. Use everything else as reference.

Getting started

Chapter	What it covers
1. Introduction	What the app is, the single-boundary security model, the main features, and how it compares to other tools.
2. Installation & First Run	System requirements, installing the app, the six-step onboarding wizard, base-image updates, the command-line tool, storage, moving to a new Mac, and uninstalling.
3. Quick Start	From the wizard to a finished task: start a session, answer the agent's question, look at the changed files, inspect the trace, then archive the session and bring it back.
4. Concepts & Architecture	Sessions, machines, rooms, and branches; session states; host and guest; the wire boundary; what persists; vsock and MCP ports; networking.

Everyday use

Chapter	What it covers
5. The Sessions Home	The main window: the sidebar and its collapsed rail, session rows and their menus, the session header, the machine menu, the Linux pill, the ⌘K command palette, and archiving, ending, deleting, and undo.
6. Starting a Session	The new-session screen: choosing the agent, the machine, and where it works (a fresh folder, one of yours, or a repository), attaching files, recent starts, and asking another session with @.
6.1 The Chat	Talking to an agent: the composer, attachments, slash commands and the inline terminal, question cards, activity lines, changed-files summaries, sign-in cards, stopping, editing and resending, and search.
6.2 Rooms	Grouping related sessions into a room: the grid of live chats, layouts and tabs, zooming into one cell, the room's own Switchboard, and sending to the whole room.
6.3 Branches & Review	Branch sessions on their own git worktree, merging them back, the Branches window, and the review window with line comments.
6.4 Agents Working Together	Delegation to child sessions, requests to other sessions by @nickname, the Delegations panel, file hand-off, limits, and cross-machine requests.
6.5 Switchboard & Messaging	The Switchboard session that keeps track of every other session, its safety rules, and the Messaging Connector for Signal, WhatsApp, and Slack.
6.6 Machines	The Virtual Machines section: creating, starting, suspending, and deleting machines, Rewind home and Reset disk, terminals and the Grid, the Files pane, and the clipboard.
6.7 The Embedded Browser	The Chromium browser beside a session: driving it yourself, letting the agent drive it through the browser tools, staying signed in, and privacy.
Metal Acceleration in Bromure Web	The standalone web app: Metal requirements, app-wide and per-profile controls, active renderer, and video support.
6.8 Automations	Scheduled, unattended agent runs on a kanban board: triggers, schedules, chains, run history, answering their prompts, and the Automations MCP server.
6.9 Coding Tasks	The coding kanban: tasks, agent-planned phases, autonomous runs in worktrees, review with line comments, and merging.

Settings reference

Chapter	What it covers
7. Settings Reference	How to open the settings editor and Preferences, the grouped pane list and Search settings, the Defaults template, and what saves when.

The settings reference has one page per pane, in the editor's order:

Workspace: General, Appearance
Models: Models, Fusion, Squelch
Machine: Folders, Environment, MCP, Browser, Resources
Security: Credentials, Tracing, Guardrails, Supply Chain, Prompt Injection, PII Protection
App (Preferences only): Automation

Security & the wire boundary

Chapter	What it covers
8. Credentials & the Wire Boundary	How real secrets stay on the host while the agent gets only fakes: the MITM proxy, sign-ins and API keys, per-credential approvals, and the compromise alert.
9. Supply-Chain Protection	Checking, rewriting, and blocking package installs before the agent sees them: the age gate, OSV, socket.dev, Depi, and install-script stripping.
10. Prompt-Injection Detection & Guardrails	On-device detectors that scan the agent's AI traffic for injected instructions, the egress firewall, and guardrails on destructive operations.
10.5 PII Protection	Swapping personal data for consistent stand-ins before a conversation leaves your Mac, and restoring it in the replies.
11. Tracing & Audit	What a session trace records, the Trace Inspector, encryption at rest, retention, exporting, and privacy.
11.5 Security Overview & Timeline	The Security Timeline window: the 24-hour Overview, per-machine protections, and the filterable, exportable Timeline of every security decision.

Models & infrastructure

Chapter	What it covers
12. Fusion — the Multi-Model Panel	Answering each prompt with several models at once, judged and combined into a single reply on the wire.
12.5 Squelch — Less Noise, Fewer Tokens	Trimming passing tests, progress and other noise out of command output before the model reads it (after rtk), and the tokens it saved per session.
13. Models & Providers	The global Models board: providers (sign-ins, API keys, Amazon Bedrock, OpenRouter, custom servers, on-device models), per-agent model choices, per-workspace overrides, and live changes.
13.5 Kubernetes Clusters & Registries	Running k3s clusters and a private container registry in their own VMs beside your machines: storage, load balancing, add-ons, access, and the infrastructure MCP server.

Beyond one Mac

Chapter	What it covers
14. Remote Access & Clients	Mirroring a remote Bromure from another Mac, iPhone, iPad, or Apple Vision Pro; remote Preferences; the CLI over SSH, tunnels, and PAC; and the remote security model.
15. Enterprise — Enrollment & Fleet	Enrolling with bromure.io, what telemetry uploads (and what does not), the fleet view, and off-boarding.

Reference

Chapter	What it covers
16. CLI, API & MCP	The `bromure-cli` command-line tool, the loopback control API, the MCP servers, and AppleScript.
16.5 Advanced	Power-user tools: the ext4 file browser and file-system check, and restoring or rewinding a machine's home.
17. Troubleshooting	Diagnosing setup, machine, sign-in, TLS, supply-chain, disk-space, and remote-access problems, organized by symptom.
18. Glossary	Definitions of every term used in this manual.
19. Appendix	Reference tables: on-disk locations, network and vsock ports, environment variables, defaults, keyboard shortcuts, and the guest cheat sheet.

Conventions used in this manual

Bold text names an on-screen control or label exactly as the app shows it in English — a button, menu item, toggle, pane, or sidebar section (for example, New session or Start this VM at login).
Monospace text is a command, file path, environment variable, or literal value you type or see (for example, bromure-cli vm ls or ~/Library/Application Support/BromureAC).
A path such as Workspaces › Infrastructure › Messaging Connector… is a menu path: the menu, then each submenu or item in order. Preferences › Models means the Models pane of the Preferences window.
Machine and workspace mean the same thing: one isolated Linux VM with its settings. The main window says machine; the settings editor, menus such as New Workspace…, and the CLI say workspace (or profile).
A session is one conversation with an agent, in one folder, on one machine. It is not a run of a machine; see Concepts & Architecture.
Keyboard shortcuts use the macOS symbols: ⌘ Command, ⌥ Option, ⌃ Control, ⇧ Shift, ⏎ Return, ⎋ Escape.
Screenshots show the English interface with synthetic demo content. The app is localized, so your screens follow your macOS language.
Notes, tips, and warnings appear as callouts:

Note: Background information worth knowing.

Tip: A shortcut or recommended practice.

Warning: Something that can lose data or weaken a protection if you get it wrong.

Where else to look

Product downloads, the technical whitepaper, and the detailed feature matrix are at bromure.io. For questions this manual does not answer, Troubleshooting collects diagnostic procedures, and the Glossary defines the vocabulary.