The official plugins ship with seleniumbase-rs, one cargo feature each, and you turn them on by name, with no code: on the command line, in the settings file, in an environment variable, or in a builder call. This page is that surface. For writing a plugin of your own, see Writing your own.
The prebuilt sbrs and sbrs-mcp, and cargo install of
seleniumbase-rs-cli, have the official plugins compiled in, so there is
nothing to install: sbrs --plugin shield open https://example.com (see
On the command line). The rest of the page is for Rust
programs that load Settings and build their own browser. A build without the
plugins feature stops at Settings::load when the table or SB_PLUGINS names
a plugin; a build with it reads them and leaves the selection to the program.
The short version#
| You want | Do |
|---|---|
shield for one sbrs command | sbrs --plugin shield open https://example.com |
| An option of a plugin on the command line | --plugin-opt 'shield.level="strict"' |
| The plugins and what they may do | sbrs plugin list, sbrs plugin info shield |
| shield in a Rust program | features = ["plugin-shield"], then .plugins_named(["shield"]) |
| Every official plugin | features = ["plugins-builtin"] |
| A plugin chosen by a file, not code | [plugins] enable = ["shield"] in sbase_config.toml |
| A plugin for one run | SB_PLUGINS=shield |
| A plugin from another crate | Add the crate, then PluginSet::with (see Writing your own) |
Cargo features#
| Feature | Turns on |
|---|---|
plugins | The plugin API (seleniumbase_rs::plugin_api) and the hooks of both engines. No plugin of its own |
plugin-shield | plugins, and the shield plugin |
plugin-block-resources | plugins, and the block-resources plugin |
plugin-crx | plugins, and the crx plugin |
plugins-builtin | All three above |
A build compiles only the plugin crates it asks for: plugin-shield does not
also compile the CRX unpacker. The plugins live in the
plugins repository, and
this crate depends on two crates from it, the API and the aggregator of the
built-in plugins.
Both dependencies name one git URL and one commit (rev in
Cargo.toml). Cargo counts a git repository under two references (a branch, a
tag, a revision) as two sources, so a plugin crate added with a different
reference builds a second copy of seleniumbase-rs-plugin, and its Plugin is
not the trait this crate calls. The compiler then says the trait Plugin is not
implemented and mentions two versions of seleniumbase_rs_plugin. Add a plugin
crate with the same revision:
A test in this repository (tests/plugin_features.rs) fails when the two
dependencies drift apart.
In the settings file#
The [plugins] table of sbase_config.toml (or the plugins object of a JSON
.sbase_config) lists the plugins to add, in order, and a table named like a
plugin holds that plugin’s options:
Options are the plugin’s own; an option it does not know is an error. Load the
file with Settings::load, and settings.plugins holds the selection:
For the WebDriver engine, BrowserConfig::with_plugin_selection:
With SB_PLUGINS#
SB_PLUGINS is a comma-separated list of names:
It replaces the enable list of the file. The options of a plugin the list still
names stay; the options of the others are dropped, so SB_PLUGINS= (set, but
empty) turns every plugin off and leaves nothing for the build to refuse. Spaces
around a name and empty entries are ignored. Like the other SB_* variables, it
is read by Settings::load, and it takes effect before the check for plugin
support, so in a build without the plugins feature SB_PLUGINS= still
overrides a [plugins] table of the file.
On the command line#
sbrs and sbrs-mcp apply the [plugins] table and SB_PLUGINS to every
browser they start, and take two options of their own. Both go before the
command, as the other global options of sbrs do, and both repeat:
Turns the plugin on, after the ones the file and SB_PLUGINS turn on. A name that is on already stays where it is.
Sets one option of a plugin. VALUE is a TOML value, so a string is written with quotes.
Put the whole option in single quotes, so the shell keeps the double quotes TOML
needs. shield.level=strict is not a TOML value; sbrs says so and shows the
quoted spelling. NAME ends at the first ., and KEY is the option’s name.
Precedence#
Highest first:
- The command line.
--pluginadds a name;--plugin-optsets one key. SB_PLUGINS, which replaces the names the file enables, and drops the options of the plugins it no longer names (after the flags are applied, so a--pluginthat turns such a plugin back on keeps the options the file gave it).- The
[plugins]table of the settings file (--config FILE, otherwisesbase_config.tomlin the current folder).
A --plugin-opt replaces the same key from the variable or the file and keeps
the plugin’s other options. With level = "basic" and extra_block_hosts = [...]
under [plugins.shield] in the file, --plugin-opt 'shield.level="strict"'
runs shield at the strict level with the file’s hosts. The plugin has to be on:
an option for a plugin that nothing turns on is an error, not an option that is
quietly dropped. The same text is in sbrs --help.
Which commands#
| Command | What happens |
|---|---|
Every command that starts a browser with BaseCase (open, smoke, screenshot, record, replay, run-scenario, print-pdf, …) | The WebDriver engine runs the plugins (BrowserConfig::with_plugin_selection) |
sbrs devtools | The pure CDP engine runs them (LaunchOptionsBuilder::plugin_selection) |
sbrs test | Passes the names on to the tests as SB_PLUGINS, with the names the file and the variable already turn on, for a test that calls with_plugin_selection(&settings.plugins). It refuses --plugin-opt, because the variable carries names only: put the options under [plugins.NAME] in the file |
sbrs-mcp | Every browser the server starts gets them; see below |
sbrs plugin list, sbrs plugin info | Show them; see below |
Commands that start no browser (version, doctor, install, mkfile, …) | Ignore the options, even a wrong one: sbrs --plugin 'a b' version prints the version |
sbrs devtools, sbrs plugin list, sbrs plugin info and sbrs-mcp read the
[plugins] table of the settings file and nothing else of it, so a variable
that is wrong for a browser (SB_HEADLESS=maybe) or a value of the file that is
(headless = "maybe") does not stop them.
What a project file may not turn on alone#
The sbase_config.toml of the current folder may be a cloned project’s, so it
cannot grant a plugin the powers that reach beyond the browser.
A plugin that declares launch.proxy, artifacts.write or a host.*
capability (see sbrs plugin info NAME) and is named only by that file is
refused, with exit status 2 and the way to name it yourself (tunnel is an
example, not a built-in plugin):
--plugin NAME, SB_PLUGINS and a file named with --config count as the
person choosing. The other powers a plugin can declare (launch.args,
launch.network, launch.extensions, page.script, cdp:*) are not held back:
the settings file can already set an extension folder itself. Of the three built-in
plugins, crx declares one: host.fs.write:temp, to unpack an extension into
the temporary folder. So a settings file in the current folder cannot turn
crx on by itself; name it with --plugin crx or SB_PLUGINS=crx. A settings file of
the person (in their home folder), which would be trusted like --config, is
not built yet.
Every active plugin is logged at INFO with the place that turned it on, so a
file in the folder cannot switch one on unseen:
sbrs plugin list and sbrs plugin info#
ENABLED says whether the file, the variable and the options together turn the
plugin on. A name that is enabled but not in the build is listed below the table.
info shows what the plugin declares: its category and phase, each capability
with its risk and whether the host enforces it (declared only means a native
Rust plugin promises and the host cannot stop it), what it needs from the
browser, its place among the other plugins, and the options in effect. When the
plugin refuses those options, or cannot start without any (crx needs its
files), the page says so with the plugin’s own message. The plugin API of this
release does not describe the options a plugin accepts, so the page cannot list
them: each plugin’s page does (shield,
block-resources, crx).
An unknown name exits with status 2 and lists the ones the build has:
sbrs-mcp#
sbrs-mcp takes the same two options, and reads the same table (in the folder
it runs in, and only that table) and variable, and logs the active plugins as
sbrs does. The operator chooses the plugins, not the model:
start_browser has no plugin argument, and an extra argument adds nothing. All
three servers (cdp, driver, sb) give every browser they start the plugins,
in the pure CDP and the WebDriver engine:
A mistake in the plugins stops the server before it listens, with the same
message and exit status as sbrs, not at the model’s first start_browser.
Mistakes and exit status#
Nothing is skipped. These are reported before any browser starts, with exit
status 2 (the status sbrs gives every value that does not parse):
| Mistake | What you get |
|---|---|
--plugin sheild, SB_PLUGINS=sheild, or sheild under enable | An error that says no plugin has that name and lists the ones the build has |
--plugin-opt for a plugin nothing turns on | The option, the plugin, and the three ways to turn it on |
An option the plugin does not know (shield.lvel) | The plugin’s own message, with its name |
A value that is not TOML (shield.level=strict) | The text, and the quoted spelling to use |
--plugin-opt that is not NAME.KEY=VALUE, an empty --plugin, a comma in a name | What the option has to look like |
The same option twice (--plugin-opt a.b=1 --plugin-opt a.b=2) | Which one |
Builds#
plugins-builtin is a default feature of seleniumbase-rs-cli, as pdf and
mcp-server are, and the release workflow builds with it. The package also
passes plugins, plugin-shield, plugin-block-resources and plugin-crx
through to the library. A build with --no-default-features has no plugin
support and fails closed: --plugin, a [plugins] table, or SB_PLUGINS
naming a plugin stops a browser command with status 2 and the text
rebuild with --features plugins-builtin; sbrs plugin list says there are
none; sbrs plugin info fails. An empty SB_PLUGINS= still turns the file’s
plugins off. The Docker image is built without the default features and has no
plugins.
In code#
On the pure CDP engine, LaunchOptionsBuilder takes names beside the plugins you
build yourself:
plugins_named and plugin_selection only record the names. build() resolves
them and reports a mistake as SeleniumBaseError::Plugin. Named plugins are
added after the set given to plugins(...), and run in the order their phases
give (privacy plugins run after the others). On the WebDriver engine,
BrowserConfig::with_plugins_named and with_plugin_selection do the same and
return the error at once, because a configuration has no build().
A program with plugins of its own builds a registry:
A set built from names is strict: it refuses a plugin that declares no metadata, and grants each plugin what it declares except Critical capabilities.
Mistakes it catches#
Nothing is skipped silently. Every case below stops the build, before a browser starts:
| Mistake | What you get |
|---|---|
A name no plugin has (sheild) | An error that says no plugin has that name, lists the names that are known, and names the cargo features that add the official ones |
Options for a plugin that is not in enable ([plugins.sheild], or enabled = [...]) | An error naming the table and saying it is not in enable |
| An option the plugin does not know | The plugin’s own message, with the plugin’s name |
| The same name twice | An error that says the plugin is already in the set |
Names in a build without the plugins feature | Settings::load fails and says to rebuild with --features plugins-builtin |
The last row is deliberate: a program that asked for privacy hardening and silently runs without it is worse than one that stops. The command-line programs report the same mistakes with exit status 2 (see Mistakes and exit status).
Not here yet#
sbrs plugin add|remove|enable|disable|verify|sync|audit, and the global options--no-pluginsand--plugins-dir.- Plugins that are not compiled in: WebAssembly modules and TOML manifests, and the store and lockfile that pin them.
- A
pluginsargument for the MCPstart_browsertool (a subset of what the operator allowed), alist_pluginstool andrun_plugin_task. - A list of the options a plugin accepts in
sbrs plugin info; the plugin API does not describe options yet. - The other official plugins of the design (tor, fetcher, extractor, browser, batcher, crawler).