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

The latest published pre-release is v1.9.0-alpha. Download the x86_64 server installer ISO or read the release notes and known limitations. Newer changes on main and private UAT deployments are not included in that published ISO. Check the releases page for subsequent published installers and signed OTA artifacts.

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. Download the installer and checksum:

   • Archipelago 1.9.0-alpha ISO (approximately 2.7 GB).
   • 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. Disable Secure Boot for this installer and follow the console installation prompts. 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 install
npm start

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

Backend

cd core
cargo build
cargo test --all-features

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.

Documentation map

The full, grouped index lives at docs/README.md. The most common entry points:

Doc	Purpose
Architecture	System layers, crates, data paths, security model
Developer Guide	Local setup, code workflow, testing
API Reference	JSON-RPC API overview
App Developer Guide	How to package and test apps
App Manifest Spec	Manifest schema and validation rules
Nostr Git Source Hosting Plan	ngit/NIP-34 contribution workflow and maintainer model
Apps README	Packaged app catalog overview
Image Recipe	Bootable image build flow
Roadmap	Shipped, in-progress, and planned work
Archive	Historical plans, audits, and handoffs

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.