Nectar Browser is a Windows desktop shell for browser automation. You point it at any OpenAI-compatible endpoint — OpenAI, OpenRouter, Ollama, LM Studio, vLLM, or your own gateway — describe a task in plain language, and an isolated Python worker drives a real, visible Chromium window while the app streams every step back to you.
The shell is deliberately weighted toward runtime architecture, credential handling, diagnostics, and packaging rather than decoration.
- Bring your own model. Any OpenAI-compatible chat-completions endpoint, cloud or loopback.
- Keys stay encrypted. Windows DPAPI via Electron
safeStorage; the renderer never sees the secret or its ciphertext, and keys are redacted from every diagnostic stream. - Real browser, real cleanup. A fresh temporary Chromium profile per run, killed and deleted
afterwards — including the scratch directories
browser-useleaves in%TEMP%. - Hardened renderer. Context isolation, sandbox, CSP, no Node integration, HTTP(S)-only preview navigation, and trusted-frame-only IPC.
- Ships as one installer. A relocatable CPython distribution and Chromium are staged into the build, so installed users need neither Python nor npm.
- Cancels cleanly. Cooperative cancellation, backend deadlines, and parent-disconnect detection, so a crashed shell never orphans a worker or its browser.
Install Node.js 22.12+ (prefer current LTS) and CPython 3.12 x64, including the py
launcher. An internet connection is needed to download npm/Python dependencies and Chromium.
Administrator rights are not required for the app or its per-user installer.
Set-Location 'C:\path\to\nectar-browser'
npm ci
npm run setup:python
npm startSetup creates a local virtual environment and installs the complete Windows dependency lock and Playwright Chromium. No global Python packages are modified. There are no Python model downloads: run Ollama, LM Studio, or vLLM separately with your chosen model already available. On Windows, vLLM commonly runs under WSL2 or on a remote server.
Then, in the app:
- Select a provider and enter its API root, exact model identifier, and API key.
- Save the connection. Local loopback servers may omit the key.
- Enter the automation start URL and task, review the consent warning, then run.
- Watch the separate visible Chromium window and the diagnostics stream. Cancel stops the worker and its browser processes.
| Provider | Default API root | Notes |
|---|---|---|
| OpenAI | https://api.openai.com/v1 |
Account/model access required |
| OpenRouter | https://openrouter.ai/api/v1 |
Use the exact routed model ID, e.g. organization/model |
| Ollama | http://127.0.0.1:11434/v1 |
Uses the OpenAI compatibility API, not /api/chat |
| LM Studio | http://127.0.0.1:1234/v1 |
Start the local API server first |
| vLLM | http://127.0.0.1:8000/v1 |
Use the server's served model name |
| Custom | User supplied | Arbitrary gateway paths are preserved |
Enter an API root, not a complete /chat/completions URL. Root paths for named providers are
normalized; Ollama /api maps to /v1. HTTPS is required for non-loopback API hosts. Embedded
credentials, query-string API keys, and fragments are rejected. Corporate/private endpoints must
provide trusted TLS; TLS verification is never disabled. Azure-specific authentication and
non-OpenAI wire formats are deliberately out of scope.
Important
Compatibility is not capability. The endpoint must implement chat completions and its model
must reliably return valid browser-use action JSON. Strict structured output is enabled by default;
disable it for servers that reject response_format. Text-only DOM operation is used, so a vision
model is not required. None of this makes a weak or incompatible model reliably automate arbitrary
sites — rate limits, authentication, CAPTCHA, website policies, and unsupported API parameters can
still cause failures. No fallback silently sends your data to another provider.
Sandboxed renderer (index.html + src/ui.js)
| explicit contextBridge methods; no Node primitives
v
preload.js -> trusted-main-frame IPC -> main.js -> lib/agent-bridge.cjs
| | spawn(python.exe), shell:false
| electron-store metadata | stdin: JSON request / cancel
| safeStorage (DPAPI) key ciphertext | stdout: bounded NDJSON
v v
agent_engine.py
| Pydantic validation
v
your OpenAI-compatible endpoint <--> browser-use
|
visible Playwright Chromium <---+
The in-window preview and the agent's browser are separate. The preview is a sandboxed iframe
that respects X-Frame-Options and CSP; the agent drives its own real Chromium window with a
throwaway profile. An empty preview does not mean the agent failed.
| Document | Contents |
|---|---|
| Architecture | Process topology, IPC surface, worker protocol, event and exit-code contracts |
| Security | What the sandbox does and does not enforce, credential handling, limitations |
| Building | Windows installer, runtime staging, code signing and signature verification |
| Testing | Every suite, packaged-build testing, the opt-in live-endpoint check |
| Validation record | Results of a full local validation pass, and what it does not cover |
npm test # syntax checks + 10 JavaScript unit tests
npm run test:python # 18 Python unit tests
npm run test:browser # headless Chromium smoke
npm run test:electron # desktop launch and security smoke
npm run test:integration # bridge + browser-use against a mock modelEvery suite above uses a mock model, which proves transport but says nothing about a real endpoint.
npm run test:live runs one real workflow, gated on a per-run code the model can only produce by
reading the page. See Testing.
Node integration is off; context isolation, renderer sandbox, CSP, web security, trusted-frame IPC,
denied popups/permissions/downloads, and HTTP(S)-only preview navigation are on. The Python worker
receives a minimal environment with telemetry, cloud sync, and .env loading disabled.
Warning
The automation worker is not an OS security sandbox. It runs as the current user, and there is no per-action approval gate — a task may submit forms or take irreversible actions. Temporary profiles and tool exclusions reduce risk but do not guarantee resistance to page or model prompt injection. Use trusted endpoints, disposable accounts, and a low-privilege Windows account or VM for anything sensitive.
Full detail, including what is explicitly not enforced, is in Security.
Implemented and integration-tested software — not a security audit, a claim of universal endpoint compatibility, or a completed enterprise certification. Clean-machine installer acceptance, dependency license review, enterprise proxy policy, and security review remain release gates.
UNLICENSED — all rights reserved by the Nectar Browser contributors. No open-source license is
granted; see package.json.