# 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. [![Debian 13](https://img.shields.io/badge/Debian-13%20Trixie-a80030)](https://www.debian.org/) [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Rust](https://img.shields.io/badge/rust-stable-orange)](https://www.rust-lang.org/) [![Vue.js](https://img.shields.io/badge/vue.js-3.5-brightgreen)](https://vuejs.org/) [![Releases](https://img.shields.io/badge/releases-pre--release-blue)](https://source.archipelago-foundation.org/lfg2025/archy/releases) ## Current release As checked on 2026-11-12, the latest published application update is [v2.1.0-beta.2](https://source.archipelago-foundation.org/lfg2025/archy/releases/tag/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](https://source.archipelago-foundation.org/lfg2025/archy/releases/tag/v1.9.0-alpha). The later v1.9.1-alpha RC1 ISO is explicitly marked unqualified in its release notes. Check the [releases page](https://source.archipelago-foundation.org/lfg2025/archy/releases) 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](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](https://source.archipelago-foundation.org/lfg2025/archy/releases/download/v1.9.0-alpha/archipelago-installer-1.9.0-alpha-unbundled-x86_64.iso). - [SHA-256 checksum](https://source.archipelago-foundation.org/lfg2025/archy/releases/download/v1.9.0-alpha/archipelago-installer-1.9.0-alpha-unbundled-x86_64.iso.sha256). - [Signed checksum JSON](https://source.archipelago-foundation.org/lfg2025/archy/releases/download/v1.9.0-alpha/archipelago-installer-1.9.0-alpha-unbundled-x86_64.iso.sha256.json). 2. **Verify the download.** Save the ISO and `.sha256` file together, then on Linux run: ```bash 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](https://etcher.balena.io/) 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://` 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](docs/user-walkthrough.md) 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//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//`. - 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](docs/architecture.md) - [Developer Guide](docs/developer-guide.md) - [App Developer Guide](docs/app-developer-guide.md) - [App Manifest Spec](docs/app-manifest-spec.md) - [Nostr Git Source Hosting Plan](docs/nostr-git-source-hosting.md) - [Troubleshooting](docs/troubleshooting.md) ## Quick start ### Frontend ```bash cd neode-ui npm ci npm start ``` The dev UI runs at `http://localhost:8100` with a mock backend on `:5959`. ### Backend ```bash 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](docs/developer-guide.md); `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 ```bash ./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](docs/README.md) for a task-based map. 3. [Working rules](AGENTS.md) and [contribution guide](CONTRIBUTING.md) for safe checks and the canonical ngit workflow. 4. [Developer guide](docs/developer-guide.md) for local setup and the source map. 5. [OS architecture](docs/architecture.md) and its [visual HTML guide](docs/architecture.html) for system layers, trust and update boundaries. 6. [Release & Testing](Release%20%26%20Testing/README.md) 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](docs/api-reference.md) · [container lifecycle](docs/container-lifecycle.md) | | App packaging | [App developer guide](docs/app-developer-guide.md) · [manifest spec](docs/app-manifest-spec.md) · [Quadlet compilation](docs/quadlet-compilation.md) · [secrets](docs/secrets.md) · [catalog distribution](docs/registry-manifest-design.md) · [packaged apps](apps/README.md) | | Installer and OS updates | [Image recipe](image-recipe/README.md) · [OS updates](docs/os-updates.md) · [protected updater contract](docs/OS-OTA-CONTRACT-20261103.md) | | Network and security | [Nostr Git workflow](docs/nostr-git-source-hosting.md) · [multi-node architecture](docs/multi-node-architecture.md) · [external access and websites](docs/external-access-and-websites.md) · [security policy](SECURITY.md) | The [roadmap](docs/ROADMAP.md) describes direction. The [documentation index](docs/README.md) links to dated designs and historical evidence when you need them; those records do not replace current acceptance. ## Contributing Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. For security issues, follow [SECURITY.md](SECURITY.md) and do not open a public issue. ## License Archipelago is licensed under the [MIT License](LICENSE). Third-party notices are listed in [NOTICE](NOTICE) and generated license inventories in component release artifacts.