padreug
800afe647f
Some checks are pending
nix-bitcoin tests / build_test_drivers (push) Waiting to run
nix-bitcoin tests / test_scenario (default) (push) Blocked by required conditions
nix-bitcoin tests / test_scenario (joinmarket-bitcoind-29) (push) Blocked by required conditions
nix-bitcoin tests / test_scenario (netns) (push) Blocked by required conditions
nix-bitcoin tests / test_scenario (netnsRegtest) (push) Blocked by required conditions
nix-bitcoin tests / check_flake (push) Waiting to run
Show users how to configure lnd with the neutrino backend instead of bitcoind. This is useful for resource-constrained systems that can't run a full Bitcoin node, but provides less privacy and security than a local bitcoind. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| container | ||
| flakes | ||
| krops | ||
| nixops | ||
| qemu-vm | ||
| .gitignore | ||
| configuration.nix | ||
| deploy-container-minimal.sh | ||
| deploy-container.sh | ||
| deploy-krops.sh | ||
| deploy-qemu-vm.sh | ||
| importable-configuration.nix | ||
| krops-vm-configuration.nix | ||
| nix-bitcoin-release.nix | ||
| README.md | ||
| shell.nix | ||
| start-bash-session.sh | ||
Examples
The easiest way to try out nix-bitcoin is to use one of the provided examples.
Flakes-based quick start
If you use a Flakes-enabled version of Nix, run the following command to start a minimal nix-bitcoin QEMU VM:
nix run github:fort-nix/nix-bitcoin/release
The VM (defined in flake.nix) runs in the terminal and has bitcoind
and clightning installed.
It leaves no traces (outside of /nix/store) on the host system.
More examples
Clone this repo and enter the examples shell:
git clone https://github.com/fort-nix/nix-bitcoin
cd nix-bitcoin/examples/
nix-shell
The following example scripts set up a nix-bitcoin node according to ./configuration.nix and then
shut down immediately. They leave no traces (outside of /nix/store) on the host system.
By default, ./configuration.nix enables bitcoind and clightning.
-
./deploy-container.shcreates a NixOS container.
This is the fastest way to set up a node.
Requires: Nix, a systemd-based Linux distro and root privileges -
./deploy-qemu-vm.shcreates a QEMU VM.
Requires: Nix, Linux -
./deploy-krops.shcreates a QEMU VM and deploys a nix-bitcoin configuration to it using krops.
Requires: Nix, Linux -
./deploy-container-minimal.shcreates a container defined by importable-configuration.nix.
You can copy and import this file to use nix-bitcoin in an existing NixOS configuration.
The configuration doesn't use the secure-node.nix preset.
Requires: Nix, a systemd-based Linux distro and root privileges
Run the examples with option --interactive or -i to start a shell for interacting with
the node:
./deploy-qemu-vm.sh -i
Tests
The nix-bitcoin test suite is also useful for exploring features.
Real-world example
Check the server repo for https://nixbitcoin.org to see the configuration of a Flakes-based nix-bitcoin node that's used in production.
The commands in shell.nix allow you to locally run the node in a VM or container.
Flakes
Flakes make it easy to include nix-bitcoin in an existing NixOS config.
The flakes example shows how to use nix-bitcoin as an input to a system flake.
Persistent container with Flakes
The persistent container example shows how to run a Flake-based node
in a container.
Requires: A systemd-based Linux distro and root privileges.
Extending nix-bitcoin with Flakes
The mempool extension flake shows how to define new
pkgs and modules in a Flake.
Since mempool is now a core nix-bitcoin module, this Flake just serves as an example.