archy/README.md

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.

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

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.