Archipelago

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 current pre-release is v1.8.13-alpha. Release notes and signed OTA artifacts are published on Gitea. The same source is mirrored through ngit for Nostr-native cloning and contribution:

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.

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.