ssmithxandClaude Sonnet 5
edcce5a308
Phase 1 of docs/nostr-vpn-integration-plan.md's Phase 0->4 plan (seller-side
rootless feasibility already confirmed there). Two apps, one image:
- apps/nostr-vpn: the daemon. Own network namespace (container.network:
pasta), NET_ADMIN+NET_RAW scoped to that netns, /dev/net/tun, and the
net.ipv4.ip_forward sysctl via the primitive added in e42bd26. UDP 51822
(not upstream's default 51820, which collides with archipelago-wg on
fleet nodes per the Phase 0 log). Seller mode stays off until an operator
explicitly enables it (paid_exit.enabled defaults to false upstream).
- apps/nostr-vpn-web: the control panel, gated behind 127.0.0.1:38080,
talking to the daemon only through the shared /data volume (state-file
status + shelling out to the nvpn CLI) -- no network link between the
two containers, matching upstream's own umbrel/docker-compose.yml.
- docker/nostr-vpn: upstream's umbrel/Dockerfile, unchanged except for how
the pinned commit arrives (shallow git fetch of a verified SHA, since
codeload.github.com archive tarballs 404 from this environment and
GitHub won't fetch an arbitrary SHA directly). Entrypoint seeds a minimal
config.toml with the chosen listen_port on first boot only -- every
AppConfig field is `serde(default = ...)`, confirmed by reading
nostr-vpn-core directly, so this merges with nvpn's own identity/wallet
bootstrap instead of needing a generated_secrets entry or full config
template, and never touches a config that already exists.
Both volumes point at /var/lib/archipelago/nostr-vpn, adopting state from
the old root-mode install. Build and the seed-config path were verified
against the real `nvpn daemon` binary, not just read -- see the plan doc's
Phase 1 log for what that caught (a fabricated commit SHA, the codeload
404, wrong default branch name, and confirming identity/wallet persistence
actually survives container recreation).
Not done here, flagged in the plan doc instead: removing the old root-mode
path (rpc/vpn.rs, rpc/auth.rs's auto-enable-on-login) touches live
onboarding on every node, not just this app -- needs explicit sign-off.
Also missing: a stop-hook/uninstall-guard manifest primitive (doesn't
exist yet -- LifecycleHooks only has post_install/pre_start) for the
collect-due-on-stop and non-zero-wallet uninstall guard, and registry
mirroring + catalog signing (need credentials this pass doesn't have).
Co-Authored-By: Claude Sonnet 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.
Current release
The current pre-release is v1.8.13-alpha. Release notes and signed OTA artifacts are published on Gitea. The same source is mirrored through ngit for Nostr-native cloning and contribution:
nostr://npub1w3sqdkrhn0gyuvsex32effzgnfpyde6qrrc4u467flg5e9txh4wsfn5vjg/relay.ngit.dev/archy
Clone with ngit, or use the Gitea mirror when you need a conventional Git remote. Contributions should follow CONTRIBUTING.md.
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.