<divclass="layer-layman">Controls what traffic goes where. One front door (nginx) routes requests to the right app. Tor makes you reachable without exposing your IP.</div>
<tr><tdclass="cmp-label">Capabilities</td><td><code>--cap-drop=ALL</code> then add only needed: CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE. Some get NET_RAW (LND), NET_BIND_SERVICE (Vaultwarden, nginx-pm, LND-UI).</td></tr>
<tr><tdclass="cmp-label">Privileges</td><td><code>--security-opt=no-new-privileges</code> on all containers</td></tr>
<tr><tdclass="cmp-label">Disk mode</td><td>Auto: if disk <1TB → Bitcoin prune=550, dbcache=512M. If ≥1TB → full txindex, dbcache=4G</td></tr>
<divclass="layer-layman">One front door (nginx) for all traffic. Tor lets people reach you without knowing your real address. Tailscale lets YOU reach the box from anywhere.</div>
<divclass="layer-details">
<h4>Nginx Reverse Proxy</h4>
<ul>
<li>Listens on <code>:80</code> (HTTP) and <code>:443</code> (HTTPS with self-signed cert)</li>
<li>Serves Vue.js SPA at <code>/</code></li>
<li>Proxies backend at <code>/rpc/v1</code>, <code>/ws</code>, <code>/health</code></li>
<li>Proxies each app at <code>/app/{name}/</code></li>
<divclass="layer-layman">Apps run in sealed boxes. They can only see what we let them see, use only the memory we allow, and can't mess with each other.</div>
<divclass="layer-details">
<h4>Rootless Podman</h4>
<ul>
<li>All containers run as user <code>archipelago</code> (UID 1000)</li>
<li>No root access required — even if a container is compromised, it can't escalate to root</li>
<divclass="layer-desc">X11 + Chromium in kiosk mode on VT7, auto-start, crash recovery</div>
<divclass="layer-layman">Plug in a monitor and the dashboard appears fullscreen. No login, no desktop, just your node. Press Ctrl+Alt+F1 for a terminal.</div>
<divclass="layer-details">
<h4>How It Works</h4>
<ul>
<li>X11 server (Xorg) starts on Virtual Terminal 7</li>
<li>Chromium launches in <code>--kiosk --app=http://localhost/kiosk</code> mode</li>
<li>No address bar, no tabs, no right-click — just the dashboard</li>
<li>Cursor hidden after 3 seconds of inactivity</li>
<divclass="card-desc">Full Bitcoin node (Knots variant). Validates every transaction and block independently. The root dependency for the entire Bitcoin stack.</div>
<divclass="card-layman">Your own copy of the entire Bitcoin network. Nobody can lie to you about your balance because you verify everything yourself.</div>
<divclass="detail-row"><spanclass="detail-label">Port 8332</span><spanclass="detail-value">JSON-RPC API (how other apps talk to Bitcoin)</span></div>
<divclass="detail-row"><spanclass="detail-label">Port 8333</span><spanclass="detail-value">P2P network (connects to other Bitcoin nodes worldwide)</span></div>
<divclass="detail-row"><spanclass="detail-label">Port 28332</span><spanclass="detail-value">ZMQ block notifications (instant alert when new block arrives)</span></div>
<divclass="detail-row"><spanclass="detail-label">Port 28333</span><spanclass="detail-value">ZMQ transaction notifications (instant alert for new transactions)</span></div>
<divclass="detail-row"><spanclass="detail-label">Memory</span><spanclass="detail-value">2 GB (1 GB on low-memory systems)</span></div>
<divclass="detail-row"><spanclass="detail-label">Disk mode</span><spanclass="detail-value">Auto: prune if <1TB, full txindex if ≥1TB</span></div>
<divclass="detail-row"><spanclass="detail-label">RPC Auth</span><spanclass="detail-value">HMAC-SHA256 salted hash (no plaintext password in config)</span></div>
<divclass="detail-row"><spanclass="detail-label">Tor</span><spanclass="detail-value">Routes P2P through Tor SOCKS5 for privacy</span></div>
<divclass="card-desc">Electrum protocol server. Indexes the blockchain by address so wallets can look up balances instantly without scanning every block.</div>
<divclass="card-layman">An index for Bitcoin. Like a book's table of contents — instead of reading every page to find your info, you jump straight to it.</div>
<divclass="detail-row"><spanclass="detail-label">Protocol</span><spanclass="detail-value">Electrum JSON-RPC over TCP</span></div>
<divclass="detail-row"><spanclass="detail-label">Deps</span><spanclass="detail-value"><spanclass="dep-tag"onclick="find('bitcoin-knots')">bitcoin-knots</span> (reads blockchain via RPC)</span></div>
<divclass="card-layman">Lets you send and receive Bitcoin instantly (instead of waiting 10+ minutes for a block). Like a tab at a bar — settle up later on-chain.</div>
<divclass="detail-row"><spanclass="detail-label">Port 9735</span><spanclass="detail-value">Lightning P2P (connects to other Lightning nodes)</span></div>
<divclass="detail-row"><spanclass="detail-label">Port 10009</span><spanclass="detail-value">gRPC API (admin operations, authenticated with macaroons)</span></div>
<divclass="detail-row"><spanclass="detail-label">Port 8080</span><spanclass="detail-value">REST API (simpler HTTP interface to LND)</span></div>
<divclass="detail-row"><spanclass="detail-label">Auth</span><spanclass="detail-value">Macaroon tokens (read-only for queries, admin for mutations)</span></div>
<divclass="detail-row"><spanclass="detail-label">Tor</span><spanclass="detail-value">Active with stream isolation (each connection uses different circuit)</span></div>
<divclass="detail-row"><spanclass="detail-label">Tor</span><spanclass="detail-value">Has its own .onion address for receiving payments privately</span></div>
<divclass="card-desc">Federated mint daemon. Enables community-run Bitcoin custody with threshold signing and e-cash tokens.</div>
<divclass="card-layman">A way for a group of trusted people to collectively hold Bitcoin. No single person can steal the funds — you need a majority to approve.</div>
<divclass="detail-row"><spanclass="detail-label">Mode</span><spanclass="detail-value">Auto-detect: uses LND if available, otherwise built-in LDK Lightning</span></div>
<divclass="card-desc">Self-hosted file sync and collaboration platform. Dropbox/Google Drive replacement with calendar, contacts, and office docs.</div>
<divclass="card-layman">Your own Dropbox. Sync files, share documents, manage calendar and contacts — all on your own hardware.</div>
<divclass="card-desc">GUI for managing nginx proxy rules and SSL certificates. Point-and-click reverse proxy configuration.</div>
<divclass="card-layman">A visual tool for routing web traffic. Point domains to services and manage HTTPS certificates with clicks, not config files.</div>
<divclass="proto-card-desc">Real-time bidirectional channel for live updates — container status changes, logs, events.</div>
<divclass="proto-card-layman">An open phone line between your browser and the server. Instead of asking "any updates?" every second, the server just tells you when something changes.</div>
<divclass="proto-card-desc">High-performance RPC protocol used by LND for admin operations. Binary format, strongly typed.</div>
<divclass="proto-card-layman">A fast, structured way for apps to control the Lightning node. More efficient than regular HTTP for complex operations.</div>
<divclass="proto-details">
<b>Endpoint:</b><code>lnd:10009</code><br>
<b>Auth:</b> Macaroon tokens (read-only for queries, admin for mutations)<br>
<divclass="proto-card-desc">Lightweight protocol for wallet address lookups. JSON-RPC over raw TCP sockets.</div>
<divclass="proto-card-layman">How Bitcoin wallets check their balance without downloading the entire blockchain. Ask "what transactions touched this address?" and get an instant answer.</div>
<divclass="proto-card-desc">Publish-subscribe messaging from Bitcoin node. Instant notifications for new blocks and transactions.</div>
<divclass="proto-card-layman">A broadcasting system. When a new Bitcoin block is found, Bitcoin instantly shouts it out and everyone listening hears immediately.</div>
<divclass="proto-details">
<b>Endpoints:</b><br>
•<code>tcp://bitcoin-knots:28332</code>— New block hashes (hashblock)<br>
•<code>tcp://bitcoin-knots:28333</code>— New raw transactions (rawtx)<br>
<divclass="proto-card-desc">Privacy layer. Routes Bitcoin P2P through onion routing, exposes services as .onion addresses.</div>
<divclass="proto-card-layman">Like sending a letter through 3 random post offices so nobody knows where it came from. Also lets people reach your node without knowing your real IP.</div>
<divclass="proto-card-desc">Decentralized social protocol. WebSocket-based relay communication for events (posts, follows, messages).</div>
<divclass="proto-card-layman">A social media protocol where no company controls the network. Your posts live on relays, and you own your identity with a cryptographic key.</div>
<divclass="proto-details">
<b>Transport:</b> WebSocket (WSS)<br>
<b>Format:</b> JSON events signed with secp256k1 keys<br>
<divclass="proto-card-name">DWN (Decentralized Web Node)</div>
<divclass="proto-card-desc">W3C protocol for storing encrypted data and messages in a decentralized way. Identity-linked storage.</div>
<divclass="proto-card-layman">A personal data vault. Apps can store data here that only you control. Like a safety deposit box that follows you across the internet.</div>
<divclass="proto-details">
<b>Endpoint:</b><code>/dwn</code> (proxied through nginx)<br>
<b>Auth:</b> Per-record DID-based permissions<br>
<b>Reachable via:</b> Tor hidden service<br>
<b>Used for:</b> Encrypted backups, cross-node messaging, app data sync
<divclass="layer-desc">Issue, verify, revoke, and present credentials with Ed25519Signature2020 proofs — W3C VC Data Model 2.0</div>
<divclass="layer-layman">Digital certificates that prove things about you — signed by one identity, held by another, verified by anyone. Like a digitally signed diploma.</div>
<divclass="layer-details">
<h4>Three-Party Model</h4>
<ul>
<li><b>Issuer:</b> Creates and signs the credential (any managed identity)</li>
<divclass="layer-desc">Personal data store with protocol-governed records, peer sync over Tor, and DID-based authorization</div>
<divclass="layer-layman">Your personal database that YOU own. Apps ask permission to read/write data. Syncs with trusted peers automatically over Tor.</div>
<divclass="layer-details">
<h4>Records Interface</h4>
<ul>
<li><code>Records.Write</code>— Store a message (UUID-based record_id)</li>
<li><code>Records.Read</code>— Retrieve by record_id</li>
<li><code>Records.Query</code>— Filter by protocol, schema, author, date range</li>
<divclass="layer-desc">W3C DID Core 1.0 — did:key (primary, offline-capable) and did:dht (discoverability via BitTorrent Mainline DHT)</div>
<divclass="layer-layman">Your self-sovereign digital identity. No company issues it, no platform controls it. You prove who you are with cryptographic keys.</div>
<divclass="layer-details">
<h4>did:key (Primary Method)</h4>
<ul>
<li>Self-contained — no external resolution, works fully offline</li>
<li>Format: <code>did:key:z6Mk...</code> (multicodec Ed25519 in base58btc)</li>
<li>Instant, zero-cost, no network dependency</li>
<divclass="layer-desc">Dual key architecture — Ed25519 for Web5/DIDs + secp256k1 for Bitcoin/Nostr, both derived from BIP-39 master seed</div>
<divclass="layer-layman">Two types of cryptographic keys derived from one master seed. One for identity (Web5), one for money and social (Bitcoin/Nostr).</div>
Web5 was initiated by TBD (Block/Jack Dorsey) and shut down November 2024. Open-source components were donated to the <bstyle="color:#c4c8e0;">Decentralized Identity Foundation (DIF)</b>.
The W3C specs (DIDs, VCs) are independent standards with broad industry adoption. Archipelago implements these W3C standards directly with a custom DWN — not dependent on TBD's SDK.
<tr><tdclass="cmp-label">DID Core 1.0</td><td>W3C Recommendation</td><td><spanclass="card-badge badge-green">Stable</span></td><td>did:key + did:dht, full DID Document generation</td></tr>
<tr><tdclass="cmp-label">VC Data Model 2.0</td><td>W3C Recommendation (May 2025)</td><td><spanclass="card-badge badge-green">Stable</span></td><td>Issue/verify/revoke with Ed25519Signature2020</td></tr>
<tr><tdclass="cmp-label">DWN</td><td>DIF Draft</td><td><spanclass="card-badge badge-amber">Draft</span></td><td>Custom Records interface, protocol management, Tor sync</td></tr>
<tr><tdclass="cmp-label">did:dht</td><td>Near v1.0</td><td><spanclass="card-badge badge-amber">Active</span></td><td>Mainline DHT publishing via <code>mainline</code> crate</td></tr>
<tr><tdclass="cmp-label">ADR-002</td><td>did:key as primary DID method</td><td>Self-contained, offline-capable, zero-cost, aligns with sovereignty</td></tr>
<tr><tdclass="cmp-label">ADR-008</td><td>Dual key architecture (Ed25519 + secp256k1)</td><td>Ed25519 for W3C/Web5, secp256k1 for Bitcoin/Lightning/Nostr ecosystems</td></tr>
<tr><tdclass="cmp-label">ADR-011</td><td>Custom DWN, not full W3C spec compliance</td><td>TBD shut down, DWN spec stalled. Federation + Nostr relays prioritized for peer sync</td></tr>
<divclass="boot-title">LUKS Unlock → Mount Encrypted Partition</div>
<divclass="boot-desc">Cryptsetup opens the LUKS2 volume using <code>/root/.luks-archipelago.key</code> and mounts it at <code>/var/lib/archipelago</code>.</div>
<divclass="boot-layman">The encrypted safe is unlocked automatically (no password prompt). All your data becomes accessible.</div>
<divclass="boot-detail">Configured in /etc/crypttab for automatic boot-time unlock</div>
<divclass="boot-desc"><code>archipelago.service</code> launches the Rust binary. Runs crash recovery, starts container state snapshots, initializes JSON-RPC server on :5678.</div>
<divclass="boot-layman">The brain of the system wakes up. If there was a crash last time, it automatically recovers.</div>
<divclass="boot-desc"><code>first-boot-containers.sh</code> runs once (guarded by marker file). Creates all containers in tier order: databases → Bitcoin → services → apps.</div>
<divclass="boot-layman">On first startup only: installs all the apps. Databases first, then Bitcoin, then everything else. Takes 5-15 minutes.</div>
<divclass="boot-desc"><code>archipelago-kiosk.service</code> waits for <code>/health</code> endpoint (up to 30s), then starts X11 + Chromium on VT7.</div>
<divclass="boot-layman">If a monitor is plugged in, the dashboard appears fullscreen automatically. No login needed for the local screen.</div>
<divclass="boot-detail">Polls /health 15 times at 2s intervals before launching Chromium</div>
<divclass="boot-desc">Timers activate: container doctor (health repair), reconciler (spec enforcement), self-update. Tor helper watches for service config changes.</div>
<divclass="boot-layman">Maintenance robots start working in the background. They check on apps, fix broken ones, and keep everything updated.</div>
<divclass="sec-desc">All user data on an encrypted partition. Auto-detects AES-NI for hardware acceleration, falls back to ChaCha20-Adiantum. Key derived with Argon2id (GPU-resistant).</div>
<divclass="sec-layman">If someone physically steals your hard drive, all they get is encrypted noise. The data is useless without the key.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Rootless Containers</div>
<divclass="sec-desc">All containers run as unprivileged user archipelago (UID 1000). Even a compromised container cannot escalate to root. UID remapping isolates container users from host users.</div>
<divclass="sec-layman">Apps run in sealed boxes without admin access. A hacked app can't take over the whole machine.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Capability Dropping</div>
<divclass="sec-desc"><code>--cap-drop=ALL</code> then add only specific capabilities needed. <code>--security-opt=no-new-privileges</code> prevents privilege escalation inside containers.</div>
<divclass="sec-layman">Each app only gets the exact permissions it needs, nothing more. Like giving a valet driver only the car key, not your house keys.</div>
<divclass="sec-desc">Backend uses explicit method allowlists per role. No prefix matching — each RPC method must be explicitly permitted. Session cookies are HttpOnly, SameSite=Lax.</div>
<divclass="sec-layman">Different users have different permissions. A viewer can't install apps, and nobody can run commands that aren't on the approved list.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Rate Limiting</div>
<divclass="sec-desc">Nginx rate limits: auth endpoints (3/s), RPC (20/s), P2P (10/s). Prevents brute-force attacks and API abuse.</div>
<divclass="sec-layman">If someone tries to guess your password by trying thousands of combinations, they get locked out after a few attempts per second.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Tor Privacy</div>
<divclass="sec-desc">Bitcoin P2P routes through Tor with stream isolation. Hidden services expose node without revealing IP. LND uses Tor for Lightning P2P.</div>
<divclass="sec-layman">Your Bitcoin node connects through the Tor privacy network. Nobody can see your real IP address or location.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Credential Management</div>
<divclass="sec-desc">Secrets auto-generated at first boot (CSPRNG). Stored in <code>/var/lib/archipelago/secrets/</code> (mode 700). Bitcoin RPC uses HMAC-SHA256 auth hashes, never plaintext.</div>
<divclass="sec-layman">Passwords are randomly generated and stored securely. They never appear in config files as readable text.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Memory Limits & Health Checks</div>
<divclass="sec-desc">Every container has a memory limit (128MB–4GB). Health checks auto-restart failed containers. Backend has systemd watchdog (300s).</div>
<divclass="sec-layman">Runaway apps can't eat all the memory. Crashed apps restart automatically. The system self-heals.</div>
<divclass="sec-layman">The web UI tells browsers to follow strict security rules — no loading scripts from unknown sites, no accessing your camera.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Systemd Hardening</div>
<divclass="sec-desc"><code>ProtectSystem=strict</code>, <code>MemoryDenyWriteExecute</code>, <code>RestrictRealtime</code>, <code>RestrictAddressFamilies</code>. Backend can only write to approved paths.</div>
<divclass="sec-layman">The operating system restricts what the backend can do. It can only touch the files it needs to, nothing else on the system.</div>
<divclass="glossary-plain">A tool that runs apps in isolated sandboxes. Like Docker but doesn't need a background service running as root.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Rootless</div>
<divclass="glossary-tech">Containers run entirely in user namespace, no root privileges required</div>
<divclass="glossary-plain">The sandboxes run without admin access. Even if someone breaks into one, they can't take over the system.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">LUKS2</div>
<divclass="glossary-tech">Linux Unified Key Setup v2 — dm-crypt disk encryption with Argon2 KDF</div>
<divclass="glossary-plain">Industry-standard disk encryption for Linux. Scrambles the entire partition so data is unreadable without the key.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Argon2id</div>
<divclass="glossary-tech">Memory-hard password hashing function resistant to GPU/ASIC brute-force</div>
<divclass="glossary-plain">A way to protect passwords that requires lots of memory to crack, making it extremely expensive to brute-force even with specialized hardware.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Nginx</div>
<divclass="glossary-tech">High-performance HTTP reverse proxy and web server</div>
<divclass="glossary-plain">The front door of the system. All web traffic goes through nginx, which directs each request to the right app.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Reverse Proxy</div>
<divclass="glossary-tech">Server that forwards client requests to backend services based on URL path or hostname</div>
<divclass="glossary-plain">A traffic cop for web requests. You visit one address, and the proxy routes you to the right app behind the scenes.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">JSON-RPC</div>
<divclass="glossary-tech">Remote procedure call protocol using JSON over HTTP/TCP</div>
<divclass="glossary-plain">A simple way for one program to ask another to do something. Send a JSON message, get a JSON reply.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">WebSocket</div>
<divclass="glossary-tech">Full-duplex TCP communication channel over HTTP upgrade</div>
<divclass="glossary-plain">A persistent connection between browser and server. Instead of repeatedly asking "anything new?", the server pushes updates instantly.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">gRPC</div>
<divclass="glossary-tech">Google's high-performance RPC framework using Protocol Buffers over HTTP/2</div>
<divclass="glossary-plain">A fast, structured way for programs to communicate. Used by LND because it handles many Lightning operations efficiently.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">ZMQ (ZeroMQ)</div>
<divclass="glossary-tech">Asynchronous messaging library for pub/sub and push/pull patterns</div>
<divclass="glossary-plain">A broadcasting system. Bitcoin publishes "new block!" and every subscribed app hears it instantly.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Tor</div>
<divclass="glossary-tech">Onion routing network for anonymous communication via encrypted relay circuits</div>
<divclass="glossary-plain">A privacy network that bounces your traffic through multiple servers so nobody can trace it back to you.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Hidden Service (.onion)</div>
<divclass="glossary-tech">Tor service accessible via .onion address without revealing server IP</div>
<divclass="glossary-plain">A way to make your node reachable on the internet without revealing your IP address or location.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Tailscale</div>
<divclass="glossary-tech">WireGuard-based mesh VPN with NAT traversal and SSO integration</div>
<divclass="glossary-plain">A private tunnel to your node from anywhere. Like a VPN but easier — install the app on your phone, and you can access the node from a coffee shop.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Macaroon</div>
<divclass="glossary-tech">Bearer token with embedded caveats (permissions) used by LND for API auth</div>
<divclass="glossary-plain">A special key for LND that says exactly what you're allowed to do. A "read-only" macaroon can check balance but can't send money.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">CSRF Token</div>
<divclass="glossary-tech">Cross-Site Request Forgery prevention token sent in cookie + header</div>
<divclass="glossary-plain">A secret code that proves your browser request is genuine and not a trick from a malicious website.</div>
<divclass="glossary-tech">W3C standard for self-sovereign identity using cryptographic keypairs</div>
<divclass="glossary-plain">Your digital identity that you own completely. Like a passport that no government issued — you prove who you are with math, not authority.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Nostr</div>
<divclass="glossary-tech">Notes and Other Stuff Transmitted by Relays — decentralized social protocol</div>
<divclass="glossary-plain">A social media protocol where you own your identity. No company can ban you because your account is just a cryptographic key.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Lightning Network</div>
<divclass="glossary-tech">Bitcoin Layer 2 payment channel network for instant, low-fee transactions</div>
<divclass="glossary-plain">A way to send Bitcoin instantly (milliseconds) for tiny fees. Works by opening "tabs" between nodes and settling on-chain later.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Fedimint</div>
<divclass="glossary-tech">Federated Bitcoin custody protocol with threshold signing and Chaumian e-cash</div>
<divclass="glossary-plain">A community Bitcoin bank where a group of trusted guardians hold funds together. No single person can steal — you need a majority to sign.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">archy-net</div>
<divclass="glossary-tech">Custom Podman bridge network with DNS resolution for Bitcoin-stack containers</div>
<divclass="glossary-plain">A private network inside the box where Bitcoin apps can find each other by name. Like a local phone book for containers.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Capability (CAP)</div>
<divclass="glossary-tech">Fine-grained Linux privilege (e.g. CAP_NET_RAW, CAP_CHOWN) instead of full root</div>
<divclass="glossary-plain">Instead of giving an app all admin powers, we give it only the specific abilities it needs. A file manager gets "change file ownership" but not "change network settings."</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">Systemd</div>
<divclass="glossary-tech">Linux init system and service manager (PID 1)</div>
<divclass="glossary-plain">The thing that starts everything when Linux boots. Manages all services, restarts crashed ones, and enforces resource limits.</div>
</div>
<divclass="glossary-item">
<divclass="glossary-term">RBAC</div>
<divclass="glossary-tech">Role-Based Access Control — permissions assigned by user role, not individually</div>
<divclass="glossary-plain">Different users get different permissions based on their role (admin, viewer, etc). Prevents regular users from doing dangerous things.</div>
<divclass="layer l-cnt"><divclass="layer-header"><spanclass="layer-name">LXC Containers</span><spanclass="layer-tag badge-green">Isolation</span></div><divclass="layer-desc">Two-layer model: outer LXC per service (SquashFS + OverlayFS), inner subcontainers from S9PK images. JSON-RPC over Unix sockets.</div></div>
<divclass="layer l-net"><divclass="layer-header"><spanclass="layer-name">Network (built-in)</span><spanclass="layer-tag badge-cyan">Network</span></div><divclass="layer-desc">VHostController reverse proxy, hickory-server DNS, ACME TLS, WireGuard tunnels, SOCKS5 at 10.0.3.1:1080. No nginx/caddy.</div></div>
<divclass="layer l-enc"><divclass="layer-header"><spanclass="layer-name">Optional LUKS on btrfs</span><spanclass="layer-tag badge-purple">Security</span></div><divclass="layer-desc">User chooses encrypted or unencrypted during setup. LVM with btrfs for COW snapshots enabling safe app installs.</div></div>
<divclass="layer-desc">Angular 21 + TypeScript + Taiga UI 5 components, served directly by the Rust backend (Axum)</div>
<divclass="layer-layman">The dashboard you use in your browser. Built with Angular (Google's web framework), not served by a separate web server.</div>
<divclass="layer-details">
<h4>Three Separate Angular Apps</h4>
<ul>
<li><code>projects/ui/</code>— Main admin interface</li>
<divclass="layer-layman">The brain of the system. One binary that does everything — serves the UI, manages containers, handles networking, runs the built-in reverse proxy.</div>
<divclass="layer-details">
<h4>Key Components</h4>
<ul>
<li><b>Axum web server:</b> Serves UI + JSON-RPC API (no separate web server)</li>
<li><b>VHostController:</b> Built-in reverse proxy with TLS termination (no nginx/caddy)</li>
<li><b>Patch-DB:</b> Custom CBOR-encoded reactive database with diff-based WebSocket sync</li>
<divclass="layer-desc">Linux Containers (LXC) with two-layer model: outer LXC per service + inner subcontainers from S9PK images</div>
<divclass="layer-layman">Each app gets its own sealed Linux environment. Unlike Docker, these are full system containers with their own init process.</div>
<divclass="layer-details">
<h4>Two-Layer Container Model</h4>
<ul>
<li><b>Outer LXC container:</b> One per service. Created by Rust backend via lxc-create/destroy</li>
<li><b>Base rootfs:</b> SquashFS image (<code>/usr/lib/startos/container-runtime/rootfs.squashfs</code>) mounted as OverlayFS</li>
<li><b>Inner subcontainers:</b> Node.js container runtime inside each LXC can launch additional containers from S9PK-bundled images</li>
<divclass="layer-layman">No nginx or caddy — the Rust backend IS the web server, proxy, and DNS. Also manages VPN tunnels and encryption certificates.</div>
<divclass="layer-details">
<h4>Built-in Reverse Proxy</h4>
<ul>
<li>VHostController in <code>core/src/net/vhost.rs</code> handles all HTTP routing</li>
<li>TLS termination via tokio-rustls with SNI-based routing</li>
<li>No external proxy software (no nginx, no caddy, no traefik)</li>
<li>Virtual hosting with per-service domain assignment</li>
</ul>
<h4>DNS</h4>
<ul>
<li>Built-in DNS server using <code>hickory-server</code> (formerly trust-dns)</li>
<li>Service discovery and resolution for containers</li>
<li>mDNS via <code>avahi-resolve-host-name</code> for <code>.local</code> domains</li>
</ul>
<h4>TLS / Certificates</h4>
<ul>
<li>Self-signed root CA per server (NIST P-256 via OpenSSL)</li>
<li>Built-in ACME client (<code>async-acme</code>) for Let's Encrypt with TLS-ALPN-01 challenge</li>
<li>Certificate store managed in Patch-DB</li>
</ul>
<h4>Connectivity</h4>
<ul>
<li><b>SOCKS5 proxy:</b> Built-in at <code>10.0.3.1:1080</code> for container outbound traffic</li>
<li><b>WireGuard:</b> First-class support via <code>wg-quick</code> + <code>x25519-dalek</code></li>
<li><b>Multi-gateway:</b> Supports multiple interfaces (Ethernet, WiFi, WireGuard) with separate domain configs</li>
<li><b>Port forwarding:</b> iptables-based via <code>InterfacePortForwardController</code></li>
</ul>
<h4>Tor (Status: Removed in v0.4)</h4>
<ul>
<li>Architecture doc mentions "Tor via Arti" but Arti is absent from current Cargo.toml</li>
<li>Previous versions (0.3.x) used the C Tor daemon for hidden services</li>
<li>Likely planned for re-integration but not yet implemented in the 0.4 rewrite</li>
<divclass="layer-desc">Optional LUKS encryption on LVM volumes, btrfs filesystem with COW snapshots for safe installs</div>
<divclass="layer-layman">Disk encryption is optional (you choose during setup). Uses btrfs which can make instant copies of data for safe app updates.</div>
<divclass="layer-details">
<h4>Encryption (Optional)</h4>
<ul>
<li>User chooses encrypted or unencrypted during setup</li>
<li>LVM volume groups: <code>STARTOS_<random></code> (encrypted) or <code>STARTOS_<random>_UNENC</code></li>
<li>LUKS via <code>cryptsetup luksFormat/luksOpen</code> with password-based key</li>
<li>Default password: <code>"password"</code> (changed during setup)</li>
</ul>
<h4>Filesystem: btrfs</h4>
<ul>
<li>Copy-on-Write (COW) snapshots for safe service installs</li>
<li><code>cp --reflink=always</code> for instant volume snapshots before upgrades</li>
<li>If install fails, volumes restored from snapshot automatically</li>
</ul>
<h4>Volume Layout (LVM)</h4>
<ul>
<li><code>main</code> (8 GB) — System data, Patch-DB</li>
<li><code>package-data</code> (100% remaining) — All service/app data</li>
<divclass="sec-desc"><b>Outer:</b> One LXC container per service, created by the Rust backend. Base rootfs is a read-only SquashFS image mounted as OverlayFS. <b>Inner:</b> Node.js container runtime inside each LXC can launch subcontainers from S9PK-bundled images.</div>
<divclass="sec-layman">Each app gets its own sealed Linux environment with a read-only base. Any changes go to a separate overlay layer.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Communication</div>
<divclass="sec-desc">JSON-RPC over Unix domain sockets. <code>/media/startos/rpc/service.sock</code> (inbound) and <code>host.sock</code> (host callbacks). Services export <code>init()</code>, <code>uninit()</code>, <code>main()</code> via JavaScript ABI.</div>
<divclass="sec-layman">Apps talk to the system through socket files, not network ports. Each app implements 3 required JavaScript functions.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Isolation</div>
<divclass="sec-desc">User namespaces (container UID 0 → host UID 100000, range 65536). AppArmor profiles with nesting. veth bridge on <code>lxcbr0</code> (10.0.3.x subnet). GPU passthrough support via manifest flag.</div>
<divclass="sec-layman">Container root maps to an unprivileged host user. Each container gets its own virtual network interface.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Lifecycle</div>
<divclass="sec-desc"><code>LxcManager</code> handles creation (30s timeout), garbage collection, and cleanup. Service actors manage per-service state machines. btrfs reflink snapshots before install/upgrade for atomic rollback.</div>
</div>
</div>
<h3class="subsection-title">S9PK Package Format (v2)</h3>
<divclass="sec-grid">
<divclass="sec-card">
<divclass="sec-title">Signed Merkle Archive</div>
<divclass="sec-desc">Ed25519 signatures with prehashed content (SHA-512 over blake3 merkle root). Magic bytes: <code>0x3b 0x3b 0x02</code>. Enables partial downloads, integrity verification of subsets, and efficient delta updates.</div>
<divclass="sec-layman">App packages are cryptographically signed and structured so you can verify integrity without downloading the entire thing.</div>
<divclass="sec-layman">Each package bundles its own containers, logic code, icon, and license in one downloadable file.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Service ABI (JavaScript/Node.js)</div>
<divclass="sec-desc">Services implement <code>init()</code>, <code>uninit()</code>, and <code>main()</code> in JavaScript. The container runtime provides an <code>Effects</code> interface for host callbacks (dependency queries, config, health reporting).</div>
<divclass="sec-layman">App developers write their service logic in JavaScript. The system provides a standard API for the app to interact with the host.</div>
<divclass="proto-card-desc">The Angular frontend communicates with startd via JSON-RPC over HTTP. 100+ API methods. State sync via Patch-DB WebSocket.</div>
<divclass="proto-card-layman">The dashboard sends commands and gets responses in JSON format. Live updates stream automatically through a WebSocket.</div>
<divclass="proto-details">
<b>Transport:</b> HTTP POST (commands) + WebSocket (state sync)<br>
<b>State sync:</b> Patch-DB pushes CBOR-encoded diffs over WebSocket<br>
<b>Frontend applies:</b><code>PatchDB.watch$()</code>→ Angular signals via <code>toSignal()</code><br>
<b>Methods:</b> 100+ via <code>ApiService</code> abstract class
<divclass="proto-card-desc">Custom reactive database using CBOR encoding. Backend pushes diffs over WebSocket — UI updates automatically without polling.</div>
<divclass="proto-card-layman">Instead of the UI constantly asking "what changed?", the backend pushes only what changed, in a compact binary format.</div>
<divclass="proto-card-desc">TLS termination handled directly by the Rust backend (tokio-rustls). Self-signed root CA per server + ACME for public domains.</div>
<divclass="proto-card-layman">The backend IS the web server — no nginx or caddy needed. It handles encryption directly.</div>
<divclass="proto-details">
<b>TLS library:</b> tokio-rustls 0.26 + OpenSSL (vendored, for cert generation)<br>
<b>Local certs:</b> Self-signed root CA (NIST P-256 keys)<br>
<b>Public certs:</b> ACME client (<code>async-acme</code>) with TLS-ALPN-01 challenge<br>
<b>Routing:</b> SNI-based virtual hosting via VHostController
<divclass="proto-card-desc">First-class WireGuard support for remote access. Users add WireGuard configs as "gateways." Managed by tunnelbox daemon.</div>
<divclass="proto-card-layman">Built-in VPN for accessing your node from anywhere. Add a WireGuard config and get a secure tunnel.</div>
<divclass="proto-card-desc">Built-in DNS server for service discovery and resolution. Also uses mDNS (avahi) for .local domain access on LAN.</div>
<divclass="proto-card-layman">The system runs its own DNS so containers can find each other by name. Your phone finds the node via .local address.</div>
<p>StartOS does not implement Web5 (DIDs, DWNs, or Verifiable Credentials).<br>Authentication uses password-based sessions and public/private key signatures.</p>
<divclass="sec-desc">Each service in its own LXC container with UID/GID mapping (container 0 → host 100000, range 65536). AppArmor profiles with nesting. OverlayFS rootfs (base read-only).</div>
<divclass="sec-layman">Apps run in isolated Linux environments with their own user systems. Container root is mapped to an unprivileged host user.</div>
<divclass="sec-desc">All S9PK packages signed with Ed25519 over blake3 merkle roots. Signature verified before installation. Prevents supply chain attacks.</div>
<divclass="sec-layman">Every app package is cryptographically signed. If someone tampers with it, the signature check fails and installation is blocked.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">btrfs Snapshots</div>
<divclass="sec-desc">COW filesystem snapshots before every install/upgrade. If an install fails, data is atomically restored to the pre-install state.</div>
<divclass="sec-layman">The system takes a snapshot before every app update. If the update fails, your data is automatically rolled back.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Authentication</div>
<divclass="sec-desc">Password-based + session cookies. Local authcookie for CLI. Public/private key signatures for remote admin. Encrypted wire protocol during setup (public key exchange + encrypted password).</div>
<divclass="boot-desc">Mount logs to data drive, load CA certificate, set CPU governor to performance, NTP clock sync, enable zram, hardware inventory via <code>lshw</code>.</div>
<divclass="layer l-ui"><divclass="layer-header"><spanclass="layer-name">React 19 + Tailwind 4 + Radix UI</span><spanclass="layer-tag badge-purple">UI</span></div><divclass="layer-desc">Static SPA served by umbreld's Express server. Zustand + TanStack React Query for state. tRPC for typed API. 8+ languages.</div></div>
<divclass="layer l-svc"><divclass="layer-header"><spanclass="layer-name">umbreld (Node.js 22 / TypeScript)</span><spanclass="layer-tag badge-blue">Service</span></div><divclass="layer-desc">Single daemon on port 80: Express + tRPC API, app lifecycle via Docker Compose, file manager, backups (Kopia), terminal (node-pty).</div></div>
<divclass="layer l-cnt"><divclass="layer-header"><spanclass="layer-name">Docker 28.5 (rootful)</span><spanclass="layer-tag badge-green">Containers</span></div><divclass="layer-desc">Each app is a Docker Compose project. Flat bridge network (10.21.0.0/16). Per-app auth proxy containers. All containers destroyed on boot.</div></div>
<divclass="layer l-net"><divclass="layer-header"><spanclass="layer-name">Networking</span><spanclass="layer-tag badge-cyan">Network</span></div><divclass="layer-desc">No reverse proxy. Express serves on :80 directly. Optional Tor (containerized). mDNS via avahi. No TLS by default.</div></div>
<divclass="layer l-os"><divclass="layer-header"><spanclass="layer-name">Debian Trixie (testing) + Rugix</span><spanclass="layer-tag badge-amber">OS</span></div><divclass="layer-desc">Date-pinned Debian testing. Rugix A/B root partitions for atomic OS updates with automatic rollback. /data partition persists.</div></div>
<divclass="layer-desc">Docker 28.5.0 (rootful, not rootless) + Docker Compose v2. Each app is a separate Compose project.</div>
<divclass="layer-layman">Apps run in Docker containers managed by Docker Compose. Unlike Podman, Docker runs as root — simpler but less isolated.</div>
<divclass="layer-details">
<h4>Docker Setup</h4>
<ul>
<li>Installed via official Docker install script, pinned to v28.5.0</li>
<li>Rootful (runs as root) — not rootless</li>
<li>Each app: separate Docker Compose project (<code>--project-name <app-id></code>)</li>
<li>Legacy container naming: <code><app-id>_<service>_1</code> for DNS compat</li>
<divclass="layer-desc">No traditional reverse proxy. umbreld serves on port 80. Per-app proxy containers. Optional Tor via container.</div>
<divclass="layer-layman">No nginx, no caddy — the backend itself serves on port 80. Each app has its own mini proxy container for authentication.</div>
<divclass="layer-details">
<h4>HTTP</h4>
<ul>
<li>umbreld's Express server listens directly on port 80</li>
<li>Serves UI static files + tRPC API</li>
<li>No port 443/TLS by default — HTTP only on LAN</li>
<li>mDNS via avahi for <code>HOSTNAME.local</code> access</li>
</ul>
<h4>Tor (Optional)</h4>
<ul>
<li>Toggle per-system (not per-app)</li>
<li><code>tor_proxy</code> container on 10.21.21.11 (SOCKS5)</li>
<li>Each app gets a <code>tor_server</code> container creating hidden services</li>
<li>Dashboard also gets its own hidden service</li>
<li>Provides end-to-end encryption for remote access</li>
</ul>
<h4>Inter-App Communication</h4>
<ul>
<li>Via static IPs on the flat 10.21.0.0/16 bridge network</li>
<li>No DNS-based service discovery — IPs hardcoded in <code>exports.sh</code></li>
<divclass="sec-desc">Docker daemon runs as root (not rootless). Each app is a separate Docker Compose v2 project (<code>--project-name <app-id></code>). Legacy container naming: <code><app-id>_<service>_1</code> for DNS compatibility.</div>
<divclass="sec-layman">Standard Docker running with root permissions. Each app is managed as a Compose project with its own containers.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Flat Network (No Isolation)</div>
<divclass="sec-desc">Single shared bridge: <code>umbrel_main_network</code> (10.21.0.0/16). <b>All apps share one network</b>— any container can communicate with any other. Static IPs assigned per service via <code>exports.sh</code>.</div>
<divclass="sec-layman">All apps are on the same network. A compromised app could potentially reach other apps' services directly.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Per-App Auth Proxy</div>
<divclass="sec-desc">Each app gets an <code>app_proxy</code> container (<code>getumbrel/app-proxy</code>, Node.js Express) that handles JWT authentication for iframe embedding. Proxies to the actual app on its internal port.</div>
<divclass="sec-layman">Each app has a mini web server in front of it that checks your login before letting you in.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Boot Cleanup</div>
<divclass="sec-desc">On every startup: <b>stops ALL containers, prunes ALL networks</b> to prevent stale state. Pre-loads images from <code>/images/</code> (tor, auth-server baked into ISO).</div>
<divclass="sec-layman">Every reboot starts fresh by destroying all containers and recreating them. Clean but adds startup time.</div>
<divclass="sec-layman">A YAML file describing the app — what it does, what it needs, what ports it uses, and how to display it in the store.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">docker-compose.yml</div>
<divclass="sec-desc">Standard Docker Compose v3.7. Services reference <code>umbrel_main_network</code>. Images pinned by SHA256 digest. Apps define their own security constraints (no enforced capability dropping).</div>
<divclass="sec-layman">Standard Docker Compose file that defines the app's containers, networks, and volumes.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">exports.sh + hooks/</div>
<divclass="sec-desc"><code>exports.sh</code> exports environment variables (IPs, ports, credentials) for dependency resolution. <code>hooks/</code> directory with lifecycle scripts: pre/post-install, pre/post-start, pre/post-stop, pre/post-update, pre-uninstall.</div>
<divclass="sec-layman">Shell scripts that set up environment variables so apps can find each other, plus hooks that run at key lifecycle moments.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">App Store (Git repo)</div>
<divclass="sec-desc">Apps distributed via Git repository (<code>getumbrel/umbrel-apps</code>). Cloned locally, pulled every 5 minutes. Community app stores supported. <code>implements</code> field enables alternative implementations (e.g., Bitcoin Knots for Bitcoin Core).</div>
<divclass="sec-layman">The app store is just a Git repository. Umbrel checks for updates every 5 minutes by pulling the latest commits.</div>
<divclass="proto-card-desc">TypeScript-first RPC framework with end-to-end type safety. Runs over both HTTP and WebSocket on port 80.</div>
<divclass="proto-card-layman">A typed communication channel between the dashboard and the backend. If the API changes, TypeScript catches errors automatically.</div>
<divclass="proto-card-desc">Each app managed via Docker Compose v2. Install/start/stop/update handled by a bash script (app-script) calling docker compose.</div>
<divclass="proto-card-layman">Apps are defined as Docker Compose projects. A bash script handles the lifecycle by calling docker compose commands.</div>
<divclass="proto-details">
<b>Compose version:</b> v2 (docker compose plugin, not docker-compose binary)<br>
<divclass="proto-card-desc">Shell scripts that export environment variables (IPs, ports, RPC credentials). When app B depends on app A, A's exports.sh is sourced first.</div>
<divclass="proto-card-layman">Apps share their connection details through environment variables set by shell scripts.</div>
<divclass="proto-details">
<b>Variables exported:</b> IP addresses (static), ports, RPC passwords, hidden service hostnames<br>
<b>Resolution:</b> Transitive deps resolved in post-order (depth-first)<br>
<b>Alternative implementations:</b><code>settings.yml</code> can map dependency (e.g., bitcoin → bitcoin-knots)<br>
<b>Deps NOT auto-installed:</b> UI warns users to install dependencies first
<divclass="proto-card-layman">Tor is optional and runs in its own container. When enabled, each app gets its own .onion address for remote access.</div>
<divclass="proto-card-desc">JWT for API authentication. Separate "proxy tokens" validate iframe requests to app_proxy containers. bcrypt password hashing.</div>
<divclass="proto-card-layman">Login tokens that prove who you are. Separate tokens for the dashboard API and for accessing individual apps.</div>
<divclass="proto-details">
<b>API auth:</b> JWT (jsonwebtoken library)<br>
<b>Password:</b> bcrypt ($2b$, 12 rounds)<br>
<b>App auth:</b> UMBREL_PROXY_TOKEN cookie validated by app_proxy containers<br>
<divclass="proto-card-desc">App store is a Git repository cloned locally via isomorphic-git. Pulled every 5 minutes for updates.</div>
<divclass="proto-card-layman">The app catalog is just a Git repo. Umbrel checks for new apps and updates by pulling the latest commits every 5 minutes.</div>
<p>umbrelOS does not implement Web5 (DIDs, DWNs, or Verifiable Credentials).<br>Authentication uses a single-user JWT model. Per-app passwords are derived from a deterministic seed via HMAC-SHA256.</p>
</div>
</div>
<divclass="section"id="sec-umbrelos-security">
<divclass="sec-grid">
<divclass="sec-card">
<divclass="sec-title"style="color: #fca5a5;">No Disk Encryption</div>
<divclass="sec-desc">No LUKS, no dm-crypt. All data stored unencrypted on disk. Backups use Kopia with per-repository passwords. A deterministic seed (256-byte random token) derives per-app passwords via HMAC-SHA256.</div>
<divclass="sec-layman">If someone physically steals the drive, all data is readable. No encryption at rest.</div>
</div>
<divclass="sec-card">
<divclass="sec-title"style="color: #fca5a5;">Flat Network (No App Isolation)</div>
<divclass="sec-desc">All apps share one Docker bridge (10.21.0.0/16). Any container can communicate with any other container. The app_proxy adds authentication but not network isolation.</div>
<divclass="sec-layman">All apps are on the same network. A compromised app could potentially access other apps' services.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Authentication</div>
<divclass="sec-desc">Single user model. Password hashed with bcrypt ($2b$, 12 rounds). JWT tokens for API auth. Separate "proxy tokens" for app iframe auth. Optional TOTP 2FA. Session cookie: <code>UMBREL_PROXY_TOKEN</code>.</div>
</div>
<divclass="sec-card">
<divclass="sec-title">Rootful Docker</div>
<divclass="sec-desc">Docker daemon runs as root. Containers run as UID 1000 where possible, but no enforced capability dropping or security profiles. No <code>--cap-drop=ALL</code>, no <code>no-new-privileges</code> by default.</div>
<divclass="sec-layman">Docker has root access to the machine. Individual containers may or may not restrict their own privileges.</div>
<divclass="boot-title">GRUB / Rugix → Select Active Partition</div>
<divclass="boot-desc">GRUB (amd64) or tryboot (RPi) loads the kernel from the active A/B partition. Rugix commits to current partition on successful boot.</div>
<divclass="boot-desc"><b>Stops and removes ALL containers, prunes ALL networks.</b> Pre-loads images from <code>/images/</code>. Prevents stale state from previous versions.</div>
<divclass="boot-detail">Destructive reset on every boot — ensures clean state but adds startup time</div>
<divclass="boot-title">Start App Environment + All Apps</div>
<divclass="boot-desc">Starts <code>tor_proxy</code> + <code>auth</code> containers first, then all installed apps in parallel. Express HTTP server starts on port 80. App store update loop begins (every 5 min).</div>
</div>
</div>
</div>
</div>
<divclass="section"id="sec-umbrelos-data">
<divclass="path-tree"><spanclass="dir">/home/umbrel/umbrel/</span><spanclass="desc">← Main data directory (NO encryption)</span>
<spanclass="dir"> ├── umbrel.yaml</span><spanclass="desc">Main config/state (YAML file, not a database)</span>
<tdclass="bad">None (Express on :80 + per-app proxy containers)</td>
<tdclass="notes">Nginx: proven, configurable, rate limiting. Built-in: fewer moving parts. Umbrel: no central proxy means no rate limiting or security headers.</td>
<tdclass="notes">Podman: no daemon, rootless by design. LXC: heavier isolation (full system containers). Docker: rootful daemon is a larger attack surface.</td>
</tr>
<tr>
<tdclass="cmp-label">Rootless Containers</td>
<tdclass="good">Yes (all containers as UID 1000)</td>
<tdclass="notes">S9PK: most sophisticated (signed, partial downloads, delta updates). Compose: simplest for developers. Registry: fast deployment.</td>
</tr>
<tr>
<tdclass="cmp-label">Package Signing</td>
<tdclass="warn">Registry-based trust</td>
<tdclass="good">Ed25519 over blake3 merkle roots</td>
<tdclass="bad">Docker image digests only</td>
<tdclass="notes">StartOS has the strongest supply chain security. Archipelago trusts its private registry. Umbrel relies on Docker content trust.</td>
</tr>
<tr>
<tdclass="cmp-label">App Store</td>
<td>Built-in marketplace (curated)</td>
<td>Registry-based (marketplace)</td>
<td>Git repository (pulled every 5 min)</td>
<tdclass="notes">Git-based: easy for devs to contribute. Registry: more control. Curated: quality gate but slower additions.</td>
<divclass="sec-desc"><b>Strengths:</b> Package signing (S9PK), btrfs snapshots, built-in reverse proxy (fewer moving parts), WireGuard VPN, multi-arch (x86/ARM/RISC-V).<br><b>Trade-offs:</b> Tor removed in v0.4, no identity system, Angular is heavier, LXC is less container-ecosystem-compatible.</div>
<divclass="sec-desc"><b>Strengths:</b> Easiest setup, A/B OTA updates with rollback, largest app ecosystem, Git-based app store (easy contributions), React UI polish.<br><b>Trade-offs:</b> No disk encryption, flat network (no isolation), rootful Docker, no TLS, no rate limiting, no security headers, Node.js backend.</div>
"Bitcoin Knots":{tech:"A Bitcoin Core fork by Luke Dashjr with enhanced policy controls and spam filtering. Full node implementation that validates every block and transaction.",plain:"Your own copy of Bitcoin's entire ledger. It checks every transaction independently — you trust math, not people.",used:"Container: bitcoin-knots on port 8332/8333"},
"Bitcoin Core":{tech:"The reference implementation of the Bitcoin protocol. Maintains the UTXO set, validates blocks, and participates in the P2P gossip network.",plain:"The original Bitcoin software. It downloads the entire blockchain and verifies every transaction since 2009.",used:"bitcoin-knots is a fork of Bitcoin Core"},
"full node":{tech:"Software that fully validates every transaction and block against consensus rules without trusting any third party.",plain:"A computer that checks every Bitcoin transaction itself. If someone tries to cheat, your node catches it and rejects it."},
"Lightning Network":{tech:"Layer 2 payment channel network using HTLCs (Hash Time-Locked Contracts) for instant, low-fee routed payments on top of Bitcoin.",plain:"A fast-payment system built on Bitcoin. Open a 'tab' (channel) with some Bitcoin, then send thousands of instant payments through it. Settles in milliseconds, costs fractions of a penny."},
"LND":{tech:"Lightning Network Daemon — the most popular Lightning implementation. Exposes gRPC (port 10009) and REST (port 8080) APIs. Auth via macaroon bearer tokens.",plain:"The software that runs your Lightning node. Manages payment channels and routes payments across the network.",used:"Container: lnd on ports 9735/10009/8080"},
"Lightning":{tech:"Bitcoin's Layer 2 payment channel network. Uses bidirectional channels with HTLC routing (BOLT specification).",plain:"Instant Bitcoin payments. Two people deposit Bitcoin into a shared channel, then send money back and forth instantly without waiting for blockchain confirmations."},
"payment channel":{tech:"A 2-of-2 multisig Bitcoin transaction that enables off-chain payments between two parties, settled on-chain only when closed.",plain:"Like a bar tab — you deposit some Bitcoin, make unlimited fast payments, and only settle on the blockchain when you close the tab."},
"ElectrumX":{tech:"An Electrum protocol server that indexes the Bitcoin blockchain by address. Enables fast UTXO and transaction history lookups on port 50001.",plain:"An address lookup index for Bitcoin. Without it, wallet apps can't quickly check balances. With it, you get instant results from YOUR node instead of trusting a public server.",used:"Container: electrumx on port 50001"},
"Mempool":{tech:"Open-source block explorer (mempool.space). Visualizes pending transactions, fee estimates, block history. Requires: bitcoin-knots + electrumx + mariadb.",plain:"A visual dashboard for the Bitcoin blockchain. See pending transactions, fee rates, recent blocks — all from your own node, completely private.",used:"Containers: mempool-api (8999), archy-mempool-web (4080), archy-mempool-db"},
"BTCPay":{tech:"Self-hosted Bitcoin payment processor. Generates invoices, tracks payments, supports Lightning. Uses NBXplorer for chain indexing + PostgreSQL for storage.",plain:"Your own payment processing system — like Stripe or PayPal but for Bitcoin. Accept payments without middlemen or processing fees.",used:"Container: btcpay-server on port 23000"},
"BTCPay Server":{tech:"Self-hosted Bitcoin payment processor. Generates invoices, tracks payments, supports Lightning. Uses NBXplorer for chain indexing + PostgreSQL for storage.",plain:"Your own payment processing system — like Stripe or PayPal but for Bitcoin. Accept payments without middlemen or processing fees.",used:"Container: btcpay-server on port 23000"},
"NBXplorer":{tech:"Lightweight blockchain indexer for BTCPay. Tracks wallet addresses and UTXOs. Connects to Bitcoin Core via RPC.",plain:"Watches the blockchain for payments to your BTCPay addresses. When a customer pays, it tells BTCPay immediately.",used:"Container: archy-nbxplorer on port 32838"},
"Fedimint":{tech:"Federated e-cash protocol. Multi-party (m-of-n) custody with Chaumian blind-signed tokens for transaction privacy. Guardians hold BTC in multisig.",plain:"A community Bitcoin bank. A group of trusted people hold Bitcoin together and issue private digital cash to members. Nobody — not even the guardians — can see who pays whom.",used:"Containers: fedimint (8173-8175), fedimint-gateway (8176)"},
"ecash":{tech:"Chaumian blind-signed bearer tokens backed by Bitcoin in a Fedimint federation. Unlinkable — the mint cannot trace token transfers.",plain:"Digital cash that's truly private. Like physical bills — the bank that issued them can't track where they go. Backed 1:1 by real Bitcoin."},
"UTXO":{tech:"Unspent Transaction Output — Bitcoin's accounting model. Coins are tracked as discrete outputs, not account balances. Each UTXO can only be spent once.",plain:"Bitcoin doesn't have 'accounts' with balances. Instead, it tracks individual coins (outputs). Your balance is the sum of all your unspent coins."},
"BIP-39":{tech:"Bitcoin Improvement Proposal 39 — standard for encoding wallet seeds as 12 or 24 human-readable words (mnemonic phrase). Enables wallet recovery.",plain:"The 12 or 24 words that back up your Bitcoin wallet. From these words, all your keys and addresses can be regenerated. Write them down and keep them safe."},
"seed phrase":{tech:"BIP-39 mnemonic — 12 or 24 words encoding a master key from which all Bitcoin keys are derived via BIP-32 hierarchical deterministic derivation.",plain:"The master backup for your Bitcoin wallet. 12 or 24 ordinary English words that can recreate all your Bitcoin keys."},
"PSBT":{tech:"Partially Signed Bitcoin Transaction (BIP-174). A standardized format for constructing transactions that can be signed by multiple parties or hardware wallets.",plain:"A way to build a Bitcoin transaction in steps. Create it on one device, sign it on a hardware wallet, broadcast from another. Multi-step security."},
"txindex":{tech:"Transaction index — a database that maps every transaction ID to its location in the blockchain. Enables lookups by txid. Requires full (non-pruned) blockchain.",plain:"A search index that lets you look up any Bitcoin transaction instantly by its ID. Only works with the full blockchain (not pruned)."},
"pruning":{tech:"Discarding old block data after validation. Saves disk space while still fully validating the blockchain. Bitcoin Core prunes blocks older than a configurable threshold.",plain:"Your node validates every transaction but deletes the old raw data afterwards to save disk space. The validation still happened — you just don't keep a copy of every old block."},
"rpcauth":{tech:"Bitcoin Core authentication method using salted HMAC-SHA256. The password hash is stored in bitcoin.conf, never the plaintext password.",plain:"How the backend securely authenticates to Bitcoin Core. The password is stored as a mathematical hash — never in readable form."},
"multisig":{tech:"Multi-signature — requires M of N keys to authorize a transaction (e.g., 3-of-5). Used by Fedimint guardians and advanced wallets.",plain:"A Bitcoin vault that needs multiple keys to open — like a safe deposit box needing 3 out of 5 people to agree before funds can move."},
// Infrastructure & Containers
"Podman":{tech:"Daemonless, rootless container engine. Drop-in Docker replacement. Runs containers as unprivileged user. Uses NetAvark for networking.",plain:"The engine that runs all the app containers. Like Docker but more secure — doesn't need administrator privileges, so a compromised container can't take over the machine.",used:"Runs as user 'archipelago' (UID 1000)"},
"container":{tech:"An isolated process with its own filesystem, network namespace, and resource limits. Shares the host kernel. Managed by Podman using OCI images.",plain:"A sealed room for running one app. Each container has its own files and network, can't see other containers, and has memory limits. If one crashes, the others keep running."},
"rootless":{tech:"Containers running as unprivileged user (UID 1000) with user namespace mapping. Even container root (UID 0) maps to unprivileged host UID.",plain:"Containers run as a regular user, not as administrator. Even if an attacker breaks out of a container, they're just a normal user — not root."},
"archy-net":{tech:"A Podman bridge network connecting all Bitcoin-stack containers. Provides DNS resolution by container name (e.g., 'bitcoin-knots' resolves to its IP).",plain:"A private network connecting Bitcoin-related containers so they can find each other by name. Isolated from standalone app containers.",used:"Members: bitcoin-knots, electrumx, lnd, mempool-*, btcpay-*, fedimint-*"},
"bridge network":{tech:"A virtual L2 network segment (NetAvark). Containers on the same bridge get DNS resolution and can communicate. Isolated from other bridges.",plain:"A virtual cable connecting containers together. Containers on the same bridge can talk to each other using names instead of IP addresses."},
"Nginx":{tech:"High-performance reverse proxy and web server. Listens on ports 80/443, terminates TLS, rate-limits requests, adds security headers, routes /app/* to containers.",plain:"The front door to your server. Every web request goes through Nginx, which figures out which app you want and forwards you there. Also handles HTTPS encryption and blocks bad traffic.",used:"Ports 80 (HTTP) + 443 (HTTPS)"},
"reverse proxy":{tech:"A server that accepts client requests and forwards them to backend services. Handles TLS termination, load balancing, caching, and security headers.",plain:"A receptionist that directs visitors to the right office. You go to one address (your server) and the proxy figures out which app you want based on the URL."},
"systemd":{tech:"Linux init system (PID 1) and service manager. Manages service lifecycle, dependencies, restart policies, resource limits, sandboxing, and timers.",plain:"The conductor of the orchestra. It starts everything in the right order, restarts things that crash, and runs scheduled maintenance tasks."},
"Debian":{tech:"Debian 12 (Bookworm) — stable Linux distribution. Minimal debootstrap install with only required packages.",plain:"The operating system under everything. Chosen for rock-solid stability and long-term security updates."},
// Networking & Privacy
"Tor":{tech:"The Onion Router — anonymity network routing traffic through 3+ relay hops. Creates .onion hidden services for inbound connectivity without IP exposure.",plain:"Routes your traffic through multiple random computers worldwide so nobody can trace it back to you. Creates secret .onion addresses for your services.",used:"Hidden services for: UI, Bitcoin P2P, ElectrumX, LND, BTCPay"},
"hidden service":{tech:"A Tor service accessible via a .onion address. Uses rendezvous-based routing so the server's IP is never revealed. Keys stored on encrypted partition.",plain:"A secret address for your server that works globally without revealing where it physically is. Like a PO Box that forwards to your house without giving out your address."},
".onion":{tech:"Tor hidden service address — a 56-character Base32 string derived from the service's Ed25519 public key. Accessed only through the Tor network.",plain:"A Tor address — a long string of characters ending in .onion. It's your server's anonymous identity on the Tor network."},
"Tailscale":{tech:"Zero-config mesh VPN built on WireGuard. Peer-to-peer encrypted tunnels with NAT traversal. DERP relay fallback.",plain:"A modern VPN that connects your devices into a private network. Access your server from your phone anywhere in the world. No port forwarding needed.",used:"Container: tailscale on host network"},
"WireGuard":{tech:"Modern VPN protocol. UDP-based, ~4000 lines of code. ChaCha20-Poly1305 encryption, Curve25519 key exchange. Minimal attack surface.",plain:"A fast, simple VPN protocol used by Tailscale. Much faster and more secure than older VPN technologies."},
"TLS":{tech:"Transport Layer Security — encrypts HTTP traffic (HTTPS). Archipelago uses a self-signed certificate (2048-bit RSA, 10-year validity).",plain:"The padlock icon in your browser. Encrypts the connection between your browser and the server so nobody on the network can eavesdrop."},
"HTTPS":{tech:"HTTP over TLS. Nginx listens on port 443 with a self-signed certificate. HSTS header forces future visits to use HTTPS.",plain:"Encrypted web traffic. The 'S' in HTTPS means your connection is scrambled — nobody between you and the server can read it."},
// Protocols
"JSON-RPC":{tech:"Remote Procedure Call encoded as JSON over HTTP POST. Request: {method, params}. Response: {result} or {error}. Single endpoint: /rpc/v1.",plain:"A simple way for the dashboard to ask the backend to do things. Send 'call system.stats', get back the numbers. All through one URL.",used:"194+ methods at POST /rpc/v1"},
"WebSocket":{tech:"Full-duplex TCP connection (RFC 6455). Server pushes JSON Patch (RFC 6902) deltas. 30s ping, 5min timeout. Endpoint: /ws/db.",plain:"A permanent open phone line between your browser and the server. Instead of constantly asking 'what changed?', the server tells you instantly when something happens."},
"gRPC":{tech:"Google's RPC framework using HTTP/2 + Protocol Buffers binary serialization. Bidirectional streaming. Much faster than JSON-based APIs.",plain:"A high-speed way for programs to talk to each other. Uses compact binary format instead of text. The backend uses it to control LND.",used:"Backend → LND on port 10009"},
"JSON Patch":{tech:"RFC 6902 — a format for describing changes to a JSON document. Operations: add, remove, replace, move, copy. Used by WebSocket for incremental state updates.",plain:"Instead of sending the entire system state every time something changes, the server sends just the tiny piece that changed. Like saying 'change CPU to 42%' instead of resending everything."},
"CBOR":{tech:"Concise Binary Object Representation (RFC 8949). Like JSON but binary-encoded. 2-5x smaller. Used for mesh radio messages where bandwidth is precious.",plain:"A compact way to pack data. Critical for radio communication where you can only send a few bytes per second."},
// Security
"LUKS":{tech:"Linux Unified Key Setup v2. Full-disk encryption with AES-256-XTS (AES-NI) or ChaCha20-Adiantum fallback. argon2id key derivation.",plain:"The lock on your data partition. Scrambles everything so only your machine can read it. Uses the best encryption your CPU supports.",used:"Partition 4 → /var/lib/archipelago/"},
"LUKS2":{tech:"Linux Unified Key Setup v2. Full-disk encryption with AES-256-XTS (AES-NI) or ChaCha20-Adiantum fallback. argon2id key derivation.",plain:"The lock on your data partition. Scrambles everything so only your machine can read it. Uses the best encryption your CPU supports.",used:"Partition 4 → /var/lib/archipelago/"},
"AES-NI":{tech:"Advanced Encryption Standard New Instructions — CPU hardware acceleration for AES operations. Available on most x86 CPUs since 2010.",plain:"A feature in modern processors that makes encryption extremely fast — almost free in terms of CPU usage."},
"argon2id":{tech:"Memory-hard password hashing function. Resists GPU/ASIC brute-force by requiring significant RAM during key derivation.",plain:"A password-strengthening technique that's intentionally slow and memory-hungry. Makes it impractical for attackers to guess your encryption key even with powerful hardware."},
"RBAC":{tech:"Role-Based Access Control. Three roles: Admin (all 194+ methods), Viewer (read-only subset), AppUser (minimal). Explicit allowlist per role, not deny list.",plain:"A permission system. Admins can do everything. Viewers can only look. AppUsers get limited features. Each role has an explicit list of what it can do."},
"CSRF":{tech:"Cross-Site Request Forgery — attack where malicious site triggers actions on your server. Mitigated with HMAC-SHA256 token derived from session, sent in X-CSRF-Token header.",plain:"A trick where a bad website tries to make your browser do things on your server. The CSRF token is a secret code that proves the request comes from the real dashboard."},
"macaroon":{tech:"Capability-based bearer token with embedded caveats (restrictions). Used by LND. Can be attenuated (restricted further) without server involvement.",plain:"A permission slip for Lightning. The admin macaroon can do everything; you can create a read-only version that only checks balances. Like making a key that only opens one door."},
"rate limiting":{tech:"Per-IP sliding window throttle on sensitive endpoints. Financial ops: 3-10 per 5min. Auth: 5 failures per 60s. Federation: 5-30 per 60s.",plain:"Prevents abuse by limiting how often you can do something. Login: 5 tries per minute. Send Bitcoin: 5 times per 5 minutes. Stops brute-force attacks cold."},
// Identity & Social
"DID":{tech:"Decentralized Identifier (W3C standard). A URI that resolves to a DID Document containing public keys and service endpoints. No central registry needed.",plain:"A digital identity you create and control yourself. No company can delete it, no platform can ban it. Like a self-issued passport backed by cryptography."},
"Nostr":{tech:"Notes and Other Stuff Transmitted by Relays. Decentralized social protocol using Ed25519-signed events over WebSocket. NIP standards define features.",plain:"A decentralized social media protocol. You sign your posts with your cryptographic key, publish to relay servers that anyone can run. No single company controls the network."},
"Verifiable Credentials":{tech:"W3C VC standard. JSON-LD format with Ed25519 proof. Cryptographically signed claims that can be verified without contacting the issuer.",plain:"Digital proof that someone vouches for something. Like a digitally signed certificate — anyone can verify it's real without calling the issuer."},
"NIP-04":{tech:"Nostr Implementation Possibility 04 — deprecated encrypted direct message standard using shared ECDH key.",plain:"An older way to send private messages on Nostr. Being replaced by NIP-44 which is more secure."},
"NIP-44":{tech:"Modern Nostr encrypted DM standard with forward secrecy and padding. Uses XChaCha20-Poly1305.",plain:"The new, more secure way to send private messages on Nostr."},
// Mesh & Federation
"federation":{tech:"A cluster of Archipelago nodes with trust relationships. Nodes share state, deploy apps, and communicate over Tor. Three trust levels: Trusted, Observer, Untrusted.",plain:"A team of Archipelago servers that work together. They share health status, can install apps on each other, and form a resilient network."},
"LoRa":{tech:"Long Range radio — sub-GHz ISM band. Low bandwidth (~300 bps), long range (5-15 km). Mesh topology with store-and-forward.",plain:"A type of radio that sends small messages over very long distances (up to 15 km) without internet or cell towers. For truly off-grid communication."},
"mesh networking":{tech:"Peer-to-peer radio network where nodes relay messages for each other. Uses CBOR encoding, X3DH handshake, and Double Ratchet encryption.",plain:"Nodes talk to each other over radio and relay messages for each other, extending range. Like a bucket brigade — each node passes messages along until they reach the destination."},
"Double Ratchet":{tech:"Forward-secret key agreement protocol (Signal). Per-message key derivation from a ratcheting chain. Compromising one key cannot decrypt past messages.",plain:"The encryption behind Signal. Every message gets a unique key, and old keys are destroyed. Even if someone steals your key tomorrow, they can't read yesterday's messages."},
"X3DH":{tech:"Extended Triple Diffie-Hellman — key agreement protocol for establishing encrypted sessions. Used to bootstrap Double Ratchet sessions.",plain:"A secure handshake. Two devices exchange math problems to agree on a secret key without ever sending the key itself. The starting point for encrypted messaging."},
// Apps
"Vaultwarden":{tech:"Lightweight Bitwarden-compatible password manager server. Rust implementation. Stores encrypted vaults locally.",plain:"Self-hosted password manager. Compatible with all Bitwarden apps (phone, browser extension). Your passwords are stored on YOUR server, not someone else's cloud.",used:"Container: vaultwarden on port 8082"},
"Nextcloud":{tech:"Self-hosted productivity suite — file sync (WebDAV), calendar (CalDAV), contacts (CardDAV), document editing, and collaboration.",plain:"Your own Google Drive + Google Calendar + Google Contacts. Sync files across devices, share folders, edit documents. All on your hardware.",used:"Container: nextcloud on port 8085"},
"Jellyfin":{tech:"Open-source media server. Organizes and streams video/audio/photo libraries. DLNA support. No account or subscription required.",plain:"Self-hosted Netflix. Organize and stream your movies, TV shows, and music to any device. Free, no tracking, no subscriptions.",used:"Container: jellyfin on port 8096"},
"PhotoPrism":{tech:"AI-powered photo management with TensorFlow-based object detection, face recognition, and EXIF-based organization.",plain:"AI-powered photo organizer. It automatically tags, categorizes, and makes your photos searchable — like Google Photos but running on your hardware.",used:"Container: photoprism on port 2342"},
"Grafana":{tech:"Monitoring and visualization platform. Dashboards for time-series data. Supports Prometheus, InfluxDB, and other data sources.",plain:"Beautiful real-time graphs showing how your server is doing — CPU usage, disk space, Bitcoin sync progress, container health.",used:"Container: grafana on port 3000"},
"Home Assistant":{tech:"Home automation platform. Supports 2000+ IoT device integrations. Local processing, no cloud dependency.",plain:"Smart home control center. Control lights, thermostats, cameras, and sensors from one interface — all running locally, no Amazon/Google cloud needed.",used:"Container: homeassistant on port 8123"},
"SearXNG":{tech:"Privacy-respecting metasearch engine. Proxies queries to 70+ search engines without revealing user identity.",plain:"Private search engine. It searches Google, Bing, and DuckDuckGo on your behalf without them knowing who you are.",used:"Container: searxng on port 8888"},
"OnlyOffice":{tech:"Document server for collaborative editing of Office formats (.docx, .xlsx, .pptx). Integrates with Nextcloud.",plain:"Like Google Docs but self-hosted. Edit Word, Excel, and PowerPoint files right in your browser.",used:"Container: onlyoffice on port 9980"},
"Ollama":{tech:"Local LLM inference engine. Runs quantized models (Llama, Mistral, etc.) on CPU or GPU. REST API on port 11434.",plain:"Run AI chatbots locally on your hardware. Your prompts never leave your machine — truly private AI.",used:"Container: ollama on port 11434"},
"Uptime Kuma":{tech:"Self-hosted monitoring tool. Pings services, tracks response times, sends alerts via webhook, email, or push notifications.",plain:"Checks if your services are online and alerts you when something goes down. Your own personal Pingdom.",used:"Container: uptime-kuma on port 3001"},
"FileBrowser":{tech:"Web-based file manager with upload/download, sharing, and user management. Serves the Cloud storage area.",plain:"Manage your files through a browser. Upload, download, and organize documents, photos, and media.",used:"Container: filebrowser on port 8083"},
"Portainer":{tech:"Container management web UI. Visualizes running containers, logs, networks, and volumes.",plain:"A visual dashboard for your containers. See what's running, check logs, restart things — without needing the command line.",used:"Container: portainer on port 9000"},
"Penpot":{tech:"Open-source design platform (Figma alternative). 5-container stack: frontend, backend, exporter, PostgreSQL, Valkey on penpot-net.",plain:"Design tool like Figma but self-hosted. Create UI mockups, graphics, and prototypes in your browser.",used:"Container stack on penpot-net, port 9001"},
"IndeedHub":{tech:"Decentralized media platform. 7-container stack: Next.js frontend, API, PostgreSQL, Redis, MinIO (S3), FFmpeg, Nostr relay.",plain:"Decentralized YouTube. Host and stream videos without centralized platforms. Uses Nostr for discovery and Bitcoin for monetization.",used:"Container stack on bridge, port 7777"},
"Immich":{tech:"Self-hosted photo/video backup with ML-based face recognition and object detection. 3-container stack with vector-enabled PostgreSQL.",plain:"Google Photos replacement with AI features. Automatically backs up and organizes your photos from your phone.",used:"Container stack on bridge, port 2283"},
"DWN":{tech:"Decentralized Web Node (W3C standard). Personal data store with DID-based access control. Stores structured data with protocol schemas.",plain:"A personal database that YOU own. Apps request permission to read/write data. You control access with your decentralized identity."},
// Infra
"MariaDB":{tech:"MySQL-compatible relational database. Fork of MySQL with enhanced performance. Used by Mempool for block/tx data.",plain:"A database that stores structured data in tables (like a powerful spreadsheet). Mempool uses it to cache blockchain data for fast lookups.",used:"Container: archy-mempool-db"},
"PostgreSQL":{tech:"Advanced relational database with ACID compliance, JSON support, and extensibility. Used by BTCPay, IndeedHub, Penpot, Immich.",plain:"A powerful database used by several apps to store their data reliably. Known for being rock-solid and feature-rich.",used:"Containers: archy-btcpay-db, indeedhub-postgres, penpot-postgres, immich_postgres"},
"Redis":{tech:"In-memory key-value store. Sub-millisecond reads. Used for caching, session storage, and message queuing.",plain:"A super-fast notepad that apps use to remember things temporarily. Instead of reading from disk, frequently needed data is kept in RAM.",used:"Container: indeedhub-redis"},
"Valkey":{tech:"Open-source Redis fork maintained by the Linux Foundation. API-compatible drop-in replacement.",plain:"An open-source clone of Redis. Functionally identical, just under a different license.",used:"Container: penpot-valkey, immich_redis"},
"MinIO":{tech:"S3-compatible object storage server. High-performance, supports multipart uploads and bucket policies.",plain:"Stores media files (videos, images) using the same API as Amazon S3 — but running on your hardware. Apps built for S3 work with it automatically.",used:"Container: indeedhub-minio"},
"GRUB":{tech:"GRand Unified Bootloader. Stage 2 bootloader supporting BIOS (i386-pc) and UEFI (x86_64-efi). Loads Linux kernel + initramfs.",plain:"The first program that runs when you turn on the computer. It shows a menu and loads the operating system. Works on both old and new hardware."},
"squashfs":{tech:"Compressed read-only filesystem. Used by the installer to pack the live environment into a single file on the ISO.",plain:"A compressed package of the installer's temporary operating system. Boots entirely from RAM."},
"GPT":{tech:"GUID Partition Table — modern disk partitioning scheme. Supports disks >2TB, up to 128 partitions. Used by Archipelago's auto-installer.",plain:"The modern way to divide a hard drive into sections. Supports large disks and is more reliable than the older MBR format."},
"debootstrap":{tech:"Tool that installs a Debian base system into a subdirectory. Used to build the minimal Archipelago root filesystem.",plain:"A tool that creates a minimal Debian system from scratch — only the packages you need, nothing extra."},
"ext4":{tech:"Fourth Extended Filesystem — the most common Linux filesystem. Journaled, supports files up to 16TB.",plain:"The standard filesystem used by Linux. Reliable, fast, and battle-tested on millions of servers."},
// Protocols & Crypto
"Ed25519":{tech:"Edwards-curve Digital Signature Algorithm using Curve25519. 128-bit security, fast signing/verification, small keys (32 bytes).",plain:"A modern digital signature method. Used to sign messages and prove identity. Very fast and secure."},
"HMAC-SHA256":{tech:"Hash-based Message Authentication Code using SHA-256. Provides message integrity and authentication.",plain:"A way to verify that a message hasn't been tampered with and came from the expected sender."},
"secp256k1":{tech:"Elliptic curve used by Bitcoin for public key cryptography. Also used by Nostr for event signing.",plain:"The mathematical curve that Bitcoin uses for its signatures. Also used by Nostr for signing social media posts."},
"Noise protocol":{tech:"Framework for building encrypted transport protocols. Used by Lightning P2P (port 9735) and WireGuard.",plain:"An encryption framework used by Lightning and WireGuard. Like TLS but simpler and more flexible."},
// Web5 / Identity
"did:key":{tech:"Self-resolving DID method where the public key is encoded directly in the identifier. Format: did:key:z6Mk... (multicodec Ed25519 in base58btc). No external resolution needed.",plain:"A digital identity that IS your cryptographic key. Like a self-addressed envelope — the identity carries its own proof. Works offline, instant, free."},
"did:dht":{tech:"DID method that publishes DID Documents to BitTorrent's Mainline DHT using BEP-44 signed mutable items. Format: did:dht:z... (z-base-32 encoded Ed25519 pubkey).",plain:"A digital identity published to the BitTorrent network. Anyone in the world can look you up without a central registry."},
"DWN":{tech:"Decentralized Web Node (W3C/DIF draft). Personal data store with protocol-governed records, DID-based auth, and peer sync. Implements Records interface (Write/Read/Query/Delete).",plain:"A personal database that YOU own. Apps request permission to read/write data. You control access with your decentralized identity."},
"Verifiable Credential":{tech:"W3C standard (VC Data Model 2.0). Cryptographically signed claims from an Issuer about a Subject. Includes proof (Ed25519Signature2020), expiration, and revocation status.",plain:"A digital certificate that proves something about you — signed by an issuer, verifiable by anyone without contacting the issuer. Like a digitally signed diploma."},
"Web5":{tech:"Decentralized web platform combining DIDs + DWNs + Verifiable Credentials. Initiated by TBD (Block/Jack Dorsey), shut down Nov 2024. Core specs (DID, VC) are W3C standards. Open source donated to DIF.",plain:"A vision for the decentralized web where you own your identity and data. Built on open standards, not tokens or blockchains."},
"Patch-DB":{tech:"Custom database used by StartOS. CBOR-encoded with diff-based reactive sync over WebSocket. Backend pushes deltas, frontend applies them in real-time.",plain:"StartOS's custom database that automatically syncs changes to the UI in real-time, sending only what changed instead of everything."},
// Comparison systems
"LXC":{tech:"Linux Containers — OS-level virtualization using kernel namespaces and cgroups. Full system containers (not app containers like Docker/Podman). Used by StartOS.",plain:"A way to run isolated Linux environments that look like full virtual machines but share the host kernel. Heavier than Docker but more isolated."},
"Docker":{tech:"Container platform using OCI images. Daemon-based (dockerd runs as root). Default for umbrelOS. Docker Compose v2 for multi-container apps.",plain:"The most popular container tool. Runs apps in isolated environments. Requires a background service running as root (unlike Podman which is rootless)."},
"tRPC":{tech:"TypeScript-first RPC framework. End-to-end type safety between server and client without code generation. Used by umbrelOS for its API.",plain:"A way for the frontend and backend to communicate with full type safety — if the API changes, TypeScript catches errors automatically."},
"S9PK":{tech:"StartOS package format v2. Signed merkle archive with Ed25519 signatures over blake3 roots. Contains: manifest.json, JavaScript service code (squashfs), container images per architecture, assets, icon.",plain:"StartOS's app package format. Each package is cryptographically signed and contains everything needed to run the app."},
"Rugix":{tech:"A/B partition update system used by umbrelOS (formerly Rugpi). Writes OS updates to inactive partition, swaps on reboot, automatic rollback if boot fails.",plain:"A safe OS update system. Updates install to a backup partition. If the update breaks, it automatically reverts to the working version."},
"btrfs":{tech:"B-tree filesystem with copy-on-write (COW), snapshots, checksums, and compression. Used by StartOS for safe app installs via instant volume snapshots.",plain:"A modern filesystem that can take instant snapshots of your data. StartOS uses this to safely roll back failed app updates."},
// Container & OS Technology
"OCI":{tech:"Open Container Initiative \u2014 industry standard for container image formats and runtimes. Docker, Podman, and containerd all use OCI images.",plain:"A universal standard for containers. Like how USB works with any device \u2014 OCI means containers work with any compatible runtime."},
"OverlayFS":{tech:"Union filesystem that layers a writable directory on top of a read-only base. Changes are stored in the upper layer without modifying the lower. Used by Docker and LXC.",plain:"A layered filesystem \u2014 like putting a transparent sheet over a picture. You can draw on it without changing the original underneath."},
"AppArmor":{tech:"Linux Mandatory Access Control (MAC) framework. Restricts what programs can do via per-application security profiles. Used by StartOS for LXC container isolation.",plain:"A security guard for each app. It has a rulebook saying exactly what the app is allowed to touch \u2014 files, network, devices \u2014 and blocks everything else."},
"Docker Compose":{tech:"Tool for defining and running multi-container Docker applications via YAML files. Each app becomes a 'project' with its own containers, networks, and volumes.",plain:"A recipe file for running multiple containers together. You describe what you need in YAML, and Compose creates and connects everything."},
"user namespaces":{tech:"Linux kernel feature that maps container UIDs to different host UIDs. Container root (UID 0) can map to an unprivileged host user (e.g., UID 100000), preventing privilege escalation.",plain:"A trick that makes container apps think they're running as admin, but they're actually a regular user on the host. If they escape, they have no real power."},
"UID mapping":{tech:"The translation table between container user IDs and host user IDs in user namespaces. E.g., container UID 0 \u2192 host UID 100000, container UID 70 \u2192 host UID 100070.",plain:"A translation table for user identities between inside and outside a container. Container 'root' becomes a nobody on the host machine."},
"capability dropping":{tech:"Linux security mechanism that removes specific privileges (capabilities) from processes. --cap-drop=ALL removes everything, then --cap-add adds back only what's needed.",plain:"Instead of giving an app all admin powers, you take away everything and only give back the specific abilities it actually needs. Like a hotel keycard that only opens your room."},
"veth":{tech:"Virtual Ethernet \u2014 a pair of connected virtual network interfaces. One end goes inside the container, the other connects to a bridge on the host. Used for container networking.",plain:"A virtual network cable connecting a container to the host. Like plugging an Ethernet cable between two computers, but entirely in software."},
"A/B partitions":{tech:"Dual root partition scheme for atomic OS updates. Updates install to the inactive partition; on reboot the system switches to it. If boot fails, it reverts to the previous partition.",plain:"Two copies of the operating system on disk. Updates go to the spare copy. If it works, great \u2014 if not, it automatically switches back to the good copy."},
"rootful":{tech:"Container runtime where the daemon runs as root (UID 0). Docker is rootful by default. If a container escape occurs, the attacker gains root access on the host.",plain:"The container manager runs with full admin access. Simpler to set up, but if something breaks out of a container, it has full control of the machine."},
// Web Standards & Certificates
"ACME":{tech:"Automatic Certificate Management Environment \u2014 protocol for automated TLS certificate issuance (used by Let's Encrypt). Verifies domain ownership via challenges (HTTP-01, DNS-01, TLS-ALPN-01).",plain:"A system that automatically gets and renews HTTPS certificates for free. Let's Encrypt uses it to prove you own a domain and issue a certificate."},
"SNI":{tech:"Server Name Indication \u2014 TLS extension where the client sends the requested hostname at the start of the handshake. Allows one server/IP to serve different certificates for different domains.",plain:"Tells the web server which website you want before the encrypted connection starts. This lets one server host multiple HTTPS sites on one IP address."},
"mDNS":{tech:"Multicast DNS \u2014 resolves hostnames on local networks without a DNS server. Devices announce themselves as name.local (e.g., archipelago.local). Implemented by Avahi on Linux, Bonjour on macOS.",plain:"How your phone finds your node on the local network by name (like archipelago.local) without any DNS server. Devices announce themselves automatically."},
// Cryptography
"blake3":{tech:"Modern cryptographic hash function. Extremely fast (parallelizable, SIMD-optimized), outputs 256-bit hashes. Used by StartOS for S9PK merkle roots and package integrity verification.",plain:"A very fast way to create a unique fingerprint of data. Used to verify that app packages haven't been tampered with."},
"merkle tree":{tech:"Binary tree where each leaf is a hash of a data block and each node is a hash of its children. The root hash verifies the integrity of all data. Enables partial verification without downloading everything.",plain:"A tree-shaped structure of checksums. If you have the top checksum, you can verify any piece of data in the tree without checking everything else."},
"BEP-44":{tech:"BitTorrent Enhancement Proposal 44 \u2014 defines mutable and immutable data storage in the BitTorrent Mainline DHT. Mutable items are signed with Ed25519 and can be updated.",plain:"A way to store and update small pieces of data on the BitTorrent network. Used by did:dht to publish your identity where anyone can find it."},
"Mainline DHT":{tech:"BitTorrent's Distributed Hash Table \u2014 a global peer-to-peer network of millions of nodes storing key-value pairs. No central server. Used by did:dht for decentralized identity publishing.",plain:"A massive worldwide peer-to-peer network (used by BitTorrent). Millions of computers work together to store and look up small pieces of data without any central server."},
"z-base-32":{tech:"Human-friendly base32 encoding variant that avoids visually ambiguous characters (0/O, 1/l). Used to encode Ed25519 public keys in did:dht identifiers.",plain:"A way to write binary data using only letters and numbers, carefully chosen so you can't confuse similar-looking characters."},
"multicodec":{tech:"Self-describing encoding prefix that identifies the type and format of data. E.g., 0xed01 = Ed25519 public key. Used in did:key to make keys self-identifying.",plain:"A tiny label at the start of data that says what kind of data it is. Like a file extension, but built into the data itself."},
"base58btc":{tech:"Base58 encoding as used by Bitcoin. Removes ambiguous characters (0, O, l, I) from base64. Used for did:key identifiers (z-prefixed multibase).",plain:"A way to write binary data using letters and numbers, minus the confusing ones. The same encoding used for Bitcoin addresses."},
"ChaCha20-Poly1305":{tech:"Authenticated encryption cipher (AEAD). ChaCha20 encrypts, Poly1305 authenticates. Fast on CPUs without hardware AES. Used by WireGuard and Noise protocol.",plain:"An encryption method that's both fast and secure, especially on devices without special encryption hardware. Used by VPN connections."},
"ChaCha20-Adiantum":{tech:"Wide-block encryption mode combining ChaCha20 and AES for disk encryption. Fast on CPUs without AES-NI hardware acceleration. Archipelago's LUKS fallback cipher.",plain:"A disk encryption method for computers that don't have special encryption hardware. Just as secure as AES, but works fast on any processor."},
// Frontend Frameworks
"Angular":{tech:"Google's TypeScript-first web framework. Component-based, opinionated (routing, forms, HTTP, i18n built-in). Heavier than React/Vue but more batteries-included. Used by StartOS.",plain:"A comprehensive web framework by Google. Like a fully furnished apartment \u2014 everything is built in. Bigger but you don't need to choose your own tools."},
"React":{tech:"Meta's JavaScript UI library. Component-based, virtual DOM, unidirectional data flow. Lightweight core with ecosystem of add-on libraries. Used by umbrelOS.",plain:"A popular UI toolkit by Meta (Facebook). Flexible and widely used. You pick your own tools for routing, state management, and styling."},
"Vue":{tech:"Progressive JavaScript framework. Template-based, reactive data binding, single-file components. Lighter than Angular, more opinionated than React. Used by Archipelago.",plain:"A web framework that's easy to learn and incrementally adopt. Templates feel natural if you know HTML. Used by Archipelago's dashboard."},
"Vite":{tech:"Modern frontend build tool using native ES modules for instant dev server startup and fast HMR (Hot Module Replacement). Replaces webpack. Used by Archipelago and umbrelOS.",plain:"A build tool that makes web development fast. Instead of bundling everything on each change, it serves files directly and updates instantly."},
"Tailwind":{tech:"Utility-first CSS framework. Classes like 'p-4 text-white bg-blue-500' applied directly in HTML. No custom CSS needed for most styling. Rapid UI development.",plain:"A CSS toolkit where you style elements by adding utility classes directly in the HTML. Like Lego bricks for styling \u2014 compose small pieces into any design."},
"Pinia":{tech:"Official state management library for Vue 3. Type-safe, devtools-integrated, modular stores. Successor to Vuex. Used by Archipelago.",plain:"A data management system for Vue apps. Stores information (like which apps are running) in an organized way that any component can access."},
"Zustand":{tech:"Lightweight React state management library. Simple API, minimal boilerplate, supports middleware and devtools. Used by umbrelOS.",plain:"A simple data store for React apps. Lets different parts of the UI share and react to the same data without complicated setup."},
// Backend
"Express":{tech:"Minimalist Node.js web framework. Handles HTTP routing, middleware, and static file serving. De facto standard for Node.js servers. Used by umbrelOS.",plain:"The most popular web server framework for Node.js. Simple and flexible \u2014 most Node.js web applications are built on it."},
"Axum":{tech:"Rust web framework built on tokio and hyper. Type-safe routing, middleware via tower, async by default. Used by StartOS (startd) for its built-in web server.",plain:"A modern Rust web framework. Fast, safe, and async \u2014 used by StartOS to serve its entire web interface from the Rust backend."},
"Tokio":{tech:"Async runtime for Rust. Provides task scheduling, I/O, timers, and synchronization primitives. The foundation for most async Rust applications.",plain:"The engine that powers async Rust code. Handles thousands of concurrent tasks efficiently \u2014 like a traffic controller for network operations."},
// Auth & Security
"JWT":{tech:"JSON Web Token \u2014 compact, URL-safe token format for transmitting claims between parties. Base64-encoded header.payload.signature. Used by umbrelOS for API authentication.",plain:"A digital pass that proves who you are. The server creates it when you log in, and you show it with every request. The signature prevents tampering."},
"bcrypt":{tech:"Password hashing function with built-in salt and configurable cost factor. Deliberately slow to resist brute-force attacks. umbrelOS uses $2b$ variant with 12 rounds.",plain:"A way to store passwords safely. It's intentionally slow \u2014 fast enough for login, but too slow for an attacker to guess millions of passwords."},
"TOTP":{tech:"Time-based One-Time Password (RFC 6238). Generates 6-digit codes that change every 30 seconds from a shared secret. Used for two-factor authentication (2FA).",plain:"The 6-digit codes from your authenticator app that change every 30 seconds. Even if someone steals your password, they can't log in without the code."},
// Tools
"Kopia":{tech:"Open-source backup tool with encryption, deduplication, and compression. Supports local, cloud, and network storage. Used by umbrelOS for encrypted backups to external drives.",plain:"A backup program that encrypts your data, removes duplicates to save space, and can back up to external drives or cloud storage."},
"isomorphic-git":{tech:"Pure JavaScript implementation of Git. Runs in Node.js and browsers without native git binary. Used by umbrelOS to clone and pull the app store repository.",plain:"Git written entirely in JavaScript. Lets umbrelOS manage its app store repository without needing the regular git program installed."},
"Zod":{tech:"TypeScript-first schema validation library. Defines data shapes and validates at runtime. Used by umbrelOS for validating app manifests and API inputs.",plain:"A tool that checks if data has the right shape and types. Like a bouncer checking IDs \u2014 rejects malformed data before it causes problems."},
// Data & Sync
"binary diffs":{tech:"Efficient encoding of changes between two versions of data. Only the differences are transmitted, not the full state. CBOR-encoded diffs are 2-5x smaller than JSON equivalents.",plain:"Instead of sending all the data every time something changes, only the tiny difference is sent. Like telling someone 'change word 5' instead of resending the whole paragraph."},
"CBOR diffs":{tech:"Differential updates encoded in CBOR (Concise Binary Object Representation). Patch-DB uses these over WebSocket for real-time state sync between backend and frontend.",plain:"Compact binary change-packets that the backend pushes to the browser. Much smaller than JSON \u2014 critical for keeping the UI in sync without wasting bandwidth."},
"COW":{tech:"Copy-on-Write \u2014 filesystem optimization where data is only copied when modified. Original data stays intact. Enables instant, space-efficient snapshots. Core feature of btrfs and ZFS.",plain:"When you modify a file, the filesystem writes the change to a new location instead of overwriting the original. This makes instant backups (snapshots) possible."},
"DAG-CBOR":{tech:"CBOR encoding for directed acyclic graphs. Used by DWN for content-addressed data structures. Messages are encoded as DAG-CBOR with CID (Content Identifier) references.",plain:"A compact binary format for linked data structures. Each piece of data gets a unique address based on its content, making verification automatic."}
}
// Sort by length descending so longer terms match first ("Bitcoin Knots" before "Bitcoin")
