archipelagoandClaude Opus 5
7adc3260a6
Narrative pass over the manifest spec, plus one correction to the guide I committed inba052736. - **`app.id` allowed `_`.** `is_valid_app_id` accepts lowercase ASCII letters, digits and single hyphens only — no underscores, no leading/trailing hyphen, no `--`. The spec's "alphanumeric + `-`/`_`" would have a developer write an id that fails to parse. - **"Must match the directory name"** is a convention, not a rule. The loader (`prod_orchestrator.rs:1455-1474`) walks `*/manifest.yml` and keys off `app.id`, never comparing it to the folder, so a mismatch silently registers the app under a different id. Said so rather than implying enforcement. - **The Quadlet claim was the same one architecture.md was corrected for** (f55ed6bf): install does NOT compile to a `user.slice` Quadlet unit today. `config.use_quadlet_backends` defaults false, so apps take the legacy `podman create + start` path; Quadlet is opt-in per node and companion UIs are the exception that already use it. - **"no per-app installer code"** — true of installers, but `run_pre_start_hooks` is a hardcoded `match app_id` covering seven first-party apps (bitcoin-ui, filebrowser, lnd, archy-nbxplorer, btcpay-server, fedimint-clientd, grafana). Documented as the caveat it is; anyone reading the source will find it in a minute and the doc should not look like it's hiding it. - `derived_env` now names the full closed allow-list including `{{BITCOIN_HOST}}` and what it resolves to. Correction toba052736: I wrote there that an unknown `derived_env` placeholder passes through verbatim. It doesn't — `validate_derived_template` rejects both unknown names and unbalanced `{{`. Fixed that row in the guide. Verified accurate and left alone: the capability allow-list, network_policy values, `/dev/*` device rule, volume option allow-list, bind-source confinement, the four generated_secret kinds, `hooks.pre_start` being schema-only, and the 30s reconciler interval (`BootReconciler::DEFAULT_INTERVAL`). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Archipelago documentation
Start here. This index groups the docs by what you're trying to do. The
authoritative behaviour is always the code in core/; where a doc and the code
disagree, the code wins and the doc is a bug.
Getting started
- User Walkthrough — setting up and using a node, from hardware to daily use
- Talking to your node — the conversational command surface
- Seed Verification — independently verify your 24-word backup
- Troubleshooting — common problems and how to resolve them
- Gamepad / Controller Navigation — driving the UI from a controller
Architecture
- Architecture — the system at a glance
- Multi-Node Architecture — how nodes relate across a fleet
- API Reference — the JSON-RPC surface
App development
- App Developer Guide — build and package a containerized app
- App Manifest Specification — the manifest schema, field by field
- Manifest → Quadlet unit — how a manifest compiles to a systemd-owned container unit
- Container lifecycle — the reconciler state machine: install/adopt/start/stop/self-heal
- App secrets — declaring, generating and injecting per-install credentials
- Registry-Distributed Manifests — how manifests reach nodes via the signed catalog
- Decentralized Marketplace Protocol — publishing apps via an external registry
- Bitcoin RPC Relay — letting an external wallet reach the node's Bitcoin RPC
- Companion Pairing QR — the pairing handoff contract
- TV input inside iframe apps — keyboard/gamepad routing into embedded apps
Design docs
These record why a thing is built the way it is. They are design records, not step-by-step guides, and some predate the current implementation.
- Registry-Distributed Manifests
- DHT Distribution
- Bitcoin Multi-Version
- Dual Ecash
- Hardware Signer
- Manifest Hooks
- Meshroller Integration
- Nostr Git Source Hosting
- Nostr Identity Import · Nostr Signer Login (research)
- Streaming Ecash (phase 4)
- App Packaging Migration
Decisions (ADRs)
- ADR-001: Podman over Docker
- ADR-002: DID Key Method for Node Identity
- ADR-003: Nostr Relays for Discovery
- ADR-004: Tor Hidden Services for Peer Communication
- ADR-005: ChaCha20-Poly1305 for Backup Encryption
- ADR-006: Nostr Relays for Marketplace Discovery
- ADR-007: DID-Based Federation Trust
- ADR-008: Dual Key Strategy (Ed25519 + Secp256k1)
- ADR-009: Manifest-Level Container Security
- ADR-011: DWN Deprioritization
Security
- Security Policy — how to report a vulnerability
- PSBT Signing Architecture
- Bitcoin RPC Proxy Exposure
- Entropy Enforcement (KEY-05)