archipelagoandClaude Opus 5
ec0cfd1b7d
Caught on archi-dev-box within minutes of deploying3ac59a73: the reaper removed archy-bitcoin-ui and archy-lnd-ui, whose backends ARE installed. archy-bitcoin-ui was gone for 36 minutes, until the operator reinstalled bitcoin-knots and `reconcile` put the companion back. Not a logic error — the arithmetic did what it was told. The inputs were false. Both backends' containers were missing because of the clean-exit vanishing bug (8908fb4f), and both had already aged out of running-containers.json, which only ever records what is CURRENTLY RUNNING. So the two signals `installed_app_ids` combines are not independent: one root cause falsifies both simultaneously. ORPHAN_GRACE could not help either — the condition was persistent, not transient, which is exactly the case the grace period cannot distinguish. The asymmetry decides it. An un-reaped orphan costs a stale UI tile. A wrongly-reaped companion costs a working screen and turns one lost app into two — the reaper amplifies the very failure it was meant to tidy up after. `reap_orphans` and its tests stay, documented as NOT TO BE WIRED until a durable record of "this app is installed" exists to drive it. Inferring installation from runtime state cannot answer that question, however many runtime signals are combined. The provisioning half is untouched and is the actual fix for "fedimint installs but does not work": driving `reconcile` from installed_app_ids means a companion is never stood up for an app nobody installed, so no NEW orphans appear. The one genuine orphan on this node (archy-fedimint-ui, for an app never installed) was correctly removed before this change landed. Unit tests passed the reaper because they verify the set arithmetic, not whether the "installed" signal is truthful. Only the device could show that. Container suite 221/221. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.rsis 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.