archipelagoandClaude Opus 5
2ed6c71e0c
Narrative pass over troubleshooting.md against the code. Seven claims were wrong, several of them actively misleading: - **Tor is not a container.** §15/§16 told operators to run `podman ps --filter name=tor` / `podman restart tor` and to read `/var/lib/archipelago/tor/hidden_service/hostname`. Tor is the host's Debian package running as `debian-tor`; Archipelago drives it by staging a torrc and poking `archipelago-tor-helper` (`scripts/tor-helper.sh`, which does `systemctl restart tor`). The hidden-service dir is `hidden_service_archipelago` (suffixed), it's root-owned 0700, and the file a normal user can actually read is the synced copy at `/var/lib/archipelago/tor-hostnames/<service>`. - **The USB installer has no "Repair" mode.** Cited three times as the recovery path. The boot menu has exactly three entries: Install, Install (verbose), Boot from local disk. Replaced with what those entries can actually do, plus the fact that the installer prompts for a disk and requires typing `yes`, so booting it isn't itself destructive. - **`bitcoin-cli -datadir=/data`** — the container's datadir is `/home/bitcoin/.bitcoin` and RPC creds are in a generated `/tmp/rpc.conf`; the documented command could not have authenticated. - **"edit bitcoin.conf to add addnode="** — the entrypoint passes an explicit `-conf` and logs "ignoring legacy datadir bitcoin.conf". Flags come from the manifest (and the signed catalog entry that overrides it). - **"Bitcoin requires 600GB+"** — only above the manifest's 1000 GB threshold; below it the node runs pruned at `-prune=550`. - **`sudo systemctl restart podman`** — apps run under rootless Podman as the `archipelago` user, so that restarts an unrelated root socket. - **"Settings > Network"** — DNS config and disk cleanup are both on the Server page (`/server`), not Settings. Also: header claimed "the 20 most common issues" over 21 sections, and §16 presented Tor as required for peering when it's the last fallback after mesh → LAN → FIPS. 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)