diff --git a/README.md b/README.md index 3c3d17e..0c8af26 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,17 @@ ### Your Bitcoin life. Your keys. Your node. Your machine. -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. +Sovran_SystemsOS is a free and open-source operating system for **Bitcoin +self-custody** and **digital sovereignty**. Hold your own keys, trade +peer-to-peer, and verify your own money with your own node. Then extend the +same ownership to the rest of your digital life: your files, communications, +passwords, and websites, all on hardware you control. -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. +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 and +Lightning infrastructure when you are ready. **Privacy. Sovereignty. Bitcoin.** @@ -23,10 +25,6 @@ ready. [Verify the Download](https://downloads.sovransystems.com/Sovran_SystemsOS.iso.sha256) · [Build from Source](#build-from-source) - - -
- Sovran_SystemsOS private Bitcoin desktop *Bitcoin sovereignty from the first boot.* @@ -35,27 +33,64 @@ ready. --- -## Bitcoin software should help you leave the middleman behind +## Contents -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. +- [Why Sovran_SystemsOS?](#why-sovran_systemsos) +- [What is included](#what-is-included) +- [Three modes](#three-modes) +- [Use it your way](#use-it-your-way) +- [The Sovran Hub](#the-sovran-hub) +- [Install Sovran_SystemsOS](#install-sovran_systemsos) +- [For developers](#for-developers) +- [Security approach](#security-approach) +- [Acknowledgements](#acknowledgements) +- [License](#license) · [Contributing](#contributing) -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.** +## 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 + Knots](https://bitcoinknots.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. 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. +wallet what happened on the network. No third-party cloud needs to control +your data or services. + +Other projects solve one piece of this puzzle: a Linux distribution that can +run a wallet, a node project that runs Bitcoin services, a self-hosting stack +that replaces a cloud app. Sovran_SystemsOS brings those worlds together and +makes them approachable: Bitcoin tools from the first boot, a complete path +from desktop to node to self-hosting, one control center, hardware you own, +and a reproducible, auditable NixOS foundation. > Sovran_SystemsOS provides tools for self-custody and peer-to-peer Bitcoin > use. Users remain responsible for protecting their keys, understanding their @@ -63,196 +98,117 @@ control your data or services. --- -## Bitcoin tools included from day one +## What is included -You do not need the largest computer or a fully synchronized Bitcoin node to -begin taking control of your Bitcoin. +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. -Every Sovran_SystemsOS mode includes the standard desktop Bitcoin applications: -**Sparrow Wallet, Bisq, and Bisq 2**. +### Your money — Bitcoin sovereignty -### Sparrow Wallet +- Bitcoin Knots, Electrs, and Tor integration +- LND and Ride The Lightning, with [Alby Hub](https://albyhub.com) for Nostr + Wallet Connect +- 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, or Bitcoin Core in place of Knots -Sparrow is a privacy-focused desktop Bitcoin wallet built for transparent, -secure self-custody. +Run your own Bitcoin infrastructure. Verify your own money. Trust no one. -Use Sparrow to: +### Your voice — private communications -- 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 +- The [Synapse](https://github.com/element-hq/synapse) homeserver (Matrix) and + the [Element](https://element.io) client +- Optional Matrix-native calling +- Optional [Haven](https://github.com/bitvora/haven) + [Nostr](https://github.com/nostr-protocol/nostr) relay -Your keys remain under your control. +Communicate without making Big Tech the owner of your identity or +conversations. -### Bisq +### Your cloud — self-hosting and storage -Bisq is a decentralized peer-to-peer Bitcoin exchange. +- Nextcloud files, calendars, and contacts +- Vaultwarden password vault +- WordPress websites +- [Caddy](https://caddyserver.com) with private service domains +- Optional remote desktop -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. +Keep your files, passwords, calendar, contacts, website, and services on +hardware you control. -### Bisq 2 +### Your desktop -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. +- [GNOME](https://www.gnome.org) desktop +- [Brave](https://brave.com) and + [Firefox](https://www.mozilla.org/firefox) browsers +- File management, email, calendar, and office applications +- System monitoring and administration tools --- -## Three modes, one path toward Bitcoin sovereignty +## Three modes -Every mode includes the same private NixOS and GNOME foundation, the Sovran -Hub, Sparrow Wallet, Bisq, and Bisq 2. +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. -What changes is how much Bitcoin and self-hosting infrastructure runs on the -machine. - -| Mode | Best for | Bitcoin capability | +| 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 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 | +| **Node** | People ready to verify and operate their own Bitcoin infrastructure | Everything in Desktop, plus the full Bitcoin stack: Bitcoin Knots, Electrs, LND, Ride The Lightning, BTCPay Server, and wallet-to-node connections | +| **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 | -### Desktop — start with your keys - -Desktop mode is not a reduced or Bitcoin-free edition. - -It is a private everyday computer that includes: - -- Sparrow Wallet -- Bisq -- Bisq 2 -- A clean GNOME desktop -- Privacy-respecting everyday applications -- Tor -- The Sovran Hub - -This gives people a lower-hardware path to Bitcoin self-custody and -peer-to-peer, non-KYC Bitcoin tools from the first boot. - -You can begin with Desktop today and move to your own node when your hardware, +**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, giving you a lower-hardware path to +self-custody and non-KYC Bitcoin tools from the first boot. You do not need a +fully synchronized node to begin; move to Node mode when your hardware, storage, and needs are ready. -**Recommended hardware:** +**Node: verify your own money.** Instead of asking someone else's server +about your wallet and transactions, you operate the infrastructure that +performs the verification. Your node verifies. Your wallet connects to it. +Your keys remain yours. -- 64-bit Intel or AMD processor, approximately 2015 or newer -- 8 GB RAM -- 256 GB SSD -- Any broadband connection +**Server + Desktop: sovereignty beyond money.** Bitcoin sovereignty is the +foundation. Server + Desktop applies the same principle to your data, +communications, identity, and services. -### Node — verify your own money +### Recommended hardware -Node mode includes the private desktop and adds the full Bitcoin stack. - -Instead of asking someone else's server about your wallet and transactions, -you operate the infrastructure that performs the verification. - -The Node stack includes: - -- **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 - -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 +| | **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 | --- -## Use Sovran_SystemsOS your way +## Use it 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 +### 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. +GNOME desktop as your daily operating system, with the Bitcoin software and +the tools of your selected mode already in place. -You receive a private desktop, the Sovran Hub, everyday applications, Bitcoin -software, and the tools included with your selected mode. +### As a private Bitcoin and home server -### 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, with or without a monitor. From any other device on the same network, +open a browser, visit `http://sovransystemsos.local`, and manage everything +from [The Sovran Hub](#the-sovran-hub). -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 -``` - -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. +Your existing devices stay familiar. Sovran_SystemsOS provides the independent +infrastructure behind them. --- @@ -262,29 +218,16 @@ independent infrastructure behind them. 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 -``` +Sovran_SystemsOS machine. Nothing needs to be installed on the device opening +the Hub: you only need a modern browser and access to the same local network. 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. +- Open, monitor, start, and stop your services +- See what is running and configure system features +- Manage service domains and credentials +- Reach your Bitcoin tools, private cloud, and communications +- Perform supported system operations without everyday terminal commands ### Example home setup @@ -316,199 +259,71 @@ modern browser and access to the same local network. 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. +> **Local access:** the Hub is available at +> `http://sovransystemsos.local` to devices connected to the same local +> network. It is protected by authentication and is not automatically exposed +> to the public internet. --- -## 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 +## Install Sovran_SystemsOS 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? +verify it, write it to a USB drive, and install it yourself, staying in +control from the very first step. An ISO is a complete installation image containing the operating system and -the files required to boot the Sovran_SystemsOS installer. +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). -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. +**Before you begin, you will need:** -## What you need - -Before beginning, you will need: - -- A compatible 64-bit computer +- 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 -- 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. ---- +### 1. Download the ISO and checksum -## Step 1: Download the ISO +- [Download Sovran_SystemsOS.iso](https://downloads.sovransystems.com/Sovran_SystemsOS.iso) +- [Download Sovran_SystemsOS.iso.sha256](https://downloads.sovransystems.com/Sovran_SystemsOS.iso.sha256) -Download the Sovran_SystemsOS installer: +The download may take some time. Do not rename or modify the ISO before +verifying it, and keep both files in the same folder. -### [Download Sovran_SystemsOS.iso](https://downloads.sovransystems.com/Sovran_SystemsOS.iso) +### 2. Verify the checksum -Depending on your browser and internet connection, the download may take some -time. Do not rename or modify the file before verifying it. +A checksum is a digital fingerprint of a file. Verifying it confirms that the +ISO downloaded completely, was not accidentally corrupted, and matches the +published image. The checksum produced from your ISO must match the published +checksum exactly. -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 +
+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: +A successful comparison reports: ```text Sovran_SystemsOS.iso: OK ``` -### macOS +You can also run `sha256sum Sovran_SystemsOS.iso` and compare the output +against the checksum file manually. + +
+ +
+macOS Open Terminal in the download folder and run: @@ -516,13 +331,13 @@ Open Terminal in the download folder and run: shasum -a 256 Sovran_SystemsOS.iso ``` -Compare the value shown in Terminal with the value inside: +Compare the value shown in Terminal with the value inside +`Sovran_SystemsOS.iso.sha256`. -```text -Sovran_SystemsOS.iso.sha256 -``` +
-### Windows PowerShell +
+Windows Open PowerShell in the download folder and run: @@ -532,251 +347,161 @@ 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. +**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. -1. Delete the downloaded ISO. -2. Download it again. -3. Repeat the verification. -4. 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.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. -## Step 4: Write the ISO to a USB drive +> **Warning:** Flashing erases the selected drive. Verify that you selected +> the USB drive and not another storage device. -Balena Etcher is available for Linux, macOS, and Windows. +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. -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. +### 4. Boot from the USB drive -> **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. +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. ---- +### 5. Install -## Step 6: Install Sovran_SystemsOS - -Follow the on-screen installer. - -Before confirming the installation: +Follow the on-screen installer. Before confirming: - 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: +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. -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. +### 6. Open the Sovran Hub ---- - -## 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: +Open the Hub directly from the Sovran_SystemsOS desktop, or from any other +device on the same local network at: ```text http://sovransystemsos.local ``` -Sign in using your Sovran_SystemsOS credentials. +Sign in with 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 -### 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. +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`. +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. 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 +### Prefer guided help? -### 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) +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 +## 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. +Sovran_SystemsOS combines the reproducibility of [NixOS](https://nixos.org), +the Bitcoin service modules of +[nix-bitcoin](https://github.com/fort-nix/nix-bitcoin), the desktop Bitcoin +packages provided by +[btc-clients-nix](https://github.com/emmanuelrosa/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 all maintained in this repository. -The operating system configuration, installer, Hub, desktop integration, -Bitcoin services, and optional self-hosting services are maintained in this -repository. +### Technology -## Technology +- [NixOS](https://nixos.org) and [Nix flakes](https://nixos.wiki/wiki/Flakes) + for reproducible system configuration +- [nix-bitcoin](https://github.com/fort-nix/nix-bitcoin) for declarative + Bitcoin and Lightning services +- [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 -- **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 +### Build from source 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 -``` +git clone https://github.com/naturallaw777/Sovran_SystemsOS.git +cd Sovran_SystemsOS -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 +### Common development commands Run these commands from the flake root. -### Build the installer - ```bash +# Build the installer ISO nix build \ .#nixosConfigurations.sovran_systemsos-iso.config.system.build.isoImage -``` -### Build the system configuration - -```bash +# Build the system configuration nixos-rebuild build --flake .#nixos -``` -### Test without making the change permanent - -```bash +# Test without making the change permanent sudo nixos-rebuild test --flake .#nixos -``` -### Activate the new configuration - -```bash +# Activate the new configuration sudo nixos-rebuild switch --flake .#nixos -``` -### Stage the configuration for the next boot - -```bash +# Stage the configuration for the next boot sudo nixos-rebuild boot --flake .#nixos -``` -### Update pinned flake inputs - -```bash +# Update pinned flake inputs (review and test before committing flake.lock) nix flake update -``` -Review and test input updates before committing the modified `flake.lock`. - -### Roll back the last activated generation - -```bash +# Roll back the last activated generation sudo nixos-rebuild switch --rollback ``` ---- - -## Repository map +### Repository map | Path | Purpose | |---|---| @@ -786,15 +511,17 @@ sudo nixos-rebuild switch --rollback | `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 | -| `docs/wallet-connections.md` | Lightning Wallet Connections architecture, API, CLI, and security/operations notes | | `iso/` | Installer configuration, installer code, and installer assets | -| `assets/` | Repository documentation images | +| `packages/` | Custom package sources and patches (for example, Alby Hub) | +| `assets/` | Documentation images | | `custom.template.nix` | Template for local features and service overrides | -| `role-state.nix` | Selected Sovran_SystemsOS mode or role | ---- +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 +### Architecture overview Sovran_SystemsOS is assembled from a reproducible Nix flake. @@ -834,59 +561,22 @@ Sovran_SystemsOS is assembled from a reproducible Nix flake. The Hub writes supported user choices into the local configuration. NixOS then rebuilds the machine into the selected declarative state. ---- +### Module overview -## 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 +| Area | Modules | +|---|---| +| Core platform: roles, Hub, desktop integration, Caddy, domains, support, remote deployment | `modules/core/` | +| Shared credentials | `modules/credentials.nix` | +| Bitcoin and Lightning stack | `modules/bitcoinecosystem.nix` | +| Automatic wallet-to-node connections | `modules/wallet-autoconnect.nix` | +| Optional Bitcoin Core in place of Knots | `modules/bitcoin-core.nix` | +| Alby Hub and Nostr Wallet Connect on LND | `modules/nwc-wallets.nix`, `packages/albyhub/` | +| Matrix Synapse | `modules/synapse.nix` | +| Optional Matrix calling | `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 Mempool explorer | `modules/mempool.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 specific default in a @@ -1027,8 +717,6 @@ We welcome contributions! Please read our [Contributing Guidelines](CONTRIBUTING ## 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)