Note
This project and its documentation are a work in progress. Parts of the project and the documentation may change and may be outdated.
bitcoinix is a collection of Nix packages and NixOS modules for easily installing full-featured Bitcoin nodes with an emphasis on security.
It is a community fork of nix-bitcoin, which was archived in August 2026. bitcoinix is a community initiative to keep the project maintained and to continue its development.
- Original project: fort-nix/nix-bitcoin
- Historical documentation and releases up to v0.0.139: see the archived
fort-nix/nix-bitcoin repository.
The state of the original repository at the time of forking is tagged
forkedin this repository.
bitcoinix can be used for personal or merchant wallets, public infrastructure or for Bitcoin application backends. In all cases, the aim is to provide security and privacy by default. However, while bitcoinix is used in production today, it is still considered experimental.
bitcoinix nodes can be deployed on dedicated hardware, virtual machines or containers. The Nix packages and NixOS modules can be used independently and combined freely.
bitcoinix is built on top of Nix and NixOS which provide powerful abstractions to keep it highly customizable and maintainable. Testament to this are its robust security features and its potent test framework. However, running bitcoinix does not require any previous experience with the Nix ecosystem.
Warning
Note that the NixOS option namespace is still nix-bitcoin.* (e.g. nix-bitcoin.configVersion).
It is kept to not break existing configurations.
This is a summary of the proposal and community discussion on issue #12 regarding the project's direction, supported features, and hardware.
- Upstream first: Most packages should move upstream to nixpkgs. Ideally, bitcoinix serves solely as a collection of securely cooperating service modules (see issue #7).
- New services: To request support for a new project or package, please open an issue or PR so that its addition can be discussed.
- No inactive projects: Projects with a long-term lack of activity, maintenance or development are not added. Existing unmaintained projects are removed or migrated to active forks (e.g. PR #1).
masteris unstable (for now):mastersees a faster pace of changes for a while, so treat it as bitcoinix unstable. All tests pass before a change is merged, but not every issue may be caught. Please report bugs, patches are always welcome.- Deployment examples:
examples/flakes(nixos-rebuild) andexamples/colmenashow how to deploy a node. CI builds them on every pull request. Contributions for other tools are welcome.
- See the examples for an overview of all features.
- To set up a new node from scratch, see the installation instructions.
- To add bitcoinix to an existing NixOS configuration, see importable-configuration.nix and the Flake example.
Prefer the dedicated NixOS options provided by bitcoinix. User-supplied settings in
extraConfig are unsupported, and you take full responsibility for their
correctness, security and compatibility with bitcoinix. They may override managed
settings or bypass security checks; successful evaluation does not mean they are safe.
This also applies to configuration files loaded through raw settings such as
Bitcoin Core's includeconf.
bitcoinix emits an evaluation warning for non-empty extraConfig on enabled
services. Built-in presets and plugins can also populate these options; the
responsibility notice applies to settings you supply yourself.
See customizing your configuration.
The documentation at docs.bitcoinix.net describes the latest release.
For changes on master, see docs/.
- NixOS options search
- Hardware requirements
- Installation
- Configuration and maintenance
- Upgrading
- Using services
- FAQ
A configuration preset for setting up a secure node
- All applications use Tor for outbound connections and support accepting inbound connections via onion services.
NixOS modules (src)
- Application services
- Bitcoin Core (
services.bitcoind) - Core Lightning (CLN) with support for announcing an onion service
(
services.clightning) and database replication.
Available plugins:- CLBOSS: automated Core Lightning node manager
- clnrest: REST API and WebSocket notifications for Core Lightning
- currencyrate: currency converter
- feeadjuster: automatically adjusts channel fees to keep channels balanced
- monitor: helps you analyze the health of your peers and channels
- rebalance: keeps your channels balanced
- trustedcoin (experimental): replaces bitcoind with trusted public explorers
- zmq: publishes notifications via ZeroMQ to configured endpoints
- LND with support for announcing an onion service and static channel backups
- charge-lnd: policy-based channel fee manager
- lndconnect: connect your wallet to LND or Core Lightning via WireGuard or Tor
- Ride The Lightning (RTL): web interface for LND and Core Lightning
- mempool: Bitcoin visualizer, explorer, and API service
- electrs: Electrum server
- Fulcrum: Electrum server (see the module for a comparison with electrs)
- BTCPay Server
- Bitcoin Hardware Wallet Interface (HWI)
- Bitcoin Core (
- Helper
- netns-isolation: isolates applications at the network level via network namespaces
- nodeinfo: script which prints info about the node's services
- backups: duplicity backups of selected node data, with configurable extra files
- operator: configures a non-root user who has access to client tools (e.g.
bitcoin-cli,lightning-cli)
bitcoinix aims to achieve a high degree of security by building on the following principles:
- Simplicity: Only services enabled in
configuration.nixand their dependencies are installed, support for doas (sudo alternative), code is continuously reviewed and refined. - Integrity: The Nix package manager guarantees that all dependencies are exactly specified, packages can be built from source to reduce reliance on binary caches, release tags are signed with maintainer SSH keys and verified by
helper/fetch-release.sh(see SECURITY.md), upstream packages are cryptographically verified where possible, we use this software ourselves. - Principle of Least Privilege: Services operate with the minimum necessary privileges; they each have their own user and are restricted further with systemd features, RPC whitelisting and netns-isolation. There's a non-root user operator to interact with the various services.
- Defense-in-depth: bitcoinix provides an optional kernel and system hardening preset, services are confined through discretionary access control, Linux namespaces, D-Bus firewall and seccomp-bpf with continuous improvements.
Note that if the machine you're deploying from is insecure, there is nothing bitcoinix can do to protect itself.
There is no security fund. The project relies on responsible vulnerability reports and on the good faith of the community. See SECURITY.md for how to report a vulnerability and for past reports.
See dev/README, including building Linux targets from macOS with OrbStack or Docker.
If you are having problems with bitcoinix, check the FAQ or
submit an issue.
We are always happy to help.