Archipelago

Self-Sovereign Bitcoin Node OS

Archipelago is a bootable personal server OS. Flash it to a USB drive, install on any x86_64 or ARM64 machine, and manage Bitcoin infrastructure, self-hosted apps, and Web5 identity through a modern web interface.

Features

Bitcoin Infrastructure

• Bitcoin Knots full node with pruning support
• LND Lightning Network daemon with channel management
• Electrs Electrum server for wallet connectivity
• BTCPay Server for accepting Bitcoin payments
• Mempool block explorer and fee estimator
• Fedimint federation guardian and gateway

Self-Hosted Apps (20+)

Storage (File Browser, Immich, Nextcloud), Productivity (Penpot, OnlyOffice, Vaultwarden), Media (Jellyfin), Search (SearXNG), AI (Ollama), Network (Tailscale, Nginx Proxy Manager), Home (Home Assistant), and more.

Web5 Identity

• DID-based digital identity (Ed25519 + secp256k1)
• Verifiable Credentials issuance and verification
• Decentralized Web Node (DWN) for data sync
• Nostr relay integration for node discovery

Security

• AES-256-GCM encrypted secrets at rest
• Container isolation: read-only root, capability dropping, non-root user
• TOTP two-factor authentication
• Per-endpoint rate limiting and input validation
• AppArmor profiles for container confinement

Quick Start

Install from ISO

1. Download the ISO for your architecture (x86_64 or ARM64)
2. Flash to USB drive with Balena Etcher or dd
3. Boot from USB on target hardware
4. Follow the automated installer
5. Access the web UI at http://<device-ip>
6. Set your password and start the onboarding wizard

Supported Hardware

Platform	Examples	Minimum
x86_64	Intel NUC, mini PCs, any 64-bit PC	4GB RAM, 32GB storage
ARM64	Raspberry Pi 5, ARM64 SBCs	4GB RAM, 32GB storage

Recommended: 8GB+ RAM, 1TB+ NVMe SSD (for full Bitcoin node)

Development

Prerequisites

• Rust stable toolchain
• Node.js 20+
• Linux dev server (Debian 12) for backend builds

Frontend Development

cd neode-ui
npm install
npm start          # Dev server on http://localhost:8100
npm run type-check # TypeScript validation
npm test           # Run 515+ tests
npm run build      # Production build

Deploy to Server

./scripts/deploy-to-target.sh --live   # Deploy to dev server
./scripts/deploy-to-target.sh --both   # Deploy to both servers

Build ISO

ssh archipelago@<server>
cd ~/archy/image-recipe
sudo ./build-auto-installer-iso.sh     # x86_64
sudo ARCH=arm64 ./build-auto-installer-iso.sh  # ARM64

Architecture

Debian 12 (Bookworm)
  ├── Podman (rootless containers)
  ├── Nginx (reverse proxy + security headers)
  ├── Rust Backend (JSON-RPC API on port 5678)
  │     ├── core/archipelago/  — RPC endpoints, state, identity
  │     ├── core/container/    — Podman client, manifests, health
  │     └── core/security/     — AppArmor, secrets, image verification
  └── Vue 3 Frontend (Composition API + TypeScript + Pinia)

Documentation

• Architecture — System design
• Developer Guide — Contributing guide
• App Developer Guide — Writing app manifests
• App Manifest Spec — YAML manifest format
• User Guide — End-user documentation
• Release Notes — v1.0.0 release notes
• v1.1 Roadmap — Upcoming features
• v2.0 Roadmap — Long-term vision

Contributing

1. Fork the repository
2. Create a feature branch (feature/description)
3. Follow the coding standards in CLAUDE.md
4. Submit a pull request with tests

License

MIT License

Acknowledgments

Built with: Rust, Vue.js, Podman, Bitcoin Core, LND, Debian