Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

docs(settings): the settings page, the theme in config.json, both edited from the Mac app too, and a run that cannot loosen its own rules

Shahriard44e5bf60b4a
diff --git a/docs/guide/approvals.md b/docs/guide/approvals.md
index 29834a3..58702fe 100644
--- a/docs/guide/approvals.md
+++ b/docs/guide/approvals.md
@@ -171,13 +171,19 @@ gate stops being information.
---
-## The Settings tab
+## The settings page
-Everything below is editable from **Settings** in the side panel, without opening a file.
+Everything below is editable without opening a file, from two places that edit the same rows:
+
+- **The extension's settings page** — the sliders button in the side panel's header or the popup,
+ or right-click the toolbar icon → **Options** — under **Guardrails**.
+- **The Mac app's Settings tab**, in its **Guardrails** card.
+
+A change made in one shows up in the other at once, and so does a hand edit of the file.
The screen is a list of **overrides**, not a list of switches that turn protection on. Every row
starts off, meaning "use the default Browsentic ships" — so a fresh install has an empty settings
-tab and the posture you get is the posture described here, whether or not you ever open it.
+page and the posture you get is the posture described here, whether or not you ever open it.
Turning a row on reveals **Allow / Ask / Block** and writes that one line to
`~/.browsentic/config.json`. Turning it back off removes the line rather than writing a value equal
@@ -194,6 +200,9 @@ accident. Hand-editing config.json still works if you genuinely mean it.
Credential sealing appears in the list with no switch at all, because there is nothing to turn off:
it is what keeps a plaintext password off the socket in the first place.
+An agent run cannot use either screen's route to loosen its own rules: the daemon refuses a
+settings change from a connection that has acted for a run, with `BLOCKED`.
+
---
## Secrets are sealed before you are asked
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index 937ba17..bb6a9b6 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -3,7 +3,8 @@
Everything is optional. Browsentic works with no config file at all.
Settings live in `~/.browsentic/config.json`. The daemon re-reads it before every run, so an edit
-applies to the next thing you ask — no restart.
+applies to the next thing you ask — no restart. It also watches the file, so the extension's settings
+page and the Mac app show a hand edit the moment you save it.
`BROWSENTIC_HOME` relocates the whole state directory if you need it somewhere other than
`~/.browsentic`. See [internals/state.md](../internals/state.md) for the full disk layout.
@@ -22,6 +23,7 @@ Nothing here is required; this shows every key in one place.
},
"requireApproval": ["page.submitForm"],
"maxConcurrentRuns": 3,
+ "theme": "midnight",
"guardrails": {
"rules": { "raw-html-read": "allow" },
"unattended": "deny",
@@ -70,9 +72,9 @@ Eight tab sessions may be *open* at once regardless; that ceiling is compiled in
## Approvals and guardrails
-Most of this section has a UI: the side panel's **Settings** tab writes these same keys, one row at
-a time. Rows start off — meaning "use the default" — so an install that never opens the tab has no
-`guardrails` key at all. Turning a row back off deletes its line rather than writing the default,
+Most of this section has a UI: the extension's settings page and the Mac app's Settings tab both write
+these same keys, one row at a time. Rows start off — meaning "use the default" — so an install that
+never opens either has no `guardrails` key at all. Turning a row back off deletes its line rather than writing the default,
which is why a hand-edited file and a panel-edited file look the same.
| Key | Default | Notes |
@@ -114,12 +116,19 @@ ceiling is clamped; a value that is not a number ≥ 1 falls back to the default
## Appearance
-The panel's theme is not in this file. It is a row of tiles in the side panel's **Settings** tab —
-**Ember** (warm near-black, cyan), **Midnight** (cool blue-black, violet), **Phosphor** (a green
-CRT) and **Daylight** (ink on paper) — and one click repaints the panel and the popup together.
-Each tile is drawn in the theme it offers, so the preview is the thing itself.
+| Key | Default | Notes |
+| --- | --- | --- |
+| `theme` | absent (Ember) | `ember`, `midnight`, `phosphor` or `daylight` — the look of the side panel, the popup and the settings page |
+
+It is a row of tiles under **Appearance** on the extension's settings page, and under **Browser theme**
+in the Mac app's Settings tab — **Ember** (warm near-black, cyan), **Midnight** (cool blue-black,
+violet), **Phosphor** (a green CRT) and **Daylight** (ink on paper). Each tile is drawn in the theme it
+offers, so the preview is the thing itself.
-The choice is stored in the browser, never sent to the daemon, and needs nothing paired to work.
+One theme serves every paired browser: picking one anywhere repaints the panel, the popup and the
+settings page in all of them. A browser that has never been paired keeps its choice to itself and
+hands it to the daemon when it first connects; one picked while the daemon is unreachable is handed
+over at the next connect. The Mac app's own window keeps its separate System / Light / Dark setting.
---
diff --git a/docs/guide/mac-app.md b/docs/guide/mac-app.md
index fef5367..4ebfa68 100644
--- a/docs/guide/mac-app.md
+++ b/docs/guide/mac-app.md
@@ -69,7 +69,7 @@ The tabs float at the top; ⌘1–⌘7 switch between them.
| **Skills** | Every [skill](features/skills.md) the router can see and which folder it came from |
| **Activity** | Your standing [approvals](approvals.md), forgettable per site, and the downloads agents captured |
| **Logs** | `~/.browsentic/daemon.log`, followed live |
-| **Settings** | Light, dark or system appearance; whether the daemon starts with the app; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall |
+| **Settings** | Light, dark or system appearance for this window; whether the daemon starts with the app; the **Browser theme** and **Guardrails** every paired browser uses, the same rows as the extension's settings page, kept in step both ways; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall |
There is also a menu bar item with the daemon’s state and the same on, off and restart.
diff --git a/docs/internals/extension.md b/docs/internals/extension.md
index 753c56e..6cecefd 100644
--- a/docs/internals/extension.md
+++ b/docs/internals/extension.md
@@ -81,10 +81,10 @@ it is the documented escape hatch.
## The panel's tabs
-`PanelNav` owns the tab strip: **Chat**, **History**, **Skills**, **Recordings**, **Schedules**,
-**Settings**.
-Adding one is a variant in `PanelTab`, an entry in `TABS`, and a branch in the side panel's body —
-there is no router.
+`PanelNav` owns the tab strip: **Chat**, **History**, **Skills**, **Recordings**, **Schedules**.
+Adding one is an entry in `PANEL_TABS` (which `PanelTab` is derived from), an entry in `TABS` and
+`RAIL_TABS`, and a branch in the side panel's body — there is no router. A stored tab that is no
+longer in `PANEL_TABS` — `settings`, from before it moved out — opens on Chat.
**The strip labels as much as it can afford.** A `ResizeObserver` measures the width the labelled
row actually needs and steps through three fits: every label, then only the open tab's, then icons
@@ -94,12 +94,34 @@ learned, which is what keeps the strip from flapping between two fits at one pan
practice five labels want ~485 px and one wants ~225 px, so a side panel at its usual size lands on
the middle fit.
-**Settings** is two halves with nothing in common. **Guardrails** lives on the daemon rather than in
-extension storage, like the Schedules tab's tasks: it reads and writes `~/.browsentic/config.json`
-through two bridge ops, `guardrails` and `setGuardrail`, which forward to the socket frames of the
-same name. The extension holds no copy — every write returns the daemon's fresh view, which is what
-the panel then renders, and the whole half is empty until the daemon is up. **Appearance** never
-leaves the browser, which is why it sits above and renders whether or not anything is paired.
+## The settings page
+
+Settings are not a panel tab. They are the extension's options page, `entrypoints/options/`, which
+WXT turns into `options_ui` with `open_in_tab` on both browsers — so it needs no permission, Chrome
+lists it as **Options** on the toolbar icon's menu, and Firefox as **Preferences** in about:addons.
+The panel's header, the popup's header and the connection sheet open it with
+`runtime.openOptionsPage()`, which focuses a settings tab already open rather than adding another.
+
+The page is a sidebar of four sections — **Appearance**, **Guardrails**, **Agent**, **Connection** —
+with the open one in the URL hash, so a reload or a link lands on it. **Agent** and **Connection** are
+the same `AgentPicker` and `DaemonLink` the popup and the connection sheet show; those keep theirs,
+so a blocked run is still one click from its fix.
+
+**Appearance and Guardrails are shared with the Mac app**, and the daemon keeps both in
+`~/.browsentic/config.json`:
+
+- Two bridge ops, `preferences` and `setPreference`, forward to the socket frames of the same name.
+ The answer, `preferencesInfo`, is also pushed on connect and after every change to the file,
+ whoever made it, and lands in `DaemonState.preferences`. The guardrail section renders that, so a
+ row flipped in the Mac app moves here without a reload.
+- **The theme stays in `storage.local` too**, because every surface paints from it before any socket
+ exists. `servePreferences()` in [preferences.ts](../../src/lib/bridge/preferences.ts) keeps the two in
+ step:
+ - A push writes the daemon's theme locally.
+ - A local pick is sent up, unless it only echoes the push.
+ - A pick made while the daemon could not be told sets `browsentic/theme.unsynced`, and wins at the
+ next connect. So does a pick made before the browser was ever paired, when config.json names no
+ theme yet.
### Themes
diff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.md
index 75597d0..bd7bcb7 100644
--- a/docs/internals/guardrails.md
+++ b/docs/internals/guardrails.md
@@ -106,7 +106,9 @@ the consequential actions. `unattended: 'allow'` goes back to waiving them.
### The settings screen
`guardrailSettings()` in [settings.ts](../../src/daemon/guardrails/settings.ts) describes the policy to
-the side panel's Settings tab. Everything it returns is derived from `DEFAULT_RULES` and the live
+the two screens that edit it: the extension's settings page and the Mac app's Settings tab. Both reach
+it through [preferences.ts](../../src/daemon/preferences.ts), over the extension socket and `/control`
+respectively, and a change from either — or a hand edit — is pushed to the other. Everything it returns is derived from `DEFAULT_RULES` and the live
config, so a rule added to the policy appears in the screen with no second edit, and a rule whose
title or reason changes says the new thing in both places.
@@ -122,6 +124,10 @@ the key, so config.json only names real decisions and a changed default still re
`settingWritable()` is the gate: unknown ids, locked rules and wrong-shaped values are refused at
the daemon, not just hidden in the UI.
+**A run cannot loosen its own rules.** `/control` is also how an agent run's tool server reaches the
+daemon, so a control connection that has carried a `runId` is refused `setPreference` with `BLOCKED`.
+The Mac app and a plain MCP client never send one.
+
### Overriding
```json
diff --git a/docs/internals/state.md b/docs/internals/state.md
index b765f7b..5b35236 100644
--- a/docs/internals/state.md
+++ b/docs/internals/state.md
@@ -32,7 +32,7 @@ Nothing lives in the repository.
| --- | --- | --- |
| `daemon.json` | Each daemon at startup | The control token dies with the daemon that minted it. Read it with `browsentic token` |
| `auth.json` | Pairing | Session keys are per browser profile, keyed by its install id, and survive restarts. Cleared by `browsentic revoke` |
-| `config.json` | You, and the agent picker | Re-read before every run — no restart needed. [Reference](../guide/configuration.md) |
+| `config.json` | You, the agent picker, and the settings page and Mac app for `theme` and `guardrails` | Re-read before every run — no restart needed — and watched, so a hand edit reaches every open settings screen. [Reference](../guide/configuration.md) |
| `approvals.json` | **Always on ‹host›** | One action + host per entry. Only short-circuits a `confirm` |
| `models.json` | The daemon, reading each agent CLI's model list | A cache: deleting it only means the lists are read again. A failed read keeps the last list that read cleanly |
| `schedules.json` | The Schedules tab, `browsentic tasks` | At most 25 tasks. The daemon re-reads it every minute, so an edit from the CLI lands without a restart. Transcripts stay in the extension: the last three runs of each task |
@@ -69,7 +69,11 @@ state under `browsentic/dictation`, and the approvals it has already announced u
`browsentic/approvalsAnnounced`) — a restarted browser never comes back with a microphone on.
Only where the orb was dragged to (`browsentic/orbPosition`), whether hold-to-talk is on
(`browsentic/pushToTalk`) and whether this browser's speech service has ever worked
-(`browsentic/speechService`) are kept in `storage.local`. So do **diagnostics buffers** (`browsentic/diagnostics`), monitors and
+(`browsentic/speechService`) are kept in `storage.local`.
+
+**The theme** is config.json's `theme`, mirrored into `storage.local` under `browsentic/theme` so a
+page paints before any socket is up. `browsentic/theme.unsynced` marks a pick the daemon has not heard
+yet, handed over at the next connect. So do **diagnostics buffers** (`browsentic/diagnostics`), monitors and
timers — none of what a page reported about itself outlives the browser that reported it.
## Relocating
diff --git a/docs/internals/transport.md b/docs/internals/transport.md
index eebb542..c904085 100644
--- a/docs/internals/transport.md
+++ b/docs/internals/transport.md
@@ -111,7 +111,7 @@ dialling — but it never deletes the stored key. Only pairing again or `disconn
## Protocol version
-Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **14**). A mismatch closes the socket
+Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **21**). A mismatch closes the socket
with an explicit reason instead of letting two incompatible frame vocabularies talk past each other.
---