Self-hosted service
silverbulletmd/silverbullet avatar
silverbulletmd/silverbullet

SilverBullet: Markdown Pages, SLIQ queries, and Space Lua in headless Chrome

An open source personal productivity platform built on Markdown, turbo charged with the scripting power of Lua

6,570 stars535 forksTypeScriptMIT

At a glance

What is it?
SilverBullet is a self-hosted Markdown notes app whose extension language is Space Lua, and whose server runs that Lua inside headless Chrome. This reads the 2.12.1 codebase: the Rust workspace, the two build halves, and what the slim container image leaves out.
Who is it for?
SilverBullet fits a person or a small team that wants notes to stay a folder of Markdown files plus their own Lua, and that is willing to run a Rust server. It fits badly if you need a one-command end-user install, because the README only links out for that, or if you deploy the slim Docker image and then expect server-side Lua to answer.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • silverbulletmd/silverbullet6,570 ★ · +433
Star history
Repository2026-09-232026-11-21
silverbulletmd/silverbullet6.1k6.6k

433 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Markdown Pages, bi-directional links, and SLIQ queries

Your content is a collection of Markdown Pages, and that collection is called a Space. Navigation has two shapes. A Page Picker behaves like a traditional notes app, and Links behave like a wiki except that they are bi-directional, so a link appears on both pages instead of only where you typed it.

Four sets of tools sit on top of the pages, aimed at different habits. Live Preview for people who write prose. Outlining tools for people who think in bullets. Tasks for people tracking work. And Objects with Queries, called SLIQ, for people who would rather treat notes as a database than as a folder tree. That last one is the unusual part: a query language ships with the editor rather than arriving as something you install later.

What the Page model does not settle is scale and sharing. The README does not say how large a Space is meant to grow before queries slow down, and it does not document a sync or conflict story for two people editing the same Page. Both questions matter before you migrate an existing notes folder in.

Space Lua runs server-side in headless Chrome

Space Lua is SilverBullet's Lua dialect, and it is where the programmability lives: dynamically generating content, writing custom Commands, Page Templates and Widgets. The interesting engineering decision is where that code runs. The server is written in Rust and, among the things it serves, is a headless-Chrome runtime for server-side Lua. That runtime lives in its own crate, `server-runtime-chrome/`, named as the runtime backend, while `server/` is described as the HTTP router, handlers, auth, runtime seam. The seam is the word for the boundary where Rust hands work across.

Three plug-related directories ship with the project: `plugs/` holds built-in plugs in TypeScript distributed with SilverBullet, `libraries/` holds space scripts, page templates and slash templates, and `plug-api/` is the surface plug authors write against. The compiler for them sits at `bin/plug-compile.ts`.

What this arrangement does not give you is a documented failure story. The README does not say what happens to a Space Lua call when the Chrome runtime is missing, when a script loops forever, or when a plug throws inside a template. Read the runtime crate before you put a script on a path a user can trigger.

From clone to server: Node 24, stable Rust, and a browser download

Building the server yourself has real prerequisites: Node.js 24+ and npm 10+ for the client and the plugs, and stable Rust installed through rustup for the server. The repository ships `.nvmrc` and `.node-version`, so a version manager picks the right Node release for you:

shell
nvm use  # If using nvm

Then the dependency step, which is not only an npm install:

shell
make setup

That target runs `npm install` and then `npx playwright install`, so a browser download is part of your first build even if you never intend to run the browser tests. A release build follows, and it produces `silverbullet` and `cli` binaries in `./target/release/`:

shell
make

Start the server by handing it a data folder:

shell
./target/release/silverbullet <PATH-TO-YOUR-DATA-FOLDER>

Notice what is not here: an end-user install command. The Installing section is a single link to `https://docs.silverbullet.md/Install`, and everything above is the developer path. If you want SilverBullet running rather than hacking on it, that documentation site is the only source this repository offers for the steps.

A debug server reads client_bundle/ from disk, a release build embeds it

The two halves rebuild independently, and the difference between them is not only speed. The client, TypeScript in `client/`, is built by ESBuild into `client_bundle/`. The server half is the Rust set `server/`, `server-common/`, `server-runtime-chrome/` and `bin/silverbullet/`, compiled to a binary. In development:

shell
npm run build
cargo run <PATH-TO-YOUR-DATA-FOLDER>

A debug build serves the client bundle live from `client_bundle/` on disk, so changing only TypeScript means rebuilding the bundle and reloading the page, with no server restart. A release build embeds the bundle into the binary instead, which is why the comment on the Makefile's `build-e2e` target says embedded assets are covered separately by `test-e2e-release` rather than by the debug path.

The client is CodeMirror 6 with Preact for extra UI, so anything written against `plug-api/` executes in a browser runtime rather than in Node, even though that API is published to npm.

The container picks its own data folder and health-checks /.instance

The Docker route exists so you need neither Node nor Rust locally. The README's build command uses the root Dockerfile, which is the slim variant without Chromium (Dockerfile.runtime-api layers Chromium on top to create the default image):

shell
docker build -t silverbullet .

Run it with the data folder bind mounted at `/data`:

shell
docker run -p 3000:3000 -v <PATH-TO-YOUR-DATA-FOLDER>:/data silverbullet

The image mechanics settle several things you would otherwise have to guess. `SB_HOSTNAME` is set to `0.0.0.0` and `SB_PORT` to `3000`, and the health check curls `http://localhost:$SB_PORT/.instance`. `SB_FOLDER` is deliberately left unset so the entrypoint resolves the data folder itself, to `/data` or to the legacy `/space`, and a comment states the data folder can only be set via SB_FOLDER. Extra arguments, with `--single` as the example given, are forwarded to the server instead.

Two details are easy to miss. Stock accounts are wiped from `/etc/passwd` and `/etc/group` so arbitrary PUID and PGID values cannot collide with existing ones, and the entrypoint runs `$SB_FOLDER/CONTAINER_BOOT.md` if you place that file in your data folder.

The slim image has no Chromium, so /.runtime/* answers 503

This is the sharpest limit in the container story, and it is stated at the top of the Dockerfile: this variant is the SLIM one, no Chromium, so `/.runtime/*` returns 503. `Dockerfile.runtime-api` layers Chromium on top to create the default image. Build the wrong file and server-side Lua has nowhere to run while the rest of the app keeps working.

There is also a `Dockerfile.website` sitting in the same root, and nothing in the README says what it builds. Three build contexts next to each other is easy to mix up, and this particular mistake fails as a 503 on one path rather than as a container that refuses to start, which makes it a quiet break rather than an obvious one.

If you run the slim image on purpose, treat server-side Lua as unavailable and keep script work on the client side. Nothing in the README states which other features depend on that runtime, so the honest answer is that the dependency map stops at the runtime path itself.

reqwest stays on 0.12 so armv7 and freebsd cross-compiles keep working

The Rust side is a Cargo workspace with seven members, `server-common`, `server`, `server-search`, `server-runtime-chrome`, `server-merge`, `bin/silverbullet` and `bin/sb`, all on edition 2021 under an MIT workspace license. A `default-members` line narrows bare Cargo commands to the server binary:

toml
default-members = ["bin/silverbullet"]

CI compensates by passing `--workspace` explicitly, so clippy and tests still cover every crate regardless of that default. Lint policy is centralised as well: `all = "warn"` under `[workspace.lints.clippy]`, with CI running `cargo clippy -- -D warnings` to turn them into hard errors.

The dependency that explains the project's platform reach is reqwest, pinned below:

toml
reqwest = { version = "0.12", features = ["rustls-tls", "json", "blocking", "stream"], default-features = false }

The reason sits in a comment beside it: the 0.12 `rustls-tls` feature uses the ring crypto provider, which cross-compiles cleanly to every static-musl target including armv7 and freebsd, while 0.13's rustls path moved to aws-lc-rs, which needs a C toolchain and CMake. That one line is what lets `build-for-docker` emit aarch64, x86_64 and armv7 musl binaries.

One version number ties package.json, the binary and the releases

Three releases sit between September and October 2026: 2.11.1 on 2026-09-22, 2.12.0 on 2026-10-06 and 2.12.1 on 2026-10-12. The version in `package.json` is 2.12.1, matching the newest release, and a `version.ts` sits at the repository root next to `CHANGELOG.md`. The repository is not archived, the default branch is `main`, and the last push was on 2026-11-01.

The published package is `@silverbulletmd/silverbullet`, ESM only, described as a self-hosted, web-based note taking app. Its exports map points straight at TypeScript sources:

json
"./lib/tags": "./plug-api/lib/tags.ts",

Roughly thirty entries cover `syscall`, `syscalls`, `constants` and `ui`, libraries for json, tree, ref, resolve, dates, fuzzy, crypto, tags, collation, transclusion and query_expression, plus a `type/` family for client, config, manifest, namespace, datastore, event and revisions. The only compiled artifact in the package is the `plug-compile` binary, mapped to `dist/plug-compile.js`.

Licensing is the uncomplicated part: the repository carries `LICENSE.md` and the Cargo workspace declares `license = "MIT"`.

Editorial conclusion

SilverBullet fits a person or a small team that wants notes to stay a folder of Markdown files plus their own Lua, and that is willing to run a Rust server. It fits badly if you need a one-command end-user install, because the README only links out for that, or if you deploy the slim Docker image and then expect server-side Lua to answer. Check three things first: whether /.runtime/* returns 503 in the image you plan to run, whether Node 24+ and stable Rust are available on the build host, and whether LICENSE.md grants what your organisation needs from an MIT project.

Frequently asked questions

What does a SilverBullet do?

It is a browser-based, self-hosted Markdown notes app whose content is a Space of Markdown Pages, with bi-directional links, Outlining tools, Tasks, Objects and SLIQ queries, and Space Lua for custom Commands, Page Templates and Widgets. The server is written in Rust and serves the pre-built client bundle, a file and space HTTP API, authentication, and a headless-Chrome runtime for server-side Lua.

How do I use SilverBullet?

The README gives no end-user command; its Installing section links to https://docs.silverbullet.md/Install. From a clone the documented path is `make setup`, then `make`, then `./target/release/silverbullet <PATH-TO-YOUR-DATA-FOLDER>`, with Node.js 24+, npm 10+ and stable Rust installed beforehand.

What is SilverBullet?

A programmable, private, browser-based, open source, self-hosted personal knowledge database, described in its own README as a notes app on steroids. It keeps content as Markdown Pages, navigates them with a Page Picker or with bi-directional Links, and adds a query language called SLIQ plus a Lua dialect on top.

What is SilverBullet software?

The stack is a TypeScript client on CodeMirror 6 with Preact for extra UI, built by ESBuild, served by a Rust Cargo workspace of seven members. Its npm package is @silverbulletmd/silverbullet at version 2.12.1, and the docs are published as docs.silverbullet.md and bundled as the Desktop app's Help.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. silverbulletmd/silverbullet on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/silverbulletmd-silverbullet.svg)](https://hysenlabs.com/projects/silverbulletmd-silverbullet)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/silverbulletmd-silverbullet.svg)](https://hysenlabs.com/projects/silverbulletmd-silverbullet)

Was this useful?