Archipelago

Alpha testing — funds at your own risk. Archipelago is experimental software and is not production-ready. Any funds you put on it are at your own risk. Substantial security hardening is planned before production readiness; current builds are for testing and feedback.

Self-sovereign Bitcoin node OS and manifest-driven app platform.

Archipelago is a bootable personal server OS for Bitcoin infrastructure, self-hosted apps, mesh communication, decentralized identity, and federation. Apps are packaged as declarative manifest.yml files and run as rootless Podman containers managed by the Rust backend.

Current release

As checked on 2026-11-12, the latest published application update is v2.1.0-beta.2. It has signed OTA assets but no installer ISO. The latest publicly qualified x86_64 installer remains v1.9.0-alpha. The later v1.9.1-alpha RC1 ISO is explicitly marked unqualified in its release notes. Check the releases page for a newer qualified installer or update before using these versions. Source on main, published artifacts, and installed-node acceptance are separate.

ngit is the canonical source contribution and review platform. Gitea mirrors accepted source and hosts release downloads. For Nostr-native cloning:

nostr://npub1w3sqdkrhn0gyuvsex32effzgnfpyde6qrrc4u467flg5e9txh4wsfn5vjg/relay.ngit.dev/archy

Clone with ngit, or use the Gitea mirror when you need a conventional Git remote. Contributions should follow CONTRIBUTING.md.

Install on a server

Use a dedicated x86_64 Intel/AMD server, mini PC, or PC, an SSD, and an 8 GB or larger USB drive. For Bitcoin and multiple apps, 8 GB or more RAM and a generously sized SSD are recommended; an unpruned Bitcoin node needs room for the growing blockchain. Connect Ethernet and a monitor/keyboard, or use your server's remote console and virtual installation media.

1. Choose a qualified installer from the releases page and download its checksum alongside it. At the 2026-11-12 check, that means:

   • Archipelago 1.9.0-alpha ISO.
   • SHA-256 checksum.
   • Signed checksum JSON.

2. Verify the download. Save the ISO and .sha256 file together, then on Linux run:

   sha256sum --check archipelago-installer-1.9.0-alpha-unbundled-x86_64.iso.sha256
   

   The result must be OK. This checks file integrity; the signed JSON is provided separately for release-signature verification.

3. Write the ISO to USB using Balena Etcher or your preferred image writer. Write the image rather than copying the ISO into the USB filesystem. For a remotely managed server, attach the ISO as virtual installation media instead. This is a raw .iso; no decompression is needed.

4. Boot the server from that media and follow the console installation prompts. Verify Secure Boot compatibility for the selected image and firmware; later image-recipe work does not change previously published ISOs. Installation erases the selected target disk, so back up its contents and check the disk selection carefully.

5. Remove/eject the installation media and boot from the installed disk. Find the server's address in your router's DHCP client list or local console, then open http://<server-ip> from another device on the same network.

6. Complete first-run setup: create your dashboard password and follow the onboarding wizard to choose apps and Bitcoin storage settings. The unbundled ISO downloads app images as needed, so allow internet access for app setup.

For an existing Archipelago server, use the dashboard's Settings update flow for a published OTA rather than reinstalling. See the user walkthrough for onboarding and daily use.

This remains alpha software: funds are at your own risk, and production security hardening is still ahead.

What is here

• core/ - Rust workspace: backend API, container runtime, security, OpenWrt helpers, and performance/resource management.
• neode-ui/ - Vue 3 + TypeScript frontend.
• apps/ - app manifests and custom app container sources.
• docker/ - supporting container build contexts for UI companion surfaces.
• image-recipe/ - bootable image/ISO build inputs.
• Android/ - Android companion app.
• scripts/ - development, release, deployment, and validation tooling.
• docs/ - architecture, app packaging, operations, API, and roadmap docs.

Platform model

Archipelago is built as a developer-ready app platform, not a fixed appliance:

• Apps are declared in apps/<app-id>/manifest.yml.
• The Rust parser in core/container/src/manifest.rs is the canonical schema.
• The orchestrator compiles manifests to rootless Podman/Quadlet runtime state.
• App data lives under /var/lib/archipelago/<app-id>/.
• Secrets are generated or read from /var/lib/archipelago/secrets/ and injected through Podman secrets rather than static environment values.
• Release and app catalogs are signed and verified against a pinned trust anchor.

Start with:

• Architecture
• Developer Guide
• App Developer Guide
• App Manifest Spec
• Nostr Git Source Hosting Plan
• Troubleshooting

Quick start

Frontend

cd neode-ui
npm ci
npm start

The dev UI runs at http://localhost:8100 with a mock backend on :5959.

Backend

cd core
cargo check --locked

On a machine with installed apps, run backend tests only through scripts/test-backend-isolated.sh from the repository root. See the developer guide; cargo test --no-run compiles but does not execute tests.

Linux is the supported backend runtime and release-build target. macOS is fine for frontend work and many Rust compile/test loops, but host integration tests that touch Podman, systemd, networking, or image build paths require Linux.

App manifests

./scripts/validate-app-manifest.sh apps/filebrowser/manifest.yml
python3 scripts/generate-app-catalog.py
python3 scripts/check-app-catalog-drift.py --release --strict

scripts/generate-app-catalog.py requires Python with PyYAML installed.

New Developer Reading List

Start here, in order:

1. This README for the product, source tree and published release distinction.
2. Documentation index for a task-based map.
3. Working rules and contribution guide for safe checks and the canonical ngit workflow.
4. Developer guide for local setup and the source map.
5. OS architecture and its visual HTML guide for system layers, trust and update boundaries.
6. Release & Testing for current scope and the evidence required before calling a build accepted.

Then read the documents for the area you are changing:

Area	Guides
Backend and API	API reference · container lifecycle
App packaging	App developer guide · manifest spec · Quadlet compilation · secrets · catalog distribution · packaged apps
Installer and OS updates	Image recipe · OS updates · protected updater contract
Network and security	Nostr Git workflow · multi-node architecture · external access and websites · security policy

The roadmap describes direction. The documentation index links to dated designs and historical evidence when you need them; those records do not replace current acceptance.

Contributing

Read CONTRIBUTING.md before opening a pull request. For security issues, follow SECURITY.md and do not open a public issue.

License

Archipelago is licensed under the MIT License. Third-party notices are listed in NOTICE and generated license inventories in component release artifacts.