---
title: Set up Freedom Browser for development
description: Build and run Freedom Browser from source: prerequisites, toolchains for optional components, the Linux sandbox fix, tests and debugging.
kick: Contribute
dek: Clone, install, run. Plus the toolchains the optional parts need, which is where most first builds get stuck.
source: https://github.com/solardev-xyz/freedom-browser/blob/main/docs/development.md
---

Thanks for helping build a browser for the decentralized web. Code, tests,
documentation, issue triage and reproducible bug reports are all welcome.
New here? Start with [Open for contribution](open-issues.html.md) and say hello in
the [community](community.html.md); we offer mentorship.

This page follows [docs/development.md](https://github.com/solardev-xyz/freedom-browser/blob/main/docs/development.md) on
`main`. When they disagree, that file and the scripts in `package.json` win.

## Prerequisites

- **Node.js 24 LTS.** The exact version is pinned in
  [`.nvmrc`](https://github.com/solardev-xyz/freedom-browser/blob/main/.nvmrc) (24.18.1 at the time of writing); with nvm, run
  `nvm install && nvm use` in the checkout.
- npm (bundled with Node.js) and Git.
- The platform build tools that Electron native modules need.
- **CMake 3.16+ and a C++ toolchain** (Xcode command-line tools on macOS, MSVC
  Build Tools on Windows, a C++ compiler and Make on Linux). `npm start`
  builds the offline whisper.cpp runtime for local dictation from pinned
  source the first time, and fails without CMake. The result is cached.
- **Linux (Debian/Ubuntu):** the udev and libusb headers, because `npm ci`
  rebuilds the Ledger USB module from source:

```bash
sudo apt install libudev-dev libusb-1.0-0-dev
```

Without `libudev-dev`, `npm ci` fails with
`fatal error: libudev.h: No such file or directory`.

## Clone, install, run

```bash
git clone https://github.com/solardev-xyz/freedom-browser.git
cd freedom-browser
npm ci
npm run ant:download
npm run ipfs:download
npm run myotis:download
npm run myotis:build-supervisor
npm start
```

The Swarm node (Ant) and IPFS start automatically. Radicle and Myotis are
opt-in under **Settings → Nodes → Startup**.

### Linux: the Chromium sandbox

On distributions that restrict unprivileged user namespaces (Ubuntu 24.04
and later), `npm start` aborts with
`The SUID sandbox helper binary was found, but is not configured correctly`.
Electron downloads its binary on first launch, so fetch it, then hand the
helper to root:

```bash
npx --no install-electron
sudo chown root:root node_modules/electron/dist/chrome-sandbox
sudo chmod 4755 node_modules/electron/dist/chrome-sandbox
```

Repeat after every `npm ci` and every Electron upgrade. Do not develop with
`--no-sandbox`: it hides real behaviour.

## Optional components and their toolchains

| Component | Command | Needs |
| --------- | ------- | ----- |
| Myotis supervisor | `npm run myotis:build-supervisor` | An installed C compiler: Apple clang or the command-line tools on macOS, a native C compiler on Linux, an **x64 MSVC developer shell** on Windows. Nothing is downloaded for you |
| Radicle | `npm run radicle:download` | Nothing extra; prebuilt for macOS, Linux and Windows x64/ARM64. Then enable Radicle for the profile under **Settings → Nodes** |
| Tor | `npm run tor:download` | **Rust** at or above the pinned Arti release's minimum version (`MIN_RUST_VERSION` in [`scripts/fetch-arti.js`](https://github.com/solardev-xyz/freedom-browser/blob/main/scripts/fetch-arti.js); the script checks). Arti is compiled for the host only. Linux also needs OpenSSL headers (and `libsqlite3-dev` when `pkg-config` is installed); Windows needs the x64 MSVC tools. Then enable Tor under **Settings → Advanced** |
| Linux workspace helper | built by `npm start` | `/usr/bin/gcc`. Without it, startup continues with a warning and skips the helper |

## Tests and checks

| Script | What it does |
| ------ | ------------ |
| `npm run lint` | ESLint. Run it after every code change |
| `npm test` | Jest unit suite. Most modules have a neighbouring `.test.js` |
| `npm run test:e2e` | Playwright harness with deterministic node and naming stubs; fast, no network |
| `npm run test:e2e:live` | Real nodes, protocols and name resolution; needs the downloaded binaries |
| `npm run test:e2e:packaged` | Smoke tests against a built binary (`FREEDOM_E2E_EXECUTABLE`) |
| `npm run test:e2e:startup-smoke` | Fails if the main process blocks for more than 1 s in its first 90 s |
| `npm run ant:smoke-upload` | A Swarm buy, upload and download round trip |
| `npm run ipfs:native:smoke` | Smoke-tests the native IPFS addon |
| `npm run check-binaries` | Validates packaged native binary targets |

On headless Linux, run the Playwright suites under `xvfb-run -a`. Formatting:
run `npx prettier --check` on the files you touched, because the repo-wide
`npm run format:check` currently fails on existing drift. Other scripts,
such as `radicle:build-addon` (libradicle from a sibling checkout) and
`adblock:download`, are listed in [development.md](https://github.com/solardev-xyz/freedom-browser/blob/main/docs/development.md#common-npm-scripts).

## Debugging

- **Menu (☰) → Developer Tools** (or `F12`) for the current page.
- **View → App Developer Tools** for Freedom's own UI, including navigation
  events.
- The terminal shows main-process output. `DEBUG=1 npm start` turns on
  verbose logging.
- `FREEDOM_LOG_SYNC=1` writes every log line synchronously, for chasing a
  main-thread hang or a native crash.

Next: [Architecture](architecture.html.md) · [Workflow](workflow.html.md)