Developers Build and contribute
Docs

Developers

Build and contribute

View as Markdown

Build Nanobrowser from source, load it in Chrome or Edge, learn how it works and send your first pull request.

On this page

Nanobrowser is open source under the Apache License 2.0. The code is on GitHub.

Build from source

You need:

  • Node.js 24 LTS, version 24.11.0 or later.
  • pnpm 10. With corepack enable, pnpm switches to the version the project pins (10.34.7).

Clone and build:

git clone https://github.com/nanobrowser/nanobrowser.git
cd nanobrowser
corepack enable # skip if pnpm 10 is already installed
pnpm install
pnpm build      # builds the extension into dist/

Load it in Chrome or Edge

  1. Open chrome://extensions (in Edge, edge://extensions).
  2. Turn on Developer mode.
  3. Click Load unpacked and choose the dist folder.

Then set it up and use it as in the Quickstart.

Update your build

  1. Pull the latest source with git pull.
  2. Run pnpm install, then pnpm build.
  3. On the extensions page, click the reload icon on the Nanobrowser card.

How does it work?

Nanobrowser has three main parts.

  • The browser control layer looks at the page, acts on it and reports what happened. It has no AI model in it, so the same input always gives the same result.
    • Each element the agent sees gets an ID tied to that exact element. If the page changes, an old ID stops working instead of pointing at something else.
    • Clicks and typing are real browser input. Before it acts, the layer checks that the element is visible, not moving, enabled and not covered.
    • Each action is sent once. The result says whether it went through, whether the page responded and whether the page reached the expected state.
    • It talks to the page only through Chrome’s chrome.debugger API, and uses Puppeteer to keep track of the frames on a page.
  • The agent loop runs on top of the layer. There is one agent per conversation. In each turn it calls the model once, then runs the tools the model asked for, such as a click or a page read. It stops when the task is done, when you click Stop, or at the turn limit. Every model gets the same tools, and only vision models get screenshots. What the agent may do on its own is checked in code, outside the model, and no model can change it.
  • The test panel lets you try the layer by hand, with no model. To open it, bind a key to the open-test-panel command in chrome://extensions/shortcuts. By default, it asks you before it runs a submit, pay or delete action, or a page script.

Where is the code?

  • src/browser-control/: the browser control layer.
  • src/agent/: the agent loop, its tools and prompts.
  • src/llm/: model providers.
  • src/side-panel/ and src/options/: the side panel and the settings page.
  • src/extension/: the parts that run in the background and connect everything.

AGENTS.md explains the full layout, the design rules and how we work. It is also the guide for AI coding assistants.

Development commands

pnpm dev          # development mode: rebuilds and reloads as you edit; load dist/ in Chrome
pnpm build        # release build into dist/
pnpm zip          # release build, packed as a zip file in dist-zip/
pnpm type-check   # check types
pnpm lint         # check code style and import rules
pnpm prettier     # format the code
pnpm test         # run the unit tests

Run the tests

  • Unit tests: pnpm test. They use Vitest and live in __tests__/ folders under src/.
  • Browser tests: run pnpm install-chrome once to install Chrome for Testing. Then run pnpm autorun scenarios. It runs the checks on local test pages, without opening a browser window.

Before you open a pull request, make sure pnpm prettier, pnpm lint, pnpm type-check and pnpm test pass. CI runs the same checks, plus a build, on every push and pull request.

How can I contribute?

  • Share prompts and ideas on Discord.
  • Give feedback on Discord or in GitHub Discussions.
  • Report a bug in GitHub Issues. Search first. Say what you did, step by step, your operating system, your browser and its version, your Nanobrowser version, and the provider and model you used. Never include API keys or passwords.
  • Send code. Read CONTRIBUTING.md first. Then:
    1. Fork the repository and create a branch.
    2. Make one change per pull request.
    3. Add unit tests for pure functions, and a test page and scenario for anything that needs a browser.
    4. Open a pull request.

Read AGENTS.md before a larger change. Some design rules there are fixed.

Report a security problem

Don’t post it in public issues, pull requests or discussions. Report it through a GitHub Security Advisory, so it can be fixed before it is made public. See SECURITY.md.

Search docs