Home / Docs / Use

Using the browser

Ferrite is a normal browser with an agent panel beside it. This page covers the window and the shortcuts. It covers the panels you can resize. It says what happens when a page asks for a dropdown, a dialog or a file. It also says what the crash banner means. Some words here are new. Words we use explains them.

Which build has this

Everything here is in the source. The build on the releases page was published on 2026-10-02 from commit f4ed744. That is before the page-control overlays, resizable panels, DevTools and crash banner were written. The release page names its commit. To get these features now, build from source (Run it from source). The screenshots on this page were rendered on Linux.

The window#

Tab strip#

The tabs share the strip equally, down to a minimum width. If there are more tabs, the strip scrolls. A long title is cut off with an ellipsis (...). The active tab keeps a minimum width, so its close button stays reachable.
The close button shows on the active tab or on a tab under the pointer. A middle-click closes a tab. Cmd/Ctrl+T or the + opens a new tab.
A small dot on a tab means the page needs you. The dot has the accent colour while the page waits on a dropdown or dialog. It is red after the page stopped responding. This matters because you cannot see the alert of a background tab. That page is blocked until you look.
The empty part of the strip drags the window. A double-click maximizes it. On macOS, the title bar is transparent and the strip holds the window buttons. On Linux and Windows, the window keeps its normal frame.

From left to right, the toolbar has these parts:

back, forward and reload (reload becomes stop while a page loads)
the address bar
the Agent button (a dot appears when something needs your decision)
the audit shield
the menu

A thin band that sweeps along the bottom edge of the toolbar shows that a page is loading. The address bar follows these rules:

An address with a scheme (https://…) or an about: page is opened as typed.
A bare host or path that has a dot and no spaces gets https://. localhost and IP addresses get http://.
Anything else is a Google search. The agent's own search is separate. Its prompt still sends it to DuckDuckGo Lite and tells it not to use google.com. This is because Google's pages stayed blank in this engine when that was written. Nobody has confirmed whether Google's results page now draws well (see Limits).
A click on the bar selects everything. A zoom chip appears in the bar when the page is not at 100%. A bookmark button saves the page.

The overflow menu: New tab, a zoom control, Find in page, Bookmark this page, Bookmarks, History, Downloads, Developer tools, Switch to dark theme and Settings. — The overflow menu. This screenshot was rendered on Linux, so the shortcuts read Ctrl. On macOS they read Cmd.

The overflow menu in the dark theme: New tab, a zoom control, Find in page, Bookmark this page, Bookmarks, History, Downloads, Developer tools, Switch to light theme and Settings. — The overflow menu. This screenshot was rendered on Linux, so the shortcuts read Ctrl. On macOS they read Cmd.

Bookmarks, History and Downloads share one drawer. Browsing history is for the current session only. It is not saved. Bookmarks are saved. Downloads has a manual Download current page action. Ferrite does not catch clicks on <a download> links.

Keyboard shortcuts#

Mod is Cmd on macOS and Ctrl everywhere else. These shortcuts come from the shortcut table in the interface code. They keep working while the address bar or the agent box has focus. The editing keys still reach the field. These are Mod+A, C, V, X and Z.

Keys	Action
`Mod`+`T` / `Mod`+`W`	New tab / close the active tab
`Mod`+`R`, `F5`	Reload
`Mod`+`L`	Focus the address bar
`Mod`+`F`	Find in page (`Esc` closes the bar)
`Mod`+`D`	Bookmark this page, or remove the bookmark
`Mod`+`=`, `Mod`+`-`, `Mod`+`0`	Zoom in, out, reset
`Mod`+`[`, `Mod`+`]`, `Alt`+`←`, `Alt`+`→`	Back, forward
`Mod`+`Shift`+`[` / `]`, `Ctrl`+`Tab` / `Ctrl`+`Shift`+`Tab`	Previous or next tab (`Ctrl`+`Tab` is `Ctrl` on macOS too)
`Mod`+`1` to `8`, `Mod`+`9`	That tab by number; the last tab
`Mod`+`Shift`+`A`	Show or hide the agent panel
`Mod`+`Shift`+`O`	New agent chat
`Mod`+`,`	Settings
`Cmd`+`Opt`+`I` (macOS), `Ctrl`+`Shift`+`I` (elsewhere), `Mod`+`J`	Developer tools
`F12`	The Audit panel (model calls and the audit log, where each entry is tied to the one before it), not DevTools

Typing, pointer and wheel input go to the page. They go to the browser instead if a field of the browser has focus or a page control is open. One thing is not handled: input-method (IME) composition. Nobody has tested non-US keyboard layouts, dead keys or key repeat.

Panels you can resize#

The agent, library (bookmarks, history, downloads) and settings drawers share the right-hand side. Only one shows at a time. DevTools and the audit panel share the bottom. To resize a panel, drag the edge between the panel and the page. To reset it, double-click the edge.

Side drawers are 300 to 760 px wide (380 by default). Bottom panels are 140 to 720 px tall (260 by default).
The page always keeps at least 360 by 160 px. Ferrite fits the sizes to the real window every time. So a size saved on a big monitor never hides the page on a small one.
Ferrite saves the sizes when you release the mouse, in ui-layout.json in the data folder. If a size cannot be saved, the panel still resizes.

What a page can ask the browser for#

A page can ask for these things: dropdown lists, alert(), confirm() and prompt() dialogs, the colour picker, the file picker, the page's context menu and a sign-in for a site that uses HTTP authentication. Each one reaches the browser as a request. Ferrite draws each one itself, as an overlay on the page. The page is blocked until you answer. While an overlay is open, the page gets no pointer or key input. You can answer or dismiss every control. Esc cancels it.

The page's text is untrusted. Ferrite draws a dialog's message, an option's label or a menu row as plain text. It removes control characters and bidirectional characters (characters that change the text direction). It also caps the length. A dialog names the site it comes from. It also says that the words come from the page. So a page cannot pass its words off as Ferrite's.

A dropdown list of countries drawn by Ferrite over a form, with Germany ticked. — A `<select>` list. The form is a real engine render of a local demo page. The overlay is drawn from sample state, placed over its select box.

A dropdown list of countries drawn by Ferrite over a form in the dark theme, with Germany ticked. — A `<select>` list. The form is a real engine render of a local demo page. The overlay is drawn from sample state, placed over its select box.

A confirm dialog titled This page asks, from localhost, with the message Remove 2 items from your cart, a note that the message comes from the web page, and Cancel and OK buttons. — A `confirm()` dialog, shown as coming from the page. Rendered from sample state.

A confirm dialog in the dark theme titled This page asks, from localhost, with the message Remove 2 items from your cart, a note that the message comes from the web page, and Cancel and OK buttons. — A `confirm()` dialog, shown as coming from the page. Rendered from sample state.

The file picker card: Choose a file, from localhost, with a field for the full path and a note that the page accepts .pdf and .png, and Cancel and Open buttons. — The file card. **Choose a file…** opens your system's own file dialog. You can also type or paste the path. Rendered from sample state (an older picture, without the button).

The file picker card in the dark theme: Choose a file, from localhost, with a field for the full path and a note that the page accepts .pdf and .png, and Cancel and Open buttons. — The file card. **Choose a file…** opens your system's own file dialog. You can also type or paste the path. Rendered from sample state (an older picture, without the button).

Known gaps

The file card's Choose a file… button runs the system's own picker: osascript on macOS, PowerShell on Windows, and zenity or kdialog on Linux. A Linux without either one keeps the typed field. Nothing from the page goes into that command. The picked path fills the card. Ferrite checks it, and the page gets it only when you press Open. Nobody has opened the picker on a real Mac or Windows machine yet.

A site that answers with HTTP authentication (a 401) gets a Sign in card with a username and a hidden password field. The password goes to that site only when you press Sign in. It never appears in a log. Cancel shows the site's own error page. The agent cannot answer this card. Select, confirm(), prompt() and the colour input were checked in the engine. The overlays were driven on Linux at normal pixel density. They were not driven on a Retina screen or a Mac.

Ferrite follows the page's cursor (pointer, text, crosshair and so on). cursor: none shows the ordinary arrow.

When a page stops responding#

A page's script thread can die. Then the engine reports it, and Ferrite leaves the page frozen on screen. A banner covers part of the page, and the tab gets a red dot. The banner is not a dialog. You can keep using the rest of the browser.

The top of the Ferrite window with a banner over the page: This page stopped responding, with Reload, Details and a close button, and a red dot on the active tab. — The crash banner, rendered from sample state. The engine did not really crash here.

The top of the Ferrite window in the dark theme with a banner over the page: This page stopped responding, with Reload, Details and a close button, and a red dot on the active tab. — The crash banner, rendered from sample state. The engine did not really crash here.

Reload: Gives the tab a fresh engine session. Then it loads the same address again. On a crashed tab, Reload and typing an address also start a fresh session. They do not talk to the dead one.
Details: Shows the reason and a backtrace. A backtrace is a list of the code steps that led to the crash. A Copy button copies a short report that includes the page address.
Dismiss: Hides the banner. The crash stays in the Engine tab of DevTools and in the log file.

The agent panel#

The panel is a chat. Each run is a turn. A turn shows the steps the agent took, and its answer. The steps fold up when the run finishes. Ferrite saves chats and lists them under the clock icon. The answer appears while the model writes it, word by word, with a blinking caret and the note Writing…. This is only something to watch: the agent acts on a step only once the model has finished it and Ferrite has checked it. The answer is shown as Markdown, which is simple formatted text. Ferrite does not run any HTML in it. It does not fetch any images. A link shows the site it really goes to. It opens only when you click it. Getting started covers the cards that ask for your decision. Models and settings covers Settings.