diff --git a/README.md b/README.md index 72f68e5..9816800 100644 --- a/README.md +++ b/README.md @@ -1,159 +1,1046 @@
-Sovran Systems +Sovran Systems logo # Sovran_SystemsOS -`Base Development` · NixOS Flake · AGPL-3.0 +### Your Bitcoin life. Your keys. Your node. Your machine. -[Sovran Systems](https://sovransystems.com) +Sovran_SystemsOS is a free and open-source Bitcoin operating system built for +self-custody, private peer-to-peer exchange, independent verification, and +digital sovereignty. + +Every installation includes a private NixOS desktop with **Sparrow Wallet, +Bisq, and Bisq 2** ready to use. Move beyond custodial exchanges, use Bitcoin +without making a centralized platform the center of your financial life, and +grow into running your own Bitcoin and Lightning infrastructure when you are +ready. + +**Privacy. Sovereignty. Bitcoin.** + +[Visit the Website](https://sovransystems.com) · +[Download the ISO](https://downloads.sovransystems.com/Sovran_SystemsOS.iso) · +[Verify the Download](https://downloads.sovransystems.com/Sovran_SystemsOS.iso.sha256) · +[Build from Source](#build-from-source)
-Sovran_SystemsOS desktop showing application dock and PRIVACY. SOVEREIGNTY. BITCOIN. tagline +Sovran_SystemsOS private Bitcoin desktop -*The Sovran_SystemsOS desktop — "Privacy. Sovereignty. Bitcoin."* +*Bitcoin sovereignty from the first boot.*
--- -## Table of Contents +## Bitcoin software should help you leave the middleman behind -1. [What This Repo Is](#what-this-repo-is) -2. [Architecture](#architecture) -3. [Module Catalog](#module-catalog) -4. [The Three Modes (internal reference)](#the-three-modes-internal-reference) -5. [Build & Deploy Reference](#build--deploy-reference) -6. [Networking & Reverse Proxy](#networking--reverse-proxy) -7. [Security Posture](#security-posture) -8. [Backups & Recovery](#backups--recovery) -9. [License](#license) +Bitcoin gives people the ability to hold and transfer value without asking a +bank, exchange, or custodian for permission. But that freedom depends on the +software and infrastructure you choose to use. + +Sovran_SystemsOS brings the essential tools together in one operating system: + +- **Hold your own keys** with Sparrow Wallet. +- **Buy and sell Bitcoin peer-to-peer** with Bisq and Bisq 2. +- **Use non-KYC Bitcoin tools** without depending on a custodial exchange account. +- **Verify your own Bitcoin** with a full node. +- **Connect your wallets to your node**, not a stranger's. +- **Use Lightning** with LND and Ride The Lightning. +- **Accept Bitcoin directly** with BTCPay Server. +- **Route the Bitcoin stack through Tor** for stronger network privacy. +- **Control everything from the Sovran Hub.** + +No custodian needs to hold your Bitcoin. No outside node needs to tell your +wallet what happened on the Bitcoin network. No third-party cloud needs to +control your data or services. + +> Sovran_SystemsOS provides tools for self-custody and peer-to-peer Bitcoin +> use. Users remain responsible for protecting their keys, understanding their +> trades, following applicable laws, and maintaining secure backups. --- -## What This Repo Is +## Bitcoin tools included from day one -Sovran_SystemsOS is defined entirely as a **Nix flake** (`flake.nix`) and built from source. There is no pre-built binary — the System Installer is produced from this tree. Everything the system does is declared here. +You do not need the largest computer or a fully synchronized Bitcoin node to +begin taking control of your Bitcoin. -The control center is the **Hub** — a built-in panel that lets the operator launch, monitor, and toggle services without touching a terminal. Under the hood, the Hub writes to `custom.nix`, which feeds back into the flake. +Every Sovran_SystemsOS mode includes the standard desktop Bitcoin applications: +**Sparrow Wallet, Bisq, and Bisq 2**. -## Architecture +### Sparrow Wallet -``` - ┌─────────────────────────┐ - │ flake.nix │ - │ inputs: nixpkgs, │ - │ nix-bitcoin, nixvim, │ - │ btc-clients │ - └───────────┬─────────────┘ - │ nixosModules.Sovran_SystemsOS - ▼ - ┌──────────────────────────┐ imports ┌──────────────────────────┐ - │ configuration.nix │────────────▶│ modules/modules.nix │ - │ boot / fs / users / │ │ core/* + services + opt │ - │ desktop / nix settings │ │ features │ - └──────────────────────────┘ └──────────┬───────────────┘ - ▲ │ - │ ./role-state.nix (mode/role) ▼ - │ ./custom.nix (user overrides) ┌────────────────────┐ - │ │ modules/*.nix │ - └───────── sovran-hub writes ───────▶│ synapse / wordpress│ - │ nextcloud / etc. │ - └────────────────────┘ -``` +Sparrow is a privacy-focused desktop Bitcoin wallet built for transparent, +secure self-custody. -- **`flake.nix`** declares two NixOS configurations: - - `nixosConfigurations.nixos` — the running system. - - `nixosConfigurations.sovran_systemsos-iso` — the System Installer. -- **`configuration.nix`** owns host concerns (boot, filesystems, users, desktop, locale, Nix settings, firewall, audio, backups). -- **`modules/modules.nix`** is the service router. Every other module is opt-in via flags read from `role-state.nix` and `custom.nix`. +Use Sparrow to: -## Module Catalog +- Create and manage Bitcoin wallets +- Connect signing devices and hardware wallets +- Build and inspect transactions +- Manage UTXOs and coin selection +- Use multisignature wallets +- Connect directly to your own Electrs server in Node mode -Defaults follow the import order in `modules/modules.nix`. Toggles live in `custom.nix` (the Hub writes them) and `role-state.nix`. +Your keys remain under your control. -| Module | Default | Purpose | +### Bisq + +Bisq is a decentralized peer-to-peer Bitcoin exchange. + +It allows buyers and sellers to trade directly without depositing their +Bitcoin with a centralized exchange. There is no central company holding user +funds and no conventional exchange account standing between participants. + +### Bisq 2 + +Bisq 2 is the next generation of the Bisq peer-to-peer trading network. It is +installed alongside Bisq so users can access both generations of the Bisq +ecosystem from the Sovran_SystemsOS desktop. + +Together, Sparrow, Bisq, and Bisq 2 provide a practical path to obtaining, +holding, and using Bitcoin without making a custodial exchange the center of +your financial life. + +--- + +## Three modes, one path toward Bitcoin sovereignty + +Every mode includes the same private NixOS and GNOME foundation, the Sovran +Hub, Sparrow Wallet, Bisq, and Bisq 2. + +What changes is how much Bitcoin and self-hosting infrastructure runs on the +machine. + +| Mode | Best for | Bitcoin capability | |---|---|---| -| `core/*` | **on** | Roles, Caddy, Njalla, Hub, desktop, perf, ssh-bootstrap | -| `php.nix`, `credentials.nix` | **on** | Required by web services & secrets | -| `synapse.nix` | **on** | Matrix homeserver | -| `wordpress.nix` | **on** | WordPress + PHP-FPM vhost | -| `nextcloud.nix` | **on** | Files / calendar / contacts | -| `vaultwarden.nix` | **on** | Bitwarden-compatible secrets vault | -| `bitcoinecosystem.nix` | **on** | bitcoind/electrs/LND/RTL/BTCPay (over Tor) | -| `wallet-autoconnect.nix` | **on** | Sparrow/Bisq ↔ node handshake | -| `haven.nix` | off | Nostr relay | -| `element-calling.nix` | off | LiveKit + JWT for E2E calling | -| `mempool.nix` | off | Mempool.space dashboard | -| `bitcoin-core.nix` | off | Switch node to Bitcoin Core (replaces default Bitcoin Knots + BIP110) | -| `rdp.nix` | off | xrdp remote desktop | -| `sshd.nix` | off | Public-facing OpenSSH | +| **Desktop** | Everyday users and computers with modest hardware | Sparrow, Bisq, and Bisq 2 for self-custody and peer-to-peer Bitcoin use | +| **Node** | People ready to verify and operate their own Bitcoin infrastructure | Everything in Desktop plus Bitcoin Knots, Electrs, LND, RTL, BTCPay Server, Tor, and wallet-to-node connections | +| **Server + Desktop** | Bitcoiners who also want to reclaim their communications, cloud, passwords, and web services | The complete Node stack plus private self-hosted services | -> Tor is wired directly into the Bitcoin stack. In `modules/bitcoinecosystem.nix`, `bitcoind`, `electrs`, and `lnd` all set `tor.enforce = true` and `tor.proxy = true`, and onion services are exposed for them. +### Desktop — start with your keys -## The Three Modes (internal reference) +Desktop mode is not a reduced or Bitcoin-free edition. -Selected by `role-state.nix`, resolved by `modules/core/role-logic.nix`. All three configurations are produced from this same flake. +It is a private everyday computer that includes: -| Mode | What's enabled on top of the base NixOS + GNOME | -|---|---| -| **Desktop** | Private daily-driver. Sparrow + Bisq included. | -| **Node** | Desktop + full Bitcoin stack (bitcoind/electrs/LND/RTL/BTCPay over Tor). | -| **Server+Desktop** | Node + self-hosting services (Synapse, Nextcloud, WordPress, Vaultwarden, Element Calling, etc.). | +- Sparrow Wallet +- Bisq +- Bisq 2 +- A clean GNOME desktop +- Privacy-respecting everyday applications +- Tor +- The Sovran Hub -## Build & Deploy Reference +This gives people a lower-hardware path to Bitcoin self-custody and +peer-to-peer, non-KYC Bitcoin tools from the first boot. -Internal commands. Run from the flake root. +You can begin with Desktop today and move to your own node when your hardware, +storage, and needs are ready. -| Action | Command | -|---|---| -| Build the System Installer | `nix build .#nixosConfigurations.sovran_systemsos-iso.config.system.build.isoImage` | -| Switch now | `sudo nixos-rebuild switch --flake .#nixos` | -| Test in current boot only | `sudo nixos-rebuild test --flake .#nixos` | -| Stage for next boot | `sudo nixos-rebuild boot --flake .#nixos` | -| Build only (no activation) | `nixos-rebuild build --flake .#nixos` | -| Update pinned inputs | `nix flake update` (then rebuild) | -| Rollback last switch | `sudo nixos-rebuild switch --rollback` | -| Garbage-collect (>7 days) | Automatic weekly; manual: `sudo nix-collect-garbage -d` | +**Recommended hardware:** -## Networking & Reverse Proxy +- 64-bit Intel or AMD processor, approximately 2015 or newer +- 8 GB RAM +- 256 GB SSD +- Any broadband connection -- **Firewall on by default** (`networking.firewall.enable = true`). Port are opened by the module that needs it. -- **Caddy** (`modules/core/caddy.nix`) terminates TLS for all HTTP services. -- **Njalla** dynamic DNS (`modules/core/njalla.nix`) keeps records in sync via a 15-minute cron job. -- **Tor** is enabled with `torsocks` available. The Bitcoin stack uses it directly — see [Security Posture](#security-posture). -- **SSH:** localhost-only by default (`core/sshd-localhost.nix`). - -## Security Posture +### Node — verify your own money -Facts about the defaults, straight from `configuration.nix` and the modules: +Node mode includes the private desktop and adds the full Bitcoin stack. -- **Reproducible builds.** Every artifact derives from `flake.lock`. The same commit produces the same OS. -- **Bitcoin stack over Tor.** In `modules/bitcoinecosystem.nix`, `bitcoind`, `electrs`, and `lnd` all set `tor.enforce = true`, and onion services are exposed for `bitcoind`, `electrs`, `lnd`, and friends. -- **Firewall on, public sshd off, RDP off, auto-login off, fail2bain active** -- **Kernel surface trimmed.** `boot.blacklistedKernelModules = [ "rxrpc" ];` -- **Weekly garbage collection** with `--delete-older-than 7d`. +Instead of asking someone else's server about your wallet and transactions, +you operate the infrastructure that performs the verification. -## Backups & Recovery +The Node stack includes: -`services.rsnapshot` snapshots hourly and daily to `/run/media/Second_Drive/BTCEcoandBackup/NixOS_Snapshot_Backup`: +- **Bitcoin Knots** — independently verify the Bitcoin timechain and consensus rules +- **Electrs** — connect compatible wallets to your own node +- **LND** — operate a Lightning node +- **Ride The Lightning** — manage Lightning through a web interface +- **BTCPay Server** — accept Bitcoin payments without a payment processor +- **Sparrow Wallet** — connect your wallet to your own infrastructure +- **Bisq and Bisq 2** — trade Bitcoin peer-to-peer +- **Tor integration** — improve network privacy across the Bitcoin stack +- **Sovran Hub** — launch, monitor, and reach everything from one place -``` -backup /home/ localhost/ -backup /var/lib/ localhost/ -backup /etc/nixos/ localhost/ -backup /etc/nix-bitcoin-secrets/ localhost/ -retain hourly 5 -retain daily 5 -cron hourly 0 * * * * -cron daily 50 21 * * * +Your node verifies. Your wallet connects to it. Your keys remain yours. + +**Recommended hardware:** + +- x86 Intel or AMD processor, approximately three years old or newer +- 16 GB RAM +- 500 GB NVMe SSD for the operating system +- 2 TB NVMe SSD for the Bitcoin timechain +- Unmetered broadband +- Approximately 200 Mbps download and 50 Mbps upload + +### Server + Desktop — sovereignty beyond money + +Server + Desktop includes the complete Bitcoin Node stack and extends the same +ownership model to the rest of your digital life. + +Run your own: + +- Private cloud +- Files, calendars, and contacts +- Encrypted communications +- Password vault +- Website +- Nostr relay +- Bitcoin payment infrastructure + +Bitcoin sovereignty is the foundation. Server + Desktop applies that principle +to your data, communications, identity, and services. + +**Recommended hardware:** + +- x86 Intel or AMD processor, approximately three years old or newer +- 32 GB RAM +- 500 GB NVMe SSD for the operating system +- 2 TB NVMe SSD for the Bitcoin timechain +- Unmetered broadband +- Approximately 200 Mbps download and 50 Mbps upload +- A domain for publicly accessible self-hosted services + +--- + +## Use Sovran_SystemsOS your way + +You do not have to replace the operating system on your current computer to +benefit from Sovran_SystemsOS. + +### Use it as your everyday computer + +Install Sovran_SystemsOS on a desktop, laptop, or mini PC and use its clean +GNOME desktop as your daily operating system. + +You receive a private desktop, the Sovran Hub, everyday applications, Bitcoin +software, and the tools included with your selected mode. + +### Use it as a private Bitcoin and home server + +Prefer to keep using Windows, macOS, Linux, Android, or iOS? + +Install Sovran_SystemsOS on a separate computer and let it run quietly on your +local network. From another device connected to the same network, open a web +browser and visit: + +```text +http://sovransystemsos.local ``` -The second drive is mounted by label (`BTCEcoandBackup`) with `nofail` so a missing drive doesn't block boot. +Sign in to the Sovran Hub and manage the system from your: + +- Windows computer +- Mac +- Linux computer +- Phone +- Tablet +- Any other device with a modern web browser + +Your Sovran_SystemsOS machine can operate as a private, headless Bitcoin and +self-hosting appliance. It can run without a monitor during everyday use while +you control it from the devices you already know. + +Your existing devices remain familiar. Sovran_SystemsOS provides the +independent infrastructure behind them. + +> **Local access:** `sovransystemsos.local` is intended for devices connected +> to the same local network as the Sovran_SystemsOS machine. The Hub is +> protected by authentication and is not automatically exposed to the public +> internet. + +--- + +## The Sovran Hub + +### Your private infrastructure, controlled from any screen. + +The Sovran Hub is the command center built into Sovran_SystemsOS. It is both a +local desktop application and a private web interface served directly by your +Sovran_SystemsOS machine. + +Use the Hub directly from the Sovran_SystemsOS desktop, or open it from another +device at: + +```text +http://sovransystemsos.local +``` + +From one place, the Hub helps you: + +- Open and monitor your services +- See what is running +- Start and stop supported services +- Configure system features +- Manage service domains +- Reach your Bitcoin tools +- Manage your private cloud and communications +- Perform supported system operations +- Control Sovran_SystemsOS without everyday terminal commands + +Nothing needs to be installed on the device opening the Hub. You only need a +modern browser and access to the same local network. + +### Example home setup + +```text + Your local network + │ + ┌──────────────────────┼──────────────────────┐ + │ │ │ + Windows laptop Phone or tablet Mac or Linux + │ │ │ + └──────── Browser: sovransystemsos.local ────┘ + │ + ▼ + ┌──────────────────────────┐ + │ Sovran_SystemsOS │ + │ │ + │ • Sovran Hub │ + │ • Bitcoin node │ + │ • Sparrow Wallet │ + │ • Bisq and Bisq 2 │ + │ • Lightning │ + │ • Private cloud │ + │ • Communications │ + │ • Password vault │ + │ • Hosted services │ + └──────────────────────────┘ +``` + +Keep using the devices you already own. Sovran_SystemsOS becomes the private +Bitcoin and digital infrastructure behind them. + +--- + +## What is included? + +Depending on the selected mode and enabled features, Sovran_SystemsOS brings +together a growing collection of private, open-source tools. + +### Your money — Bitcoin sovereignty + +- Bitcoin Knots +- Electrs +- LND +- Ride The Lightning +- BTCPay Server +- Sparrow Wallet +- Bisq +- Bisq 2 +- Tor integration +- Automatic wallet-to-node connections +- Optional Mempool explorer + +Run your own Bitcoin infrastructure. Verify your own money. Trust no one. + +### Your voice — private communications + +- Matrix Synapse +- Element +- Optional Element calling +- Optional Haven Nostr relay + +Communicate without making Big Tech the owner of your identity or +conversations. + +### Your cloud — self-hosting and storage + +- Nextcloud +- Vaultwarden +- WordPress +- Caddy +- Private service domains +- Optional remote desktop + +Keep your files, passwords, calendar, contacts, website, and services on +hardware you control. + +### Your desktop + +- GNOME desktop +- Brave +- Firefox +- File management +- Calendar and contacts +- Email client +- Office applications +- System monitoring tools +- Administration utilities + +Not every service is enabled in every mode. The Sovran Hub presents and +manages the features available on your system. + +--- + +## What makes Sovran_SystemsOS different? + +There are Linux distributions that can run a Bitcoin wallet. There are node +projects that can run Bitcoin services. There are self-hosting projects that +can replace individual cloud applications. + +Sovran_SystemsOS brings those worlds together. + +### Bitcoin from the first boot + +Sparrow, Bisq, and Bisq 2 are not optional suggestions buried in +documentation. They are installed as part of the operating system and +available from the desktop. + +### A complete path + +Begin with a private desktop and self-custody. Grow into peer-to-peer Bitcoin +exchange, your own node, Lightning, Bitcoin payments, and complete +self-hosting. + +### One control center + +The Sovran Hub brings the Bitcoin stack, private services, credentials, system +status, and supported configuration into one interface. + +### Your hardware + +The system runs on a computer you control. Your node, wallets, data, services, +and system configuration do not depend on a Sovran Systems cloud account. + +### Reproducible foundation + +Sovran_SystemsOS is built declaratively with NixOS and Nix flakes. Its inputs +are pinned, its configuration can be audited, and the system can be rebuilt +from source. + +--- + +# Download and install it yourself + +Sovran_SystemsOS is free and open source. You can download the installer, +verify it, write it to a USB drive, and install it yourself. + +You remain in control from the very first step. + +## What is an ISO? + +An ISO is a complete installation image containing the operating system and +the files required to boot the Sovran_SystemsOS installer. + +The ISO is not copied to a USB drive like an ordinary document. It must be +written to the USB drive with an imaging application such as Balena Etcher. + +## What you need + +Before beginning, you will need: + +- A compatible 64-bit computer +- A USB drive that can be erased +- Another computer for downloading and preparing the installer +- An internet connection +- A USB imaging application such as Balena Etcher +- A backup of anything important on the destination computer + +> **Important:** Installing an operating system can erase the selected +> destination drive. Back up important files and review every disk selection +> carefully before continuing. + +--- + +## Step 1: Download the ISO + +Download the Sovran_SystemsOS installer: + +### [Download Sovran_SystemsOS.iso](https://downloads.sovransystems.com/Sovran_SystemsOS.iso) + +Depending on your browser and internet connection, the download may take some +time. Do not rename or modify the file before verifying it. + +The downloaded file should be named: + +```text +Sovran_SystemsOS.iso +``` + +--- + +## Step 2: Download the checksum + +Download the matching SHA-256 checksum: + +### [Download Sovran_SystemsOS.iso.sha256](https://downloads.sovransystems.com/Sovran_SystemsOS.iso.sha256) + +A checksum is a digital fingerprint of a file. + +Verifying the checksum confirms that: + +- The complete ISO downloaded successfully +- The file was not accidentally corrupted +- The downloaded file matches the published image + +The checksum produced from your ISO must match the published checksum exactly. + +--- + +## Step 3: Verify the ISO + +Place the ISO and checksum file in the same folder, then follow the +instructions for your current operating system. + +### Linux + +Open a terminal in the download folder and run: + +```bash +sha256sum Sovran_SystemsOS.iso +``` + +You can also ask the checksum file to perform the comparison: + +```bash +sha256sum --check Sovran_SystemsOS.iso.sha256 +``` + +A successful comparison should report: + +```text +Sovran_SystemsOS.iso: OK +``` + +### macOS + +Open Terminal in the download folder and run: + +```bash +shasum -a 256 Sovran_SystemsOS.iso +``` + +Compare the value shown in Terminal with the value inside: + +```text +Sovran_SystemsOS.iso.sha256 +``` + +### Windows PowerShell + +Open PowerShell in the download folder and run: + +```powershell +Get-FileHash .\Sovran_SystemsOS.iso -Algorithm SHA256 +``` + +Compare the value under `Hash` with the published checksum. + +### If the values do not match + +Do not install the image if the checksums are different. + +1. Delete the downloaded ISO. +2. Download it again. +3. Repeat the verification. +4. Continue only after the values match exactly. + +--- + +## Step 4: Write the ISO to a USB drive + +Balena Etcher is available for Linux, macOS, and Windows. + +1. Download and install Balena Etcher. +2. Connect the USB drive. +3. Open Balena Etcher. +4. Choose **Flash from file**. +5. Select `Sovran_SystemsOS.iso`. +6. Choose **Select target**. +7. Select the correct USB drive. +8. Review the selected drive carefully. +9. Choose **Flash**. +10. Wait for the writing and verification process to finish. + +> **Warning:** Flashing the ISO erases the selected USB drive. Verify that you +> selected the USB drive and not another storage device. + +After flashing, your current operating system may report that it cannot read +the USB drive or may show several unfamiliar partitions. This can be normal for +a bootable Linux installer. + +Do not format the USB drive after flashing it. + +--- + +## Step 5: Boot from the USB drive + +1. Leave the prepared USB drive connected. +2. Shut down or restart the destination computer. +3. Open the computer's boot-device menu. +4. Select the USB drive. +5. Start the Sovran_SystemsOS installer. + +Common boot-menu keys include: + +- `F12` +- `F11` +- `F10` +- `F9` +- `Esc` +- `Delete` + +The correct key depends on the computer manufacturer. It is often briefly +shown on screen when the computer first powers on. + +If the normal operating system starts instead, restart and try the boot-menu +key again. + +--- + +## Step 6: Install Sovran_SystemsOS + +Follow the on-screen installer. + +Before confirming the installation: + +- Verify that you selected the correct destination drive. +- Back up any important data on that drive. +- Understand that existing partitions and data may be erased. +- Disconnect unrelated external drives if you are unsure which drive is which. +- Confirm that the computer is connected to reliable power. + +When installation is complete: + +1. Restart the computer. +2. Remove the USB drive when instructed. +3. Allow Sovran_SystemsOS to start from the installed drive. +4. Complete the initial setup. + +--- + +## Step 7: Open the Sovran Hub + +You can open the Hub directly from the Sovran_SystemsOS desktop. + +You can also open it from another device on the same local network. + +On your laptop, phone, tablet, or other computer, open a browser and visit: + +```text +http://sovransystemsos.local +``` + +Sign in using your Sovran_SystemsOS credentials. + +You can now use the Hub without sitting in front of the Sovran_SystemsOS +computer. + +### If `sovransystemsos.local` does not open + +Check the following: + +1. Make sure the Sovran_SystemsOS machine is powered on. +2. Make sure both devices are connected to the same local network. +3. Confirm that you entered the full address: + + ```text + http://sovransystemsos.local + ``` + +4. Avoid guest Wi-Fi networks, which may prevent devices from seeing one another. +5. Allow the Sovran_SystemsOS machine a few minutes to finish starting. +6. Temporarily disconnect a VPN that may be interfering with local-network access. +7. Try another browser or device on the same network. + +Some networks or devices may not support `.local` address discovery correctly. +Network isolation, custom DNS settings, VPNs, and some routers can interfere +with local-device discovery. + +--- + +## Two paths to get started + +### Download and install + +Sovran_SystemsOS is free, public, and open source. + +Download the ISO, verify the checksum, flash it to USB, and install it on your +own hardware. + +[Download the ISO](https://downloads.sovransystems.com/Sovran_SystemsOS.iso) + +### Guided help + +Not technical? You do not have to figure everything out alone. + +Visit the Sovran Systems website to learn about guided setup, supported +hardware, and Royal Membership. + +[Visit Sovran Systems](https://sovransystems.com) + +--- + +# For developers + +Sovran_SystemsOS combines the reproducibility of NixOS, the Bitcoin service +modules of nix-bitcoin, the desktop Bitcoin packages provided by +`btc-clients-nix`, and the Sovran Hub into a complete Bitcoin operating system. + +The operating system configuration, installer, Hub, desktop integration, +Bitcoin services, and optional self-hosting services are maintained in this +repository. + +## Technology + +- **NixOS and Nix flakes** for reproducible system configuration +- **nix-bitcoin** for declarative Bitcoin and Lightning services +- **btc-clients-nix** for Sparrow, Bisq, and Bisq 2 packages +- **Python and FastAPI** for the Sovran Hub backend +- **JavaScript, HTML, and CSS** for the Hub interface +- **GNOME** for the desktop environment +- **Caddy** for local and public service routing +- **Tor** for Bitcoin network privacy +- **AGPL-3.0** licensing + +--- + +## Build from source + +### Prerequisites + +You need a system with Nix installed and flakes enabled. + +Clone the repository: + +```bash +git clone https://github.com/naturallaw777/sovran-systems.git +cd sovran-systems +``` + +Build the installer: + +```bash +nix build \ + .#nixosConfigurations.sovran_systemsos-iso.config.system.build.isoImage +``` + +The resulting build output will be available through the `result` symlink. + +--- + +## Common development commands + +Run these commands from the flake root. + +### Build the installer + +```bash +nix build \ + .#nixosConfigurations.sovran_systemsos-iso.config.system.build.isoImage +``` + +### Build the system configuration + +```bash +nixos-rebuild build --flake .#nixos +``` + +### Test without making the change permanent + +```bash +sudo nixos-rebuild test --flake .#nixos +``` + +### Activate the new configuration + +```bash +sudo nixos-rebuild switch --flake .#nixos +``` + +### Stage the configuration for the next boot + +```bash +sudo nixos-rebuild boot --flake .#nixos +``` + +### Update pinned flake inputs + +```bash +nix flake update +``` + +Review and test input updates before committing the modified `flake.lock`. + +### Roll back the last activated generation + +```bash +sudo nixos-rebuild switch --rollback +``` + +--- + +## Repository map + +| Path | Purpose | +|---|---| +| `flake.nix` | Declares flake inputs, the running system, and installer outputs | +| `flake.lock` | Pins dependencies for reproducible builds | +| `configuration.nix` | Base host, boot, desktop, user, security, backup, and system configuration | +| `modules/` | Core modules, Bitcoin services, self-hosted services, and optional features | +| `modules/core/` | Roles, Hub integration, Caddy, desktop, support, and other core behavior | +| `app/` | Sovran Hub backend, templates, static assets, scripts, and web interface | +| `iso/` | Installer configuration, installer code, and installer assets | +| `assets/` | Repository documentation images | +| `custom.template.nix` | Template for local features and service overrides | +| `role-state.nix` | Selected Sovran_SystemsOS mode or role | + +--- + +## Architecture overview + +Sovran_SystemsOS is assembled from a reproducible Nix flake. + +```text + ┌─────────────────────────┐ + │ flake.nix │ + │ │ + │ Inputs and system │ + │ build outputs │ + └────────────┬────────────┘ + │ + ▼ + ┌─────────────────────────┐ + │ configuration.nix │ + │ │ + │ Host, desktop, users, │ + │ boot, security, backup │ + └────────────┬────────────┘ + │ + ▼ + ┌─────────────────────────┐ + │ modules/modules.nix │ + │ │ + │ Core modules, services, │ + │ and optional features │ + └────────────┬────────────┘ + │ + ┌──────────────────┼──────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌────────────┐ ┌────────────┐ ┌────────────┐ + │ Sovran Hub │ │ Bitcoin │ │ Private │ + │ and desktop│ │ ecosystem │ │ services │ + └────────────┘ └────────────┘ └────────────┘ +``` + +The Hub writes supported user choices into the local configuration. NixOS then +rebuilds the machine into the selected declarative state. + +--- + +## Module overview + +### Core modules + +Core modules provide the base Sovran_SystemsOS experience, including: + +- Role selection and role logic +- Sovran Hub +- GNOME desktop integration +- Caddy +- Local Hub access +- Network and domain support +- Local SSH operations +- Remote deployment support +- Technical support controls +- Performance and power behavior + +### Bitcoin services + +The Bitcoin stack includes: + +- Bitcoin Knots +- Electrs +- LND +- Ride The Lightning +- BTCPay Server +- Sparrow Wallet +- Bisq +- Bisq 2 +- Wallet-to-node connections +- Tor integration + +### Private services + +Self-hosted services include: + +- Matrix Synapse +- Nextcloud +- Vaultwarden +- WordPress + +### Optional features + +Optional features include: + +- Haven Nostr relay +- Element calling +- Mempool explorer +- Bitcoin Core selection +- Remote desktop +- Public-network SSH + +Feature availability and defaults may change as Sovran_SystemsOS develops. +Review the relevant Nix module before relying on a specific default in a +production environment. + +--- + +## Security approach + +Sovran_SystemsOS is designed around local ownership and explicit control. + +Its security foundations include: + +- Reproducible builds from pinned flake inputs +- Firewall enabled by default +- Public SSH disabled by default +- Remote desktop disabled by default +- Hub authentication +- Local-network Hub access through `sovransystemsos.local` +- Tor integration for the Bitcoin stack +- User-controlled service exposure +- Declarative system configuration +- Restricted technical-support access +- Auditable open-source code + +No operating system can guarantee complete security. Users should still apply +updates, protect credentials, maintain backups, secure their local network, +and review any services they choose to expose publicly. + +Bitcoin users must also securely back up wallet seed phrases, descriptors, +channel backups, and other recovery information. Never store your only wallet +backup on the same computer that holds the wallet. + +--- + +## Acknowledgements + +Sovran_SystemsOS stands on the work of exceptional free and open-source +projects and contributors. + +### NixOS + +Deep gratitude goes to the **NixOS team, the Nixpkgs maintainers, and the +broader Nix community**. + +NixOS provides the reproducible, declarative foundation that makes +Sovran_SystemsOS possible. Its module system, package ecosystem, flakes, and +generation-based system management allow an entire Bitcoin operating system +to be described, audited, rebuilt, upgraded, and rolled back from source. + +Sovran_SystemsOS would not have the same reliability, transparency, or +reproducibility without their years of work. + +### nix-bitcoin + +Special thanks go to the **nix-bitcoin project and its contributors**. + +nix-bitcoin provides the declarative foundation for building and operating +Bitcoin and Lightning services on NixOS. Its work makes it possible to +configure complex Bitcoin infrastructure—including nodes, Electrs, Lightning, +Tor integration, and related services—in a reproducible and auditable way. + +Sovran_SystemsOS builds upon that foundation to make this infrastructure +approachable through an integrated desktop, installer, and Sovran Hub. + +### Emmanuel Rosa and btc-clients-nix + +Special thanks go to **Emmanuel Rosa** for +[`btc-clients-nix`](https://github.com/emmanuelrosa/btc-clients-nix). + +The project provides Nix packages for the Bitcoin desktop software central to +the Sovran_SystemsOS experience: + +- Sparrow Wallet +- Bisq +- Bisq 2 + +This work helps make it possible for Sovran_SystemsOS to deliver self-custody +and peer-to-peer Bitcoin tools as part of every installation. + +### The upstream Bitcoin ecosystem + +Sovran_SystemsOS also depends on the work of the developers and communities +behind: + +- Bitcoin Knots +- Bitcoin Core +- Sparrow Wallet +- Bisq +- Bisq 2 +- Electrs +- LND +- Ride The Lightning +- BTCPay Server +- Tor +- NixOS +- GNOME +- Caddy +- Nextcloud +- Matrix Synapse +- Element +- Vaultwarden +- WordPress +- Every other upstream project included in the system + +Sovran Systems did not create these foundations. Our work is to bring them +together into a cohesive operating system that helps more people use Bitcoin +privately, independently, and with confidence. + +Thank you to every developer, maintainer, reviewer, tester, documentarian, and +user who keeps this ecosystem alive. + +--- ## License -Licensed under the **GNU Affero General Public License v3.0** — see [`LICENSE`](./LICENSE). +Sovran_SystemsOS is free and open-source software licensed under the +[GNU Affero General Public License v3.0](LICENSE). + +The AGPL-3.0 protects your freedom to: + +- Use Sovran_SystemsOS +- Study how the system works +- Modify the source code +- Share original or modified versions +- Build and operate the system on your own hardware + +If you distribute a modified version, you must make its corresponding source +code available under the same license. + +Because Sovran_SystemsOS includes the browser-based Sovran Hub, operators who +modify the covered software and make that modified version available for users +to interact with over a network must offer those users access to its +corresponding source code, as required by the AGPL-3.0. + +Sovran_SystemsOS is provided **without warranty**, as described in the full +license. + +> Individual upstream applications, packages, artwork, fonts, and other +> components included with or built by Sovran_SystemsOS may have their own +> licenses and copyright holders. The AGPL-3.0 license for this repository does +> not replace the licenses of independent upstream projects. + +Read the complete license terms in [`LICENSE`](LICENSE). + +--- + +
+ +## Privacy. Sovereignty. Bitcoin. + +### Your Bitcoin life. Your keys. Your node. Your machine. + +[Visit Sovran Systems](https://sovransystems.com) · +[Download Sovran_SystemsOS](https://downloads.sovransystems.com/Sovran_SystemsOS.iso) · +[View the License](LICENSE) + +