archipelagoandClaude Opus 5
6c6e237646
An app whose container disappeared could be lost permanently. Desired-state recovery decided whether to recreate it from running-containers.json — "what was running at the last snapshot" — which is a different question and a perishable answer: it records only what is running NOW, so an app that stays down long enough simply ages out. Once out, boot's ExistingOnly mode will not recreate it, because it cannot tell "installed and lost" from "merely available in the catalog". Manifest still on disk, nothing to bring it back. This is the second occurrence of one root cause. indeedhub-minio/-postgres went permanently absent on one node (2026-08-06); the fix then was `absent_stack_member_with_live_sibling`, which only rescues a stack member that still has a living sibling. bitcoin-knots is standalone, so on archi-dev-box (2026-08-08) it vanished, aged out, and stayed gone — LND crash-looping on `lookup bitcoin-knots: no such host` for hours, electrumx unable to reach its daemon, and an orphaned fedimint container waiting 30 hours for a host that no longer resolved. Recovering it took a manual reinstall. This is the general fix the narrow one implied. Installation is a DECISION, not a runtime observation, so it gets a record that no amount of downtime erodes: installed-apps.json, written when an install succeeds and cleared on uninstall, in the same breath as mark_user_uninstalled — leaving a stale claim would let recovery recreate the app that was just removed. It is the durable counterpart to the user-uninstalled marker that already existed. Safety, in order of how badly each could go wrong: - Cannot resurrect a deliberate uninstall: user_uninstalled is checked earlier in ensure_running_with_mode and returns before anything is created, and uninstall clears this record too. - Cannot install an app nobody asked for: only names in the record qualify, and ExistingOnly's other guards are untouched. - Cannot mislead a node upgrading into the feature: backfill seeds from ADOPTED containers only — evidence that something is really there — skips anything user-uninstalled, is additive so a momentarily-down app is never dropped, and no-ops on an empty adoption list (podman unreachable must not read as "nothing is installed"). Four tests, including the one that states the point: the record must outlive a running-snapshot that has gone empty. Container suite 221/221, crash_recovery 15/15. 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.