archipelagoandClaude Fable 5
e1a3f31a0a
Demo images / Build & push demo images (push) Successful in 3m32s
User-reported checkpoint regression: on a genuinely first visit to Cloud this session, no folder opened on click (subsequent visits fine). Root-caused on archi-dev-box, not guessed: - The click DID register (confirmed via a direct DOM listener) and DID call router.push (confirmed by patching the live router instance) — but the push's promise never settled, because Vue Router awaits the target route's async component, and that dynamic import() itself never resolved. - Confirmed via a manual import() from the page console: importing ANY lazy route chunk (Fleet, CloudFolder, AppDetails — unrelated views) hangs identically after visiting Cloud once, but works instantly before ever visiting Cloud. Not chunk-specific, not router-specific. - Traced to exactly one permanently-pending network request: a File Browser `GET /app/filebrowser/api/resources/Photos` call from Cloud's own onMounted burst, confirmed hung via request-lifecycle tracking (never finishes or fails, still pending after 10s). The identical request, issued manually with a fresh token outside of Cloud.vue, returns in 29ms — ruling out the backend/File Browser itself. - Mechanism: Cloud.vue's syncOnEntry() (loadCounts/loadPeers/ loadPeerFiles) fires from BOTH onMounted and onActivated with no fresh-mount guard (02-04 exempted it, reasoning each resource is individually staleness/inflight-deduped — true per-resource, but the two back-to-back passes still double the concurrent request volume at the single riskiest instant in a session: first KeepAlive activation, stacked on whatever other cached view's own onMounted burst is firing at the same moment). On real hardware that volume was enough to leave one File Browser request stuck, which then starves Chromium's per-origin connection pool — breaking every subsequent same-origin fetch, including the lazy chunk any later navigation needs. Not a router or click-handler bug; the click and push both worked correctly the whole time. Fix: give Cloud.vue the same fresh-mount guard already used in Home.vue/Web5.vue/Mesh.vue/Server.vue (skip onActivated's redundant first-activation re-fire since onMounted just ran it). Removes the duplicate-burst mechanism without changing steady-state reactivation — onActivated still re-syncs normally on every later KeepAlive round-trip. No visual/behavioral change (D-01 rule). Full test suite green (95 files / 774 tests), type-check and build clean. Co-Authored-By: Claude Fable 5 <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
- Operations Runbook
- 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 |
| Operations Runbook | Production operations and recovery |
| Open Source Readiness | Public-release cleanup checklist |
| Roadmap | Shipped, in-progress, and planned work |
| Unified Task Tracker | Launch hardening task list |
| 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.