Skip to content

Agent Zero AI framework

Add proxy support to internal Browser

Alessandroeae1b67c09fd
diff --git a/docs/guides/browser.md b/docs/guides/browser.md
index 2b7d18efe..a005c252a 100644
--- a/docs/guides/browser.md
+++ b/docs/guides/browser.md
@@ -119,6 +119,7 @@ The toolbar menu includes:
The full settings include:
- **Browser location:** Use the Docker browser or **Bring Your Own Browser** through A0 CLI.
+- **Proxy:** Optionally route the Docker browser through an HTTP or SOCKS proxy, with bypass and authentication settings.
- **Page content access:** Controls host-browser page text and screenshots.
- **Starting page:** The default URL for new Browser sessions.
- **Autofocus active page:** Lets an already-open Browser surface follow the agent's browsing.
@@ -135,6 +136,11 @@ can show in the Canvas.
In normal Docker installs, the needed browser is already included. In local
development, Agent Zero can install it the first time it is needed.
+To use a proxy, enter its server in Browser settings, for example
+`http://proxy.example:3128` or `socks5://proxy.example:1080`. Add an optional
+comma-separated bypass list, username, and password when the proxy requires
+them. Saving proxy changes restarts active Docker Browser sessions.
+
## Bring Your Own Browser
Bring Your Own Browser lets Agent Zero use Chrome, Edge, Brave, Opera, Vivaldi,
diff --git a/docs/res/usage/browser/browser-plugin-settings.png b/docs/res/usage/browser/browser-plugin-settings.png
index faecb7a4c..305b51369 100644
Binary files a/docs/res/usage/browser/browser-plugin-settings.png and b/docs/res/usage/browser/browser-plugin-settings.png differ
diff --git a/plugins/_browser/AGENTS.md b/plugins/_browser/AGENTS.md
index 68e84f0b4..b790991e4 100644
--- a/plugins/_browser/AGENTS.md
+++ b/plugins/_browser/AGENTS.md
@@ -31,6 +31,7 @@
- Prefer DOM/CDP browser actions with refs, selectors, frame-chain refs, and screenshots over viewport coordinate input. Coordinates remain a visual fallback.
- Do not hardcode user-specific browser paths or secrets.
- Browser model-preset selection resolves omitted preset fields from `_model_config`'s global `Default` preset, not from an unrelated currently scoped model selection.
+- Internal-browser proxy settings map directly to Playwright's persistent-context proxy option, never to Bring Your Own Browser, and changes must restart active internal runtimes.
## Work Guidance
diff --git a/plugins/_browser/default_config.yaml b/plugins/_browser/default_config.yaml
index 896239304..22d05d2e8 100644
--- a/plugins/_browser/default_config.yaml
+++ b/plugins/_browser/default_config.yaml
@@ -22,6 +22,13 @@ max_open_tabs: 32
# - host_required: Bring Your Own Browser through A0 CLI and prepare it on first browser use when possible.
runtime_backend: "container"
+# Optional proxy used only by the internal Docker browser.
+# Server examples: http://proxy.example:3128 or socks5://proxy.example:1080.
+proxy_server: ""
+proxy_bypass: ""
+proxy_username: ""
+proxy_password: ""
+
# Local-model enforcement for host-browser content:
# - enforce_local: block host page content and screenshots unless the active chat model is local.
# - warn: allow and return a warning in tool output.
diff --git a/plugins/_browser/helpers/config.py b/plugins/_browser/helpers/config.py
index 964c242dc..e412b652c 100644
--- a/plugins/_browser/helpers/config.py
+++ b/plugins/_browser/helpers/config.py
@@ -17,6 +17,10 @@ RUNTIME_BACKEND_KEY = "runtime_backend"
HOST_BROWSER_PRIVACY_POLICY_KEY = "host_browser_privacy_policy"
HOST_BROWSER_PROFILE_MODE_KEY = "host_browser_profile_mode"
HOST_BROWSER_SELECTION_KEY = "host_browser_selection"
+PROXY_SERVER_KEY = "proxy_server"
+PROXY_BYPASS_KEY = "proxy_bypass"
+PROXY_USERNAME_KEY = "proxy_username"
+PROXY_PASSWORD_KEY = "proxy_password"
RUNTIME_BACKENDS = {"container", "host_required"}
BROWSER_TAB_SCOPES = {"per_context", "shared"}
HOST_BROWSER_PRIVACY_POLICIES = {"enforce_local", "warn", "allow"}
@@ -161,6 +165,10 @@ def normalize_browser_config(settings: dict[str, Any] | None) -> dict[str, Any]:
HOST_BROWSER_SELECTION_KEY: _normalize_host_browser_selection(
raw.get(HOST_BROWSER_SELECTION_KEY, raw.get("host_browser_choice", ""))
),
+ PROXY_SERVER_KEY: str(raw.get(PROXY_SERVER_KEY, "") or "").strip()[:2048],
+ PROXY_BYPASS_KEY: str(raw.get(PROXY_BYPASS_KEY, "") or "").strip()[:4096],
+ PROXY_USERNAME_KEY: str(raw.get(PROXY_USERNAME_KEY, "") or "")[:1024],
+ PROXY_PASSWORD_KEY: str(raw.get(PROXY_PASSWORD_KEY, "") or "")[:4096],
MODEL_PRESET_KEY: _normalize_model_preset(raw.get(MODEL_PRESET_KEY, "")),
}
@@ -169,6 +177,10 @@ def browser_runtime_config(settings: dict[str, Any] | None) -> dict[str, Any]:
config = normalize_browser_config(settings)
return {
"extension_paths": config["extension_paths"],
+ PROXY_SERVER_KEY: config[PROXY_SERVER_KEY],
+ PROXY_BYPASS_KEY: config[PROXY_BYPASS_KEY],
+ PROXY_USERNAME_KEY: config[PROXY_USERNAME_KEY],
+ PROXY_PASSWORD_KEY: config[PROXY_PASSWORD_KEY],
}
@@ -374,10 +386,12 @@ def describe_browser_extensions(settings: dict[str, Any] | None) -> dict[str, An
def build_browser_launch_config(settings: dict[str, Any] | None) -> dict[str, Any]:
- extensions = describe_browser_extensions(settings)
+ config = normalize_browser_config(settings)
+ extensions = describe_browser_extensions(config)
args = list(BASE_BROWSER_ARGS)
channel: str | None = None
browser_mode = "chromium"
+ proxy = None
if extensions["active"]:
joined_paths = ",".join(extensions["active_paths"])
@@ -388,8 +402,19 @@ def build_browser_launch_config(settings: dict[str, Any] | None) -> dict[str, An
]
)
+ if config[PROXY_SERVER_KEY]:
+ proxy = {"server": config[PROXY_SERVER_KEY]}
+ for config_key, proxy_key in (
+ (PROXY_BYPASS_KEY, "bypass"),
+ (PROXY_USERNAME_KEY, "username"),
+ (PROXY_PASSWORD_KEY, "password"),
+ ):
+ if config[config_key]:
+ proxy[proxy_key] = config[config_key]
+
return {
"args": args,
+ "proxy": proxy,
"browser_mode": browser_mode,
"channel": channel,
"extensions": extensions,
diff --git a/plugins/_browser/helpers/runtime.py b/plugins/_browser/helpers/runtime.py
index ef32e9278..f5ac52866 100644
--- a/plugins/_browser/helpers/runtime.py
+++ b/plugins/_browser/helpers/runtime.py
@@ -822,6 +822,8 @@ class _BrowserRuntimeCore:
launch_kwargs["channel"] = launch_config["channel"]
else:
launch_kwargs["executable_path"] = str(browser_binary)
+ if launch_config["proxy"]:
+ launch_kwargs["proxy"] = launch_config["proxy"]
try:
self.context = await self.playwright.chromium.launch_persistent_context(
**launch_kwargs
diff --git a/plugins/_browser/webui/browser-config-store.js b/plugins/_browser/webui/browser-config-store.js
index ca354444a..b41f210aa 100644
--- a/plugins/_browser/webui/browser-config-store.js
+++ b/plugins/_browser/webui/browser-config-store.js
@@ -37,6 +37,10 @@ function ensureConfig(config) {
config.browser_tab_scope = normalizeChoice(config.browser_tab_scope, BROWSER_TAB_SCOPES, "per_context");
config.max_open_tabs = normalizeInt(config.max_open_tabs, DEFAULT_MAX_OPEN_TABS, MIN_MAX_OPEN_TABS, HARD_MAX_OPEN_TABS);
config.runtime_backend = normalizeRuntimeBackend(config.runtime_backend);
+ config.proxy_server = String(config.proxy_server || "").trim();
+ config.proxy_bypass = String(config.proxy_bypass || "").trim();
+ config.proxy_username = String(config.proxy_username || "");
+ config.proxy_password = String(config.proxy_password || "");
config.host_browser_privacy_policy = normalizeChoice(
config.host_browser_privacy_policy,
HOST_PRIVACY_POLICIES,
diff --git a/plugins/_browser/webui/config.html b/plugins/_browser/webui/config.html
index 07a14c472..9b2ebf735 100644
--- a/plugins/_browser/webui/config.html
+++ b/plugins/_browser/webui/config.html
@@ -49,6 +49,59 @@
<span>Internal Docker browser selected. Host-browser CLI settings are ignored for Browser tool runs.</span>
</div>
+ <label
+ class="browser-config-field"
+ x-show="$store.browserConfig.config.runtime_backend === 'container'"
+ >
+ <span class="browser-config-field-label">Proxy server</span>
+ <input
+ type="text"
+ x-model="$store.browserConfig.config.proxy_server"
+ placeholder="http://proxy.example:3128 or socks5://proxy.example:1080"
+ autocomplete="off"
+ />
+ <span class="browser-config-field-help">Optional. Routes the internal browser through this HTTP or SOCKS proxy.</span>
+ </label>
+
+ <label
+ class="browser-config-field"
+ x-show="$store.browserConfig.config.runtime_backend === 'container'"
+ >
+ <span class="browser-config-field-label">Bypass proxy for</span>
+ <input
+ type="text"
+ x-model="$store.browserConfig.config.proxy_bypass"
+ placeholder="localhost, .example.com"
+ autocomplete="off"
+ />
+ <span class="browser-config-field-help">Optional comma-separated domains that should connect directly.</span>
+ </label>
+
+ <label
+ class="browser-config-field"
+ x-show="$store.browserConfig.config.runtime_backend === 'container'"
+ >
+ <span class="browser-config-field-label">Proxy username</span>
+ <input
+ type="text"
+ x-model="$store.browserConfig.config.proxy_username"
+ autocomplete="off"
+ />
+ </label>
+
+ <label
+ class="browser-config-field"
+ x-show="$store.browserConfig.config.runtime_backend === 'container'"
+ >
+ <span class="browser-config-field-label">Proxy password</span>
+ <input
+ type="password"
+ x-model="$store.browserConfig.config.proxy_password"
+ autocomplete="off"
+ />
+ <span class="browser-config-field-help">Saving proxy changes restarts active internal Browser sessions.</span>
+ </label>
+
<label
class="browser-config-field"
x-show="$store.browserConfig.config.runtime_backend === 'host_required'"
@@ -324,6 +377,7 @@
}
.browser-config-field input[type="text"],
+ .browser-config-field input[type="password"],
.browser-config-field input[type="number"],
.browser-config-field select {
width: 100%;
diff --git a/tests/test_browser_agent_regressions.py b/tests/test_browser_agent_regressions.py
index c8317d835..f23014adc 100644
--- a/tests/test_browser_agent_regressions.py
+++ b/tests/test_browser_agent_regressions.py
@@ -164,6 +164,10 @@ def test_browser_config_normalizes_extension_paths(tmp_path):
"host_browser_privacy_policy": "allow",
"host_browser_profile_mode": "existing",
"host_browser_selection": "",
+ "proxy_server": "",
+ "proxy_bypass": "",
+ "proxy_username": "",
+ "proxy_password": "",
"model_preset": "",
}
@@ -187,6 +191,24 @@ def test_browser_config_normalizes_host_backend_and_privacy_policy():
assert config["host_browser_profile_mode"] == "agent"
+def test_browser_config_builds_authenticated_internal_proxy():
+ config = normalize_browser_config(
+ {
+ "proxy_server": " socks5://proxy.example:1080 ",
+ "proxy_bypass": " localhost, .example.com ",
+ "proxy_username": "researcher",
+ "proxy_password": "secret",
+ }
+ )
+
+ assert build_browser_launch_config(config)["proxy"] == {
+ "server": "socks5://proxy.example:1080",
+ "bypass": "localhost, .example.com",
+ "username": "researcher",
+ "password": "secret",
+ }
+
+
def test_browser_config_normalizes_host_browser_selection():
assert normalize_browser_config({})["host_browser_selection"] == ""
assert (
@@ -307,6 +329,7 @@ def test_browser_launch_config_uses_full_chromium_for_all_sessions(tmp_path):
assert default_launch["browser_mode"] == "chromium"
assert default_launch["channel"] is None
assert default_launch["requires_full_browser"] is True
+ assert default_launch["proxy"] is None
assert not any(arg.startswith("--load-extension=") for arg in default_launch["args"])
assert "--headless=new" not in default_launch["args"]
@@ -1232,6 +1255,11 @@ def test_browser_extension_settings_stay_user_facing():
assert "Maximum tabs per chat" in config_html
assert 'x-model="$store.browserConfig.config.browser_tab_scope"' in config_html
assert 'x-model.number="$store.browserConfig.config.max_open_tabs"' in config_html
+ assert 'x-model="$store.browserConfig.config.proxy_server"' in config_html
+ assert 'x-model="$store.browserConfig.config.proxy_bypass"' in config_html
+ assert 'x-model="$store.browserConfig.config.proxy_username"' in config_html
+ assert 'x-model="$store.browserConfig.config.proxy_password"' in config_html
+ assert 'type="password"' in config_html
assert "normalizeMaxOpenTabs()" in config_html
assert "BROWSER_TAB_SCOPES" in config_store
assert "HARD_MAX_OPEN_TABS = 50" in config_store
@@ -2156,9 +2184,7 @@ def test_browser_runtime_context_close_event_clears_cached_state():
assert core.last_interacted_browser_id is None
-def test_browser_save_plugin_config_restarts_runtimes_on_change(monkeypatch, tmp_path):
- extension_dir = tmp_path / "extension"
- extension_dir.mkdir()
+def test_browser_save_plugin_config_restarts_runtimes_on_change(monkeypatch):
restarted = []
monkeypatch.setattr(
@@ -2166,6 +2192,7 @@ def test_browser_save_plugin_config_restarts_runtimes_on_change(monkeypatch, tmp
"_load_saved_browser_config",
lambda project_name="", agent_profile="": {
"extension_paths": [],
+ "proxy_server": "",
},
)
monkeypatch.setattr(
@@ -2176,13 +2203,14 @@ def test_browser_save_plugin_config_restarts_runtimes_on_change(monkeypatch, tmp
result = browser_hooks_module.save_plugin_config(
{
- "extension_paths": [str(extension_dir)],
+ "extension_paths": [],
+ "proxy_server": "http://proxy.example:3128",
},
project_name="",
agent_profile="",
)
- assert result["extension_paths"] == [str(extension_dir)]
+ assert result["proxy_server"] == "http://proxy.example:3128"
assert result["model_preset"] == ""
assert restarted == [True]