4.6 KiB
Archipelago OS architecture
For a visual overview, open the styled HTML architecture guide.
This is the source-level map for a node on current main (reviewed 2026-11-12).
It describes boundaries and ownership, not the acceptance status of a release
or a particular installed node. For those, use Release & Testing, the signed release records, and the exact node evidence.
One node
Browser / Companion
|
v
Nginx: web UI, authenticated RPC and app routes
|
v
Rust backend: API, sessions, desired app state, reconciliation, updates
| |
| +--> signed release and app-catalog verification
v
systemd user services + rootless Podman: app containers and their networks
|
v
Persistent app data and secrets under /var/lib/archipelago
Debian + systemd own the host, boot and protected OS maintenance.
The browser UI is in neode-ui/. Nginx serves it and routes
API and app traffic. The backend is the archipelago crate in
core/archipelago/. The API entry points and RPC
dispatch are under api/; authentication and
session checks stay on the backend side of the browser boundary.
The backend's container/ code owns app
lifecycle and reconciliation. The shared core/container/
crate defines manifest parsing, Podman integration and catalog support.
apps/<id>/manifest.yml declares an app; a signed catalog can supply a newer
embedded manifest than the on-disk copy. A container or service being present
does not by itself establish a successful install, healthy app or accepted
release. See container lifecycle,
Quadlet compilation and the
manifest specification.
App databases, wallets, identity and other persistent state live under
/var/lib/archipelago. The application runtime and rootless containers must
not gain host package-writer or unrestricted container-engine authority. App
uninstall/update decisions preserve data according to their specific contract;
a test or cleanup must not treat live volumes as disposable. See
app secrets and the
container-store ownership follow-up.
Trust and updates
A release manifest and app catalog are verified against the pinned release
root before protected changes. The signed app catalog controls distributed app
metadata; source files in apps/ are development inputs. The application OTA
path, app activation and OS package/kernel update are separate transactions.
The protected OS updater has its own admission, package custody, reboot and
post-boot verification contract; an application update does not imply an OS
update or a successful new boot. Start with OS updates, then
the OS executor contract when changing that path.
A successful source test, disposable integration run, built artifact, installed node check and physical/operator acceptance are different levels of evidence. The current release and testing index tracks which level is actually complete. Historical acceptance records remain version-specific and do not certify a later build.
Network and node interfaces
The backend's fips/,
mesh/,
federation/ and
transport/ modules own distinct parts
of node connectivity. The Android Companion is in Android/.
App network aliases and externally reachable routes have separate admission
and authentication rules. Start with multi-node architecture,
external access and websites and the
peering trust model for the relevant feature.
The repository also contains an openwrt crate, image
inputs in image-recipe/ and the API's Cloud, wallet,
media and device modules. Their presence in source does not mean every
hardware or installed-node acceptance gate has passed.
Where to read next
- Developer guide: checkout, builds and safe tests.
- API reference: orientation to RPC; verify handlers in source.
- App developer guide: packaging and launch acceptance.
- Documentation index: current entry points versus dated designs.