eb6ec71a56
The dd61a204 bind hardening published Bitcoin RPC on the archy-net gateway 10.89.0.1 — but rootlessport binds in the HOST netns, where that address does not exist. First real deploy (.228, 2026-07-09) crash-looped bitcoin-knots AND bitcoin-core the moment the gate's stop→start regenerated the unit from the re-signed catalog: 'rootlessport listen tcp 10.89.0.1:8332: bind: cannot assign requested address', restart counter 132. Hand-edits to the unit don't survive — the orchestrator regenerates it from the signed catalog manifest within seconds. - New archipelago_container::manifest::host_can_bind_publish_ip(): empty/ wildcard/loopback accepted without probing, anything else ephemeral-bind probed. Applied at all three publish paths — quadlet from_manifest (PublishPort), podman API create (host_ip), and the legacy -p string table loop — each dropping the publish with a warn instead of taking the container down. This neutralizes the bad binds already in the SIGNED catalog, so nodes recover on binary deploy alone (no ceremony needed). - Remove the gateway publishes from bitcoin-knots/-core manifests and the legacy config.rs tables: verified on .228 that every in-node consumer (lnd, btcpay/nbxplorer, fedimint, mempool-api) dials the container's archy-net alias directly (bitcoin-knots:8332) and lnd uses RPC polling (no ZMQ) — the gateway publish had zero consumers. Loopback-only RPC/ZMQ (the approved LAN lockdown) stands; P2P 8333 stays public. Catalog still ships the gateway binds until the next signing ceremony regenerates it from these manifests; the guard makes that non-urgent. Tests: container crate 65/65 (2 new guard tests), quadlet 40/40. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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, mesh communication, and decentralized identity through a glassmorphism web UI.
Philosophy
Archipelago is being built as a developer-ready app platform, not a fixed appliance:
- Manifest-driven apps. Every app is declared in a single
manifest.yml— image, ports, volumes, secrets, health checks, security policy. The orchestrator owns the entire lifecycle; there is no per-app installer code and no host-level provisioning. - Signed distribution. App manifests ship inside an Ed25519-signed catalog verified against a pinned release-root key, not as loose files on disk. OTA release manifests are signed the same way.
- Decentralized marketplace. Third-party developers publish apps via Nostr-based discovery (NIP-78) with DID-signed manifests and federation-weighted trust scoring — no gatekept central store.
- Rootless and secure by default. Rootless Podman only. Read-only root, no-new-privileges, capability allow-list, secrets materialised 0600 and never logged. Never rootful, never a Docker socket mount.
- 100%-uptime-capable. Every container is a systemd Quadlet unit under
user.slicethat survives backend restarts; a level-triggered reconciler self-heals drift every 30 seconds; migrations never destroy data.
Features
Bitcoin Infrastructure
- Bitcoin Core and Bitcoin Knots full nodes with per-app version pinning and bulletproof version switching, automatic prune/full mode based on disk size
- LND and Core Lightning with channel management
- ElectrumX Electrum server for wallet connectivity
- BTCPay Server for accepting Bitcoin payments
- Mempool block explorer and fee estimator
- Fedimint federation guardian, gateway, and client — plus Cashu ecash wallet support
Self-Hosted Apps (50+)
Storage (FileBrowser, Immich, Nextcloud), Productivity (Vaultwarden), Media (Jellyfin, PhotoPrism, IndeeHub), Search (SearXNG), Network (NetBird, Tailscale), Home (Home Assistant), Nostr (nostr-rs-relay, strfry), Dev/Ops (Gitea, Grafana, Portainer, Uptime Kuma), and more — 27 curated in the store UI, 50+ packaged as manifests.
Mesh Networking (tri-protocol)
- Meshtastic, MeshCore, and Reticulum (RNS/LXMF) LoRa transports behind one mesh chat UI
- End-to-end encryption with X3DH key agreement + double-ratchet
- RNode radio support with an OS-level
archy-rnodeconftool; interop verified against Sideband - Image/voice attachments, mesh AI assistant (
!ai), Bitcoin balance relay over mesh
Decentralized Identity
- Ed25519 node identity with DID Documents (did:key)
- Multi-identity management (Personal/Business/Anonymous)
- W3C Verifiable Credentials issuance and verification
- Nostr integration: NIP-33 node discovery, NIP-44/NIP-04 encryption, NIP-07 signer bridge for iframe apps, relay hosting
- Decentralized Web Node (DWN) record sync between federated nodes over Tor
Multi-Node Federation
- Invite-based node joining over Tor hidden services
- Trust levels (Trusted/Verified/Untrusted) with DID-based auth
- State sync and app deployment across federated nodes
- File sharing with access controls (free/peers-only/paid via Lightning, on-chain, or ecash)
System Updates
- OTA updates from a self-hosted Gitea release server, Ed25519-signature-verified against a pinned release-root key
- Resumable downloads, automatic pre-update backup, rollback with a post-update self-verify window
- Manual, scheduled-check, and auto-apply modes (auto-apply refuses unsigned manifests)
Security
- Argon2id password hashing (transparent upgrade from legacy hashes), ChaCha20-Poly1305 encrypted secrets at rest
- Rootless Podman: read-only root, cap-drop ALL with a reviewed allow-list, no-new-privileges
- Signed release manifests and signed app catalog (Ed25519, pinned trust anchor)
- TOTP two-factor authentication, per-endpoint rate limiting, CSRF protection
- AppArmor profiles for container confinement; Tor hidden services for inter-node traffic
- Independent security audit of an early version archived in
docs/archive/; top findings since remediated
Roadmap
Done
- Single-node production gate green — install / stop / start / restart / reinstall / reboot-survive / uninstall, 5 consecutive full runs with zero failures on real hardware
- Quadlet migration validated (all backends as
user.sliceservices on the canary node) - Release signing ceremony completed — release-root key pinned, catalog and OTA manifests signed
- Reticulum third mesh transport (real-RF LoRa gates passed), Bitcoin Core/Knots multi-version switching, decentralized marketplace backend, public demo
In progress
- Multinode pass: the same production gate across the whole test fleet (
docs/multinode-testing-plan.md) - Quadlet default flip fleet-wide + container-flapping elimination
- 1.8.0 release hardening tail (
docs/1.8.0-RELEASE-HARDENING-PLAN.md): OTA upgrade soak on real hardware, ISO/image hardening (per-device keys, no default creds, signed ISO)
Planned
- Developer CLI (
archy app validate/render/install/test) to open third-party app publishing - External marketplace trust UX + publishing tooling (
docs/marketplace-protocol.md) - DHT/P2P distribution of releases and app images (
docs/dht-distribution-design.md) - P2P encrypted voice/video over Tor, dual-ecash (Fedimint + Cashu) phases, paid streaming, hardware signer support
The live, priority-ordered task list is docs/UNIFIED-TASK-TRACKER.md; the full narrative plan is docs/PRODUCTION-MASTER-PLAN.md.
Quick Start
Install from ISO
- Build or download the ISO for your architecture (x86_64 or ARM64) — see
image-recipe/ - Flash to USB drive with Balena Etcher or
dd - Boot from USB on target hardware and follow the automated installer
- Access the web UI at
http://<device-ip> - Set your password and complete the onboarding wizard (seed backup, DID identity)
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 a full Bitcoin node). Optional: an RNode-compatible LoRa radio for mesh networking.
Development
Prerequisites
- macOS or Linux for frontend development
- Linux dev server (Debian 13) for backend builds — never build Rust on macOS for Linux
- Node.js 20+, Rust stable toolchain
Frontend Development
cd neode-ui
npm install
npm start # Dev server on http://localhost:8100 (mock backend on :5959)
npm run type-check # TypeScript validation
npm run build # Production build → web/dist/neode-ui/
Backend Development
cd core # Rust workspace root (no Cargo.toml at repo root)
cargo build
cargo test
Deploy to a Test Node
./scripts/deploy-to-target.sh --live # Deploy to primary dev server
./scripts/deploy-to-target.sh --both # Deploy to both LAN servers
Release (tarball-only)
Releases ship as a backend binary and a frontend tarball referenced by
releases/manifest.json, published to the self-hosted Gitea release server.
./scripts/create-release.sh 1.2.3
git push origin main --tags
Architecture
Debian 13 (Trixie)
├── Rootless Podman — every app a systemd Quadlet unit under user.slice
├── Nginx (reverse proxy, security headers, rate limiting)
├── Rust Backend (JSON-RPC API on 127.0.0.1:5678, ~380 RPC methods)
│ ├── core/archipelago/ — API, orchestrator + reconciler, mesh, identity,
│ │ federation, wallet, updates, marketplace
│ ├── core/container/ — Podman client, manifest schema, Quadlet compiler,
│ │ health monitor, signed app catalog
│ ├── core/security/ — AppArmor/seccomp policy, secrets manager
│ ├── core/openwrt/ — TollGate gateway provisioning (SSH/UCI)
│ └── core/performance/ — resource limits
├── Vue 3 Frontend (Composition API + TypeScript strict + Pinia + Tailwind, PWA)
│ └── Three UI modes (Pro/Easy/Chat) + gamepad navigation + i18n
├── Reticulum daemon (supervised Python/PyInstaller, one per LoRa radio)
└── System Tor (hidden services, SOCKS5 proxy)
~117,000 lines of Rust | ~69,000 lines of TypeScript/Vue | 51 packaged apps | Android companion app
Documentation
| Doc | Purpose |
|---|---|
| Architecture | System design, crate map, data paths |
| Developer Guide | Dev setup, workflow, code conventions |
| API Reference | RPC endpoint reference |
| App Developer Guide | Building and publishing apps |
| App Manifest Spec | The manifest.yml schema |
| User Walkthrough | End-user installation and usage guide |
| Troubleshooting | Diagnostic scenarios and solutions |
| Operations Runbook | Ops commands and emergency recovery |
| Production Master Plan | North star and workstream narrative |
| Unified Task Tracker | Live, priority-ordered open items |
| Test Gate | Production lifecycle test gate (definition of done) |
| Archive | Historical audits, session logs, shipped designs |
Contributing
- Fork the repository
- Create a feature branch (
feature/description) - Follow the coding standards in CONTRIBUTING.md and CLAUDE.md
- Submit a pull request
License
Acknowledgments
Built with: Rust, Vue.js, Podman, Bitcoin Core, LND, Reticulum, Debian