~/vimma/docs $ less install.md

Install and first launch

There is nothing to download yet. You build Vimma from source on Linux x86_64, then start it with a profile of its own, so your Firefox profile is never touched.

Build it

The commands, requirements and timings are on the install page. In short: Linux x86_64, about 35 GB of free disk, Node.js, Python 3 and git, and about 40 minutes for the first build.

Start it

From the checkout:

npm start                   # your build, with its own profile
npm start -- --fresh        # a throwaway profile, deleted when Vimma quits
npm start -- --profile DIR  # another profile you keep

The profile lives in ~/.cache/vimma-dev-profile. Vimma will not open the same profile twice: if it refuses to start, switch to the window that is already open.

What you see first

• No tab strip. Vimma hides it. The status bar, the line at the bottom of the window, shows the mode, the workspace and which tab you are on (tab 1/1).
• The start page, with the three keys to start from: ctrl+b ? for every key, : for commands, f for link hints.
• The URL bar is focused, so you can type an address straight away and press Enter.

Your first five minutes

1. Type an address in the URL bar and press Enter.
2. Scroll with j and k. d and u move half a page; gg and G go to the top and the bottom.
3. Press f: a yellow label appears on every link. Type a label's letters to follow that link. H goes back.
4. Press ctrl+b, let go, then press c: a new tab. ctrl+b n and ctrl+b p move between tabs.
5. Click a search box and type: you are in insert mode, and keys type as usual. Esc leaves the box, and the keys are Vimma's again.
6. Lost? ctrl+b ? lists every key; type / to filter the list, Esc to close it.

Next: Modes explains when a key is a command and when it types.

Where Vimma keeps its files

Details

Everything below is Vimma's own user guide for this topic, in full: every edge case and exception. You do not need it to get started.

Install

There are no packages or binaries yet. Tarballs, an AppImage, a .deb and AUR vimma-bin are planned. Until then, build from source as the README describes: npm ci, npx surfer download, npx surfer bootstrap, npm run import, npx surfer build. The first build takes about 40 minutes on a 16-thread machine and needs about 35 GB of disk space (engine/ 27 GB, the sccache compiler cache 6.8 GB, ~/.mozbuild 3.1 GB, .surfer/ 0.8 GB).

First launch, with its own profile

Start Vimma from the checkout with npm start. It runs your build with a profile of its own, ~/.cache/vimma-dev-profile, so your Firefox profile is never touched:

npm start                   # the full build, or the artifact build if that is all there is
npm start -- --fresh        # a throwaway profile, deleted when Vimma quits
npm start -- --profile DIR  # another persistent profile

It will not start a second Vimma on a profile that is already open; switch to that window instead. The profile's user.js gets one line Vimma needs when run from a source checkout (read access for web pages' sandbox to the checkout's src/); your own lines there are kept.

Where Vimma keeps its files on Linux:

On a profile's first launch, if ~/.config/vimma/config.toml does not exist, Vimma creates it from the same commented template :config writes, so it changes nothing until you uncomment a line, and the status bar says created ~/.config/vimma/config.toml once. An existing file, even an empty one, and the rest of ~/.config/vimma/ (key files, the vimma/ profiles folder) are left alone. A file you delete later stays deleted. The packaged builds do the same on their first launch. Nothing is created when vimma.config.path points Vimma at another file.

On first launch you see a calm window: no tab strip, the navigation bar and URL bar at the top, and Vimma's status bar at the bottom, telling you where you are. Press ctrl+b, then ?, to see every binding.

The start page

New windows and new tabs open Vimma's start page: the logo, and under it the three keys to start from (ctrl+b ? keys, : commands, f hints). The URL bar is empty and focused, so you can type an address straight away; click the page to use : and the other keys there. It is a local page (chrome://browser/content/vimma/start/start.html); nothing loads from the network.

To change it back:

• Home page and new windows: Settings (about:preferences#home) → "Homepage and new windows", or set browser.startup.homepage in about:config. "Restore Defaults" there brings the start page back.
• New tabs: set vimma.startpage.newtab to false in about:config (applies at once) for Firefox's new tab page. Settings' "New tabs" menu does not change Vimma's start page. An extension that sets its own new tab page takes precedence.

Installing (planned, not yet released)

Planned; no release has these files yet. Each GitHub Release will carry, for Linux x86_64 (X.Y.Z is the Vimma version):

The .deb and the AUR package add Vimma to your application menu and offer it for web links, but never make it your default browser on their own: xdg-settings set default-web-browser vimma-vimma.desktop does that. Vimma has no in-app updater: update through apt, your AUR helper, or by downloading the next AppImage or tarball. Next to the files are SHA256SUMS, a CycloneDX SBOM (vimma-X.Y.Z.cdx.json) and cosign signatures (*.sigstore.json); how to check them is in runbook.md ("Verify a release").

Known limits

Vimma is pre-alpha. What does not work yet, or works with a catch, is listed on the known limits page:

• Platforms and packaging
• Files and profiles

The guide at the top is written for this site; the details are built from Vimma's docs/guide.md and bindings.md at 1050bcc (2026-10-10).