Sovran Systems logo # Sovran_SystemsOS ### Bitcoin sovereignty. Sovereign computing. One system. Sovran_SystemsOS is a free and open-source operating system built for two inseparable freedoms: **Bitcoin self-custody** and **sovereign computing**. Hold your own keys, trade peer-to-peer, and verify your own money with your own node. Then claim that same uncompromising ownership over the rest of your digital life — your files, communications, passwords, and websites — all on hardware you control, running auditable open-source software you can trust. Every installation is a private [NixOS](https://nixos.org) desktop with **[Sparrow Wallet](https://sparrowwallet.com)**, **[Bisq](https://bisq.network)**, and **[Bisq 2](https://github.com/bisq-network/bisq2)** ready to use. Move beyond custodial exchanges from the first boot, and grow into your own Bitcoin node, Lightning infrastructure, private cloud, and communications platform when you are ready. [Visit the Website](https://sovransystems.com) · [Download the ISO](https://downloads.sovransystems.com/Sovran_SystemsOS-1.2.0.iso) · [Try it safely in a VM](#try-it-first-in-a-virtual-machine) · [Verify the Download](https://downloads.sovransystems.com/Sovran_SystemsOS-1.2.0.iso.sha256) · [Build from Source](#build-from-source) Sovran_SystemsOS private Bitcoin desktop *Bitcoin sovereignty from the first boot.*
> **📌 Active development on GitHub `main` / Gitea `staging-dev` — releases on > [Gitea `stable`](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable).** > See [Development workflow](#development-workflow) for details. --- ## Contents - [Why Sovran_SystemsOS?](#why-sovran_systemsos) - [Try it first in a virtual machine](#try-it-first-in-a-virtual-machine) - [What is included](#what-is-included) - [Three modes](#three-modes) - [Use it your way](#use-it-your-way) - [The Hub](#the-hub) - [Install Sovran_SystemsOS](#install-sovran_systemsos) - [For developers](#for-developers) - [Development workflow](#development-workflow) - [Build from source](#build-from-source) - [Publishing a release](#publishing-a-release) - [About Bitcoin wallet entropy](#about-bitcoin-wallet-entropy) - [Security approach](#security-approach) - [Acknowledgements](#acknowledgements) - [License](#license) · [Contributing](#contributing) --- ## Why Sovran_SystemsOS? Bitcoin lets you hold and transfer value without asking a bank, exchange, or custodian for permission, but that freedom depends on the software and infrastructure you choose. Your wider digital life works the same way: files, messages, and passwords kept on someone else's servers are never fully yours. Sovran_SystemsOS solves both with one operating system: - **Hold your own keys** with **Sparrow Wallet**. Create and manage wallets, connect hardware signing devices, use multisignature setups, build and inspect transactions, and control UTXOs and coin selection. - **Buy and sell Bitcoin peer-to-peer** with **Bisq** and **Bisq 2**. No central company holds user funds, and no exchange account stands between buyers and sellers. - **Verify your own Bitcoin** with a full node: [Bitcoin Core](https://bitcoin.org) and [Electrs](https://github.com/romanz/electrs), so your wallets connect to *your* node instead of a stranger's. - **Use Lightning** with [LND](https://github.com/lightningnetwork/lnd) and [Ride The Lightning](https://github.com/Ride-The-Lightning/RTL). - **Accept Bitcoin directly** with [BTCPay Server](https://btcpayserver.org), with no payment processor in the middle. - **Own the rest of your digital life** with [Nextcloud](https://nextcloud.com) files and calendars, [Matrix](https://matrix.org) communications, a [Vaultwarden](https://github.com/dani-garcia/vaultwarden) password vault, and your own [WordPress](https://wordpress.org) website. - **Protect your network privacy** with [Tor](https://www.torproject.org) integration across the Bitcoin stack. - **Control everything from the Sovran Hub**, on the desktop or from any browser on your local network. Other projects solve one piece of this puzzle: a distribution that runs a wallet, a node project that runs Bitcoin services, a self-hosting stack that replaces a cloud app. Sovran_SystemsOS brings them together on a reproducible, auditable NixOS foundation: Bitcoin tools from the first boot, one control center, and hardware you own. > 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. --- ## Try it first in a virtual machine **Curious, but not ready to replace your current operating system?** Start with Sovran_SystemsOS in a virtual machine (VM): a window on your existing Windows, macOS, or Linux computer, using a virtual disk file instead of your internal drive. Explore the desktop, Sovran Hub, Sparrow, Bisq, and the installation experience before changing how you use any physical machine. Closing or deleting the VM leaves your current operating system untouched, and installing on a dedicated computer later is still open to you. Use the same ISO with [VirtualBox](https://www.virtualbox.org), VMware, QEMU/KVM, Proxmox, and similar x86_64 VM software. For a first look, select **Desktop Only**, allocate at least **8 GB RAM**, and create a **256 GB or larger dynamically allocated virtual disk**. Full requirements are in [Installing in a virtual machine](#installing-in-a-virtual-machine-optional). > **A VM is for evaluation and learning, not a substitute for a dedicated, > hardened setup.** Do not hold meaningful Bitcoin, recovery phrases, > passwords, or other sensitive data in a trial VM. Avoid attaching physical > drives, and be deliberate about shared folders, clipboard sharing, and > network settings. Review VM disk selections before confirming an install. --- ## What is included Depending on the selected mode and enabled features, Sovran_SystemsOS brings together a growing collection of private, open-source tools. The Sovran Hub presents and manages the features available on your system. ### Your money — Bitcoin sovereignty - Bitcoin Core, Electrs, and Tor integration - LND and Ride The Lightning, with [Alby Hub](https://albyhub.com) for Nostr Wallet Connect (NWC) connections - BTCPay Server - Sparrow Wallet, Bisq, and Bisq 2, with automatic wallet-to-node connections - Optional: a self-hosted [Mempool](https://github.com/mempool/mempool) explorer Run your own Bitcoin infrastructure. Verify your own money. Trust no one. ### Your voice — private communications - The [Synapse](https://github.com/element-hq/synapse) homeserver (Matrix) and the [Element](https://element.io) client - Optional Matrix-native Element audio and video calling, powered by [LiveKit](https://livekit.io) - Optional [Haven](https://github.com/bitvora/haven) [Nostr](https://github.com/nostr-protocol/nostr) relay Communicate without making Big Tech the owner of your identity or conversations. ### Your cloud — self-hosting and storage - Nextcloud files, calendars, and contacts - Vaultwarden password vault - WordPress websites - [Caddy](https://caddyserver.com) with private service domains - Optional remote desktop Keep your files, passwords, calendar, contacts, website, and services on hardware you control. ### Your desktop - [GNOME](https://www.gnome.org) desktop - [Brave Origin](https://brave.com/origin/) and [Firefox](https://www.mozilla.org/firefox) browsers - File management, email, calendar, and office applications - System monitoring and administration tools --- ## Three modes Every mode shares the same foundation: the private NixOS and GNOME desktop, the Sovran Hub, and Sparrow, Bisq, and Bisq 2. What changes is how much Bitcoin and self-hosting infrastructure runs on the machine. | Mode | Best for | What you get | |---|---|---| | **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 the full Bitcoin stack: Bitcoin Core, Electrs, LND, Ride The Lightning, BTCPay Server, and wallet-to-node connections. **Publishes nothing unless you enable *Put BTCPay Server Online* or *Lightning Wallet Connections*:** [read this first](#server--desktop-and-your-home-ip-address) | | **Server + Desktop** | Bitcoiners who want the same sovereignty over their communications, cloud, passwords, and web services | The complete Node stack, plus the private self-hosted services. **Makes your home IP address public:** [read this first](#server--desktop-and-your-home-ip-address) | **Desktop: start with your keys.** Desktop is not a reduced or Bitcoin-free edition: it is a complete, private everyday computer with a clean GNOME desktop, Tor, and the Sovran Hub, and a lower-hardware path to self-custody and non-KYC Bitcoin tools from the first boot. Move to Node mode when your hardware, storage, and needs are ready. **Node: verify your own money.** You operate the infrastructure that performs the verification instead of asking someone else's server: your node verifies, your wallet connects to it, your keys stay yours. Node publishes nothing by default. Two Node features need a public domain and make your home IP address public when enabled: **Put BTCPay Server Online** and **Lightning Wallet Connections**. Everything else, Mempool and Ride The Lightning included, stays on your home network or reaches you through Tor — see [Server + Desktop and your home IP address](#server--desktop-and-your-home-ip-address). **Server + Desktop: sovereignty beyond money.** The same principle, applied to your data, communications, identity, and services. ### Recommended hardware | | **Desktop** | **Node** | **Server + Desktop** | |---|---|---|---| | Processor | 64-bit Intel or AMD, ~2015 or newer | Intel or AMD x86, ~3 years old or newer | Same as Node | | RAM | 8 GB | 16 GB | 32 GB | | Storage | 256 GB SSD | 500 GB NVMe (OS) + 2 TB NVMe (timechain) | Same as Node | | Network | Any broadband | Unmetered, ~200 Mbps down / 50 Mbps up | Same as Node | | Also needed | — | — | A domain for publicly accessible services | > **Before choosing Server + Desktop:** this mode makes services reachable from > the public internet, which means opening specific ports on your home network. > Before you start, confirm three things: you can log in to your router's admin > panel, the panel includes a port-forwarding section, and your internet > provider allows port forwarding. ### Server + Desktop and your home IP address > **⚠️ Server + Desktop makes your home IP address public.** > Public services need a domain name that points at your home internet > connection. When you finish the guided domain setup, Sovran_SystemsOS puts > your home's public IP address in a Dynamic DNS record at > [Njal.la](https://njal.la) and keeps it up to date, and you forward ports 80 > and 443 on your router to this computer. From then on: > > - **Anyone can look up your domain and see your home IP address,** which > reveals your internet provider and approximate location and ties everything > you publish on that domain to your home connection. Domain privacy does not > hide it: registrar privacy protects the registrant's identity, not the IP > address in your DNS records. > - **Your connection is open to the whole internet on those ports.** Scanners > and bots constantly probe public IP addresses, so expect automated probing > and login attempts against every service you publish. > - **Your service names are discoverable.** Public HTTPS certificates are > listed in Certificate Transparency logs, so hostnames such as > `vault.yourdomain.com` can be found and resolved to your IP address, even > if you never share them. **Desktop** publishes nothing. **Node** publishes nothing unless you enable *Put BTCPay Server Online* or *Lightning Wallet Connections* — see [Three modes](#three-modes). **If you do not want your home IP address to be public,** choose Desktop or Node. Advanced users can put a VPS, reverse proxy, or tunnel in front of their services so DNS points there instead of at their home; Sovran_SystemsOS does not set that up, and the Hub's domain checks expect DNS to point at your home IP address.
What happens technically - You create a **Dynamic** DNS record at Njal.la and paste its update command into the Hub, which only accepts `njal.la` update URLs. - The `sovran-ddns-update` timer points your record at the address the request came from: after you save a domain, two minutes after boot, then every 15 minutes. Element calling and the Hub use that same address. See `modules/core/njalla.nix`. - Once a service that needs a domain is on, the firewall opens TCP and UDP ports 80 and 443 for Caddy, which requests public HTTPS certificates for the domains you configure. The Hub lists any additional ports a feature needs. See `modules/core/caddy.nix`.
--- ## Use it your way You do not have to replace the operating system on your current computer to benefit from Sovran_SystemsOS. ### 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, with the Bitcoin software and the tools of your selected mode already in place. ### 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, with or without a monitor. From any other device on the same network, open a browser, visit `http://sovransystemsos.local:8937`, and manage everything from [the Hub](#the-hub). --- ## The Hub ### Your private infrastructure, controlled from any screen. The Hub is the command center built into Sovran_SystemsOS: a local desktop application and a private web interface served by your Sovran_SystemsOS machine. The device opening it needs only a modern browser and access to the same local network. From one place, the Hub lets you: - Open, monitor, start, and stop your services - Configure system features and manage service domains and credentials - Reach your Bitcoin tools, private cloud, and communications - Perform supported system operations without everyday terminal commands The Sovran Hub welcome dashboard *The Hub: your whole system at a glance — Bitcoin, Lightning, and your private apps.* ### Example home setup ```text Your local network │ ┌──────────────────────┼──────────────────────┐ │ │ │ Windows laptop Phone or tablet Mac or Linux │ │ │ └─────── Browser: sovransystemsos.local:8937 ─┘ │ ▼ ┌──────────────────────────┐ │ Sovran_SystemsOS │ │ │ │ • The Hub │ │ • Bitcoin node │ │ • Sparrow Wallet │ │ • Bisq and Bisq 2 │ │ • Lightning │ │ • Private cloud │ │ • Communications │ │ • Password vault │ │ • Hosted services │ └──────────────────────────┘ ``` > **Local access:** the Hub is available at > `http://sovransystemsos.local:8937` to devices connected to the same local > network (not on Desktop, which publishes nothing). It is protected by > authentication and answers only your local network. ### Tech Support The Hub can give a Sovran Systems technician temporary access to your machine. Support runs over SSH, and **Tech Support requires SSH Remote Access, which is off by default.** Turning SSH on makes the machine listen on all interfaces and opens **TCP port 22** in the firewall. Letting support in from outside your home means forwarding port 22 on your router, which puts SSH on the public internet where scanners and brute-force attempts will find it. Turn SSH off when the session ends; the Hub prompts you to. Support signs in as the restricted `sovran-support` account, not as root, with one key that expires after 24 hours. Wallet paths stay locked unless you unlock them for a limited time, and every session event is written to `/var/log/sovran-support-audit.log`. See [Restricted support access](SECURITY.md#restricted-support-access). --- ## Install Sovran_SystemsOS Sovran_SystemsOS is free and open source: download the installer, verify it, write it to a USB drive, and install it yourself, in control from the first step. An ISO is a complete installation image containing the operating system and installer. It is not copied to a USB drive like a document; it must be written with an imaging application such as [Balena Etcher](https://etcher.balena.io). **Before you begin, you will need:** - A compatible 64-bit computer, and a backup of anything important on it - A USB drive that can be erased - Another computer for downloading and preparing the installer - An internet connection > **Important:** Installing an operating system can erase the selected > destination drive. Back up important files and review every disk selection > carefully before continuing. ### 1. Download the ISO and checksum - [Download Sovran_SystemsOS-1.2.0.iso](https://downloads.sovransystems.com/Sovran_SystemsOS-1.2.0.iso) - [Download Sovran_SystemsOS-1.2.0.iso.sha256](https://downloads.sovransystems.com/Sovran_SystemsOS-1.2.0.iso.sha256) The download may take some time. Do not rename or modify the ISO before verifying it, and keep both files in the same folder. ### 2. Verify the checksum A checksum is a digital fingerprint of a file. Verifying it confirms the ISO downloaded completely and without corruption. The checksum produced from your ISO must match the published one exactly.
Linux Open a terminal in the download folder and run: ```bash sha256sum --check Sovran_SystemsOS-1.2.0.iso.sha256 ``` A successful comparison reports: ```text Sovran_SystemsOS-1.2.0.iso: OK ```
macOS Open Terminal in the download folder and run: ```bash shasum -a 256 Sovran_SystemsOS-1.2.0.iso ``` Compare the value shown in Terminal with the value inside `Sovran_SystemsOS-1.2.0.iso.sha256`.
Windows Open PowerShell in the download folder and run: ```powershell Get-FileHash .\Sovran_SystemsOS-1.2.0.iso -Algorithm SHA256 ``` Compare the value under `Hash` with the published checksum.
**If the values do not match, do not install.** Delete the downloaded ISO, download it again, and repeat the verification. Continue only after the values match exactly. ### 3. Write the ISO to a USB drive 1. Download and install [Balena Etcher](https://etcher.balena.io), then connect the USB drive. 2. Choose **Flash from file** and select `Sovran_SystemsOS-1.2.0.iso`. 3. Choose **Select target**, select the USB drive, and review your selection carefully. 4. Choose **Flash** and wait for the writing and verification process to finish. > **Warning:** Flashing erases the selected drive. Verify that you selected > the USB drive and not another storage device. After flashing, your computer may report that it cannot read the USB drive or may show several unfamiliar partitions. This is normal for a bootable Linux installer. Do not format the drive. ### 4. Boot from the USB drive 1. Leave the USB drive connected and restart the destination computer. 2. Open the computer's boot-device menu. Common keys include `F12`, `F11`, `F10`, `F9`, `Esc`, and `Delete`; the correct key is often shown briefly when the computer powers on. 3. Select the USB drive and start the Sovran_SystemsOS installer. If the normal operating system starts instead, restart and try the boot-menu key again. ### Installing in a virtual machine (optional) Sovran_SystemsOS can be tested in VirtualBox, VMware, QEMU/KVM, Proxmox, and similar x86_64 virtual machines. Use production-like resources where possible: - Allocate **8 GB RAM or more** for Desktop Only. Node and Server + Desktop should follow the normal 16 GB / 32 GB recommendations. - Create a **256 GB or larger virtual OS disk**. Thin-provisioned / dynamically allocated disks are fine; they do not consume the full size immediately. - Use NAT or bridged networking with internet access before opening the installer. - UEFI/EFI firmware is preferred: in UEFI VMs the installer avoids depending on VM NVRAM boot-entry writes, and a VM that boots the ISO in legacy BIOS mode automatically installs GRUB instead. - For Node or Server + Desktop, attach a **second 2 TB virtual data disk**. If you only attach one disk, choose **Desktop Only**. - Present the install target as a normal virtual disk such as VirtIO, SATA, SCSI, or NVMe. USB-attached disks are hidden by the installer so you cannot erase the installer USB by mistake. ### 5. Install Follow the on-screen installer. Before confirming: - Verify that you selected the correct destination 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, restart the computer, remove the USB drive when instructed, allow Sovran_SystemsOS to start from the installed drive, and complete the initial setup. ### 6. Open the Sovran Hub Open the Hub directly from the Sovran_SystemsOS desktop, or from any other device on the same local network at: ```text http://sovransystemsos.local:8937 ``` Sign in with your Sovran_SystemsOS credentials. Desktop does not publish the Hub on the network, so in that mode open it from the desktop.
If sovransystemsos.local:8937 does not open 1. Make sure the Sovran_SystemsOS machine is powered on, and allow it a few minutes to finish starting. 2. Make sure both devices are connected to the same local network, and that you entered the full address `http://sovransystemsos.local:8937`, including the `:8937`. 3. Avoid guest Wi-Fi networks, which may prevent devices from seeing one another. 4. Temporarily disconnect any VPN that may interfere with local-network access. 5. Try another browser or device on the same network.
### Prefer guided help? Not technical? You do not have to figure everything out alone. Visit the [Sovran Systems website](https://sovransystems.com) to learn about guided setup, supported hardware, and Royal Membership. --- ## For developers Sovran_SystemsOS combines [NixOS](https://nixos.org), the standalone [Sovran_Bitcoin](https://github.com/naturallaw777/Sovran_Bitcoin) flake for Bitcoin and Lightning, desktop packages from [btc-clients-nix](https://github.com/emmanuelrosa/btc-clients-nix), and the Sovran Hub. The Bitcoin and Lightning modules live in the Sovran_Bitcoin repository and are consumed as a flake input. OS-specific Bitcoin customizations (Second_Drive paths, operator user, Hub integration) are bridged by `modules/sovran-bitcoin-integration.nix`. Legacy `nix-bitcoin.*` option names and `/etc/nix-bitcoin-secrets` remain for compatibility. ### Development workflow | Branch | Host | Purpose | |---------------|---------------------------------------------------|-----------------------------| | `main` | [GitHub](https://github.com/naturallaw777/Sovran_SystemsOS) | Active development & PRs | | `staging-dev` | [Gitea](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS) | Synced with `main` | | `stable` | [Gitea](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable) | Tested, release-ready builds | **Flow:** develop → sync `main` ↔ `staging-dev` → promote to `stable` > ⚠️ `main` and `staging-dev` may contain unreleased or less-tested code. For > stable, audited code, use Gitea > [`stable`](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable). ### Technology - [NixOS](https://nixos.org) and [Nix flakes](https://nixos.wiki/wiki/Flakes) for declarative, pinned system configuration - [Sovran_Bitcoin](https://github.com/naturallaw777/Sovran_Bitcoin) for the Bitcoin and Lightning stack (consumed as a flake input) - `modules/sovran-bitcoin-integration.nix` for OS-specific Bitcoin overrides - [btc-clients-nix](https://github.com/emmanuelrosa/btc-clients-nix) for the Sparrow, Bisq, and Bisq 2 packages - [Python](https://www.python.org) and [FastAPI](https://fastapi.tiangolo.com) for the Sovran Hub backend - JavaScript, HTML, and CSS for the Hub interface - [GNOME](https://www.gnome.org) desktop environment - [Caddy](https://caddyserver.com) for local and public service routing - [Tor](https://www.torproject.org) for Bitcoin network privacy - [AGPL-3.0](LICENSE) licensing ### Build from source You need a system with Nix installed and flakes enabled. Clone the **stable** branch from Gitea (recommended for builds): ```bash git clone -b stable https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS.git cd Sovran_SystemsOS ``` Or clone the **active development** line from GitHub: ```bash git clone https://github.com/naturallaw777/Sovran_SystemsOS.git cd Sovran_SystemsOS ``` Then build the installer ISO: ```bash nix build \ .#nixosConfigurations.sovran_systemsos-iso.config.system.build.isoImage ``` The resulting build output will be available through the `result` symlink. ### Publishing a release Releases are managed with `scripts/release-stable.sh` and `scripts/upload-cdn.sh`: 1. Run the stable release script to bump version, tag, update changelog, and push/create releases: ```bash ./scripts/release-stable.sh [version] ``` 2. Build the installer ISO: ```bash nix build .#nixosConfigurations.sovran_systemsos-iso.config.system.build.isoImage ``` 3. Copy, checksum, verify, and optionally upload to CDN: ```bash ./scripts/upload-cdn.sh --upload ``` ### Common development commands Run these commands from the flake root. ```bash # Build the installer ISO nix build \ .#nixosConfigurations.sovran_systemsos-iso.config.system.build.isoImage # Build the system configuration nixos-rebuild build --flake .#nixos # Test without making the change permanent sudo nixos-rebuild test --flake .#nixos # Activate the new configuration sudo nixos-rebuild switch --flake .#nixos # Stage the configuration for the next boot sudo nixos-rebuild boot --flake .#nixos # Update pinned flake inputs (review and test before committing flake.lock) nix flake update # Roll back the last activated generation 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, self-hosted services, and optional features | | `modules/sovran-bitcoin-integration.nix` | OS-specific Bitcoin overrides (Second_Drive, operator, Hub wiring) | | `modules/core/` | Roles, Hub integration, Caddy, desktop, support, and other core behavior | | `app/` | Sovran Hub backend, templates, static assets, scripts, and web interface | | `scripts/` | Automated release, build, and CDN upload utility scripts | | `iso/` | Installer configuration, installer code, and installer assets | | `tests/` | Security and Nix integration checks | | `assets/` | Documentation images | | `custom.template.nix` | Template for local features and service overrides | On installed systems, `flake.nix` also imports `role-state.nix` (the selected mode), `custom.nix` (generated from `custom.template.nix`), and `hardware-configuration.nix`. These are generated per machine, so they are gitignored and not part of this repository. ### 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 | Area | Modules | |---|---| | Core platform: roles, Hub, desktop integration, Caddy, domains, support, remote deployment | `modules/core/` | | Shared credentials | `modules/credentials.nix` | | Bitcoin and Lightning stack | [Sovran_Bitcoin](https://github.com/naturallaw777/Sovran_Bitcoin) flake input + `modules/sovran-bitcoin-integration.nix` | | Automatic wallet-to-node connections | `modules/wallet-autoconnect.nix` | | Matrix Synapse | `modules/synapse.nix` | | Optional Element audio and video calling via LiveKit | `modules/element-calling.nix` | | Optional Haven Nostr relay | `modules/haven.nix` | | Nextcloud, Vaultwarden, WordPress | `modules/nextcloud.nix`, `modules/vaultwarden.nix`, `modules/wordpress.nix`, `modules/php.nix` | | Optional remote desktop and public SSH | `modules/rdp.nix`, `modules/sshd.nix` | Feature availability and defaults may change as Sovran_SystemsOS develops: review the relevant Nix module before relying on a default in production. --- ## About Bitcoin wallet entropy Wallet recovery words control the funds. Never share them with a website, support technician, cloud service, or chat application. For meaningful balances, prefer a well-reviewed hardware signer and follow its verified backup process. A BIP39 passphrase is optional, advanced protection, not a replacement for recovery words: back it up separately, because losing either item can make the wallet unrecoverable. Keep durable offline backups in separate secure locations, test recovery before relying on a wallet, and begin with a small amount. --- ## Security approach Sovran_SystemsOS uses layered controls: - Pinned flake inputs and hash-pinned source archives - Bitcoin and Lightning modules maintained in this repository - Firewall enabled; SSH Remote Access and remote desktop disabled by default. Enabling SSH opens TCP port 22 and the Hub then asks you to forward it - Separate service users, systemd sandboxing, and loopback bindings where practical - Tor enforcement for supported Bitcoin services - Restricted, time-limited support access with scoped `sudo` - Operator-controlled public service exposure (Server + Desktop [makes your home IP address public](#server--desktop-and-your-home-ip-address) once you set up a domain) See [`SECURITY.md`](SECURITY.md) for the threat model, limitations, reporting, and operator guidance. --- ## Acknowledgements Sovran_SystemsOS stands on the work of exceptional free and open-source projects and contributors. ### NixOS Gratitude to the [NixOS](https://nixos.org) team, the [Nixpkgs](https://github.com/NixOS/nixpkgs) maintainers, and the broader [Nix community](https://github.com/nix-community). NixOS provides the reproducible, declarative foundation that makes Sovran_SystemsOS possible: its module system, package ecosystem, [flakes](https://nixos.wiki/wiki/Flakes), and generation-based system management allow an entire Bitcoin operating system to be described, audited, rebuilt, upgraded, and rolled back from source. ### nix-bitcoin The in-repository Bitcoin stack began with code adapted from [nix-bitcoin](https://github.com/fort-nix/nix-bitcoin), primarily from commit [`360e30f`](https://github.com/fort-nix/nix-bitcoin/commit/360e30fee5ba32f9fecc89bc35628195d9d2dbbe). It has since been narrowed to Sovran's supported services and is maintained in this repository; nix-bitcoin is no longer a flake input or build dependency. Its MIT notice is retained in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md). ### Emmanuel Rosa and btc-clients-nix Thanks to [Emmanuel Rosa](https://github.com/emmanuelrosa) for [btc-clients-nix](https://github.com/emmanuelrosa/btc-clients-nix), which packages the Bitcoin desktop software included in every installation: - [Sparrow Wallet](https://github.com/sparrowwallet/sparrow) - [Bisq](https://github.com/bisq-network/bisq) - [Bisq 2](https://github.com/bisq-network/bisq2) ### The upstream Bitcoin ecosystem Sovran_SystemsOS also depends on the work of the developers and communities behind: - [Bitcoin Core](https://github.com/bitcoin/bitcoin) - [Sparrow Wallet](https://github.com/sparrowwallet/sparrow) - [Bisq](https://github.com/bisq-network/bisq) - [Bisq 2](https://github.com/bisq-network/bisq2) - [Electrs](https://github.com/romanz/electrs) - [LND](https://github.com/lightningnetwork/lnd) - [Ride The Lightning](https://github.com/Ride-The-Lightning/RTL) - [Alby Hub](https://github.com/getAlby/hub) for Nostr Wallet Connect (NWC) connections - [BTCPay Server](https://github.com/btcpayserver/btcpayserver) - [Tor](https://www.torproject.org) - [NixOS](https://github.com/NixOS/nixpkgs) - [GNOME](https://gitlab.gnome.org/GNOME) - [Caddy](https://github.com/caddyserver/caddy) - [Nextcloud](https://github.com/nextcloud/server) - [Matrix Synapse](https://github.com/element-hq/synapse) - [Element](https://github.com/element-hq/element-web) - [LiveKit](https://github.com/livekit/livekit) for Element audio and video calling - [Vaultwarden](https://github.com/dani-garcia/vaultwarden) - [WordPress](https://github.com/WordPress/WordPress) - Every other upstream project included in the system Sovran Systems did not create these foundations; our work is to bring them together into one operating system that helps more people use Bitcoin privately and independently. Thank you to every developer, maintainer, reviewer, tester, documentarian, and user who keeps this ecosystem alive. --- ## License Sovran_SystemsOS is free and open-source software licensed under the [GNU Affero General Public License v3.0](LICENSE). You may use, study, modify, share, and self-host it; 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 may have their own licenses and copyright holders, which the AGPL-3.0 does not replace. Read [`LICENSE`](LICENSE) and [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md). --- ## Contributing We welcome contributions! The [GitHub repository](https://github.com/naturallaw777/Sovran_SystemsOS) is the primary location for collaboration. Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting a pull request.
--- ## Privacy. Sovereignty. Bitcoin. [Visit Sovran Systems](https://sovransystems.com) · [Download Sovran_SystemsOS](https://downloads.sovransystems.com/Sovran_SystemsOS-1.2.0.iso) · [View the License](LICENSE)