archy/CLAUDE.md

CLAUDE.md — Archipelago (Archy) Project Guide

Project Overview

Archipelago is a Bitcoin Node OS — a bootable, self-sovereign personal server you flash to USB, install on hardware, and manage via a web UI. Similar to Umbrel/Start9/RaspiBlitz but custom-built with production-grade security.

Stack: Rust backend + Vue 3 (Composition API) + TypeScript (strict) + Vite 7 + Tailwind CSS + Pinia + Podman Target OS: Debian 12 (Bookworm) — x86_64 and ARM64 Current version: 0.1.0

---

BETA FREEZE — ACTIVE (2026-03-18)

Goal: Ship a flawless beta that works perfectly on every machine we install it on.

We are in beta stabilization mode. The current feature set is LOCKED. Every session must push toward this goal.

Pipeline

PHASE 1: Feature Testing (internal)     ← WE ARE HERE
    ↓  Gate: every feature works, bugs fixed, security hardened, ISO verified
PHASE 2: User Testing (real users on real hardware we don't control)
    ↓  Gate: user-reported issues resolved, telemetry shows stable fleet
PHASE 3: Beta Live (public release)

What IS allowed

• Bug fixes for existing features
• Security hardening and testing
• Beta telemetry / node reporting (TASK-12 — needed for user testing)
• UI/layout rearrangements (moving things around, improving flow)
• Boot screen completion (FEATURE-4 — already in progress)
• Testing all features end-to-end on fresh installs
• Performance and reliability improvements to existing code
• ISO build hardening

What is NOT allowed

• New features (watch-only wallet, mesh balance check, etc. are POST-BETA)
• New app integrations
• New backend modules or RPC endpoints (unless fixing existing bugs or beta telemetry)
• New dependencies (unless required for beta infrastructure)
• Scope creep of any kind

Status tracking

• Progress tracker: docs/BETA-PROGRESS.md — updated every session
• Beta checklist: docs/BETA-RELEASE-CHECKLIST.md — the acceptance criteria
• Master plan: docs/MASTER_PLAN.md — phased roadmap (Phase 1/2/3)

Session protocol

1. Read docs/BETA-PROGRESS.md at start of every session
2. Report current phase and status before starting work
3. Work only on current-phase items
4. Update docs/BETA-PROGRESS.md at end of every session with what changed

---

Quick Reference

# Frontend local dev (mock backend on :5959, Vite on :8100)
cd neode-ui && npm start

# Deploy to live server (frontend + backend + restart services)
./scripts/deploy-to-target.sh --live

# Deploy to both servers
./scripts/deploy-to-target.sh --both

# Frontend build (outputs to web/dist/neode-ui/)
cd neode-ui && npm run build

# Type-check frontend
cd neode-ui && npm run type-check

# Rust checks (run on dev server, NOT macOS)
cargo clippy --all-targets --all-features
cargo fmt --all
cargo test --all-features

Dev server: http://192.168.1.228 | Local frontend: http://localhost:8100 (password: password123)

Architecture

Debian 12 (Bookworm)
  ├── Podman (rootless containers)
  ├── Nginx (port 80 → proxies /rpc/, /ws/, /health to backend)
  ├── Rust Backend (core/) — binary on port 5678
  │     ├── core/archipelago/     — Main binary, RPC endpoints
  │     ├── core/container/       — PodmanClient, manifest parser, dependency resolver, health monitor
  │     ├── core/security/        — AppArmor profiles, secrets manager, Cosign image verifier
  │     ├── core/performance/     — Resource manager
  │     └── core/parmanode/       — Parmanode compatibility layer
  └── Vue.js UI (neode-ui/)
        ├── src/api/              — RPC client (rpc-client.ts), WebSocket, container client
        ├── src/stores/           — Pinia stores
        ├── src/views/            — Page components
        ├── src/components/       — Reusable components
        ├── src/router/           — Vue Router
        ├── src/types/            — TypeScript type definitions
        └── src/style.css         — Global styles + Tailwind utilities

Data Paths (Server)

• App data: /var/lib/archipelago/{app-id}/
• Secrets: /var/lib/archipelago/secrets/{app-id}/ (encrypted)
• Frontend: /opt/archipelago/web-ui/
• Backend binary: /usr/local/bin/archipelago
• Systemd service: /etc/systemd/system/archipelago.service
• Nginx config: /etc/nginx/sites-available/archipelago

CRITICAL Workflow Rules

1. NEVER Build Rust on macOS for Linux

Always rsync source to the Linux dev server and build there. Building on macOS and copying the binary causes Exec format errors.

# Deploy does this automatically:
./scripts/deploy-to-target.sh --live

2. Always Deploy After Changes

After editing code (frontend, backend, scripts, or configs), deploy to the live server. Do not leave deployment to the user.

3. Frontend Build Output Path

Frontend builds to web/dist/neode-ui/ — NOT neode-ui/dist/.

4. Deploy-Test-Fix Loop

1. Make the change
2. Deploy with ./scripts/deploy-to-target.sh --live
3. Test at http://192.168.1.228
4. If broken, fix and redeploy — repeat until working
5. End loop only when everything works

5. SSH Access

• Primary: archipelago@192.168.1.228 — password: EwPDR8q45l0Upx@
• Secondary: archipelago@192.168.1.198
• Credentials stored in gitignored scripts/deploy-config.sh

sshpass -p 'EwPDR8q45l0Upx@' ssh -o StrictHostKeyChecking=no archipelago@192.168.1.228

Frontend Rules (Vue.js + TypeScript)

Component Standards

• Always <script setup lang="ts"> — never Options API, never plain JS
• Pinia for all state management — focused single-purpose stores
• TypeScript strict mode — no any, use unknown or proper types
• Export types from dedicated .types.ts files
• Use type guards for runtime type checking

Styling — Global Classes Only

• ALWAYS create global utility classes in neode-ui/src/style.css
• NEVER use inline Tailwind classes directly in components
• Use semantic class names: .glass-card, .glass-button, .gradient-button, .path-option-card

API Client Rules

• Use @/api/rpc-client.ts for RPC calls, @/api/container-client.ts for containers
• NEVER hardcode API endpoints — use environment variables
• Handle loading states, error states, retry logic for all async operations

CSS Class Hierarchy

Class	Use	Hover
.path-option-card	Section containers, interactive cards (Settings-style)	Lifts -2px
.glass-card	Content containers, modals, panels	No
.info-card	Status badges, metric displays	No
.info-card-button	Action buttons inside info sections	Lifts, brightens
bg-black/20 rounded-xl border border-white/10	Info sub-cards inside sections	No
bg-white/5	Simple read-only info rows	No
.glass-button	ALL buttons (primary and secondary)	Subtle brighten
.path-action-button	Large action buttons (Logout, Continue)	Lifts -2px

BANNED Classes — Do NOT Use

• .gradient-button — REMOVED. Use .glass-button instead. The gradient style breaks the clean glass aesthetic.
• .gradient-card / .gradient-card-dark — REMOVED. Use .glass-card or .path-option-card instead.

Design Tokens

• Font: Avenir Next (primary), Montserrat (font-archipelago)
• Spacing: 4px grid system, 16px default padding
• Glassmorphism: background: rgba(0,0,0,0.60), backdrop-filter: blur(24px), inset 0 1px 0 rgba(255,255,255,0.22)
• Transitions: all 0.3s ease standard, translateY(-2px) hover, translateY(1px) active
• Accent orange (Bitcoin): #fb923c — #f59e0b
• Green (success): #4ade80 | Red (danger): #ef4444 | Blue (info): #3b82f6
• Text: rgba(255,255,255,0.9) primary, rgba(255,255,255,0.6-0.7) muted

Tailwind Custom Values

• Blur: backdrop-blur-glass (18px), backdrop-blur-glass-strong (24px)
• Colors: glass-dark (0,0,0,0.35), glass-darker (0,0,0,0.6), glass-border (255,255,255,0.18)
• Shadows: shadow-glass, shadow-glass-inset

Backend Rules (Rust)

Error Handling

• No unwrap() or expect() in production code — use ? operator
• thiserror for library error types, anyhow for application errors
• Custom error types per module: {module}::Error
• Include context: .context("What failed and why")

RPC Endpoints

• Use rpc_toolkit::command macro for all endpoints
• Use #[context] ctx: RpcContext for context
• Return Result<T, Error> — validate all inputs before processing

Async & Runtime

• tokio runtime only — never mix with other async runtimes
• Set timeouts on all external operations
• Use select! for racing futures with timeouts
• Handle shutdown gracefully with cancellation tokens

Code Organization

• New modules in core/{module-name}/, add to core/Cargo.toml members
• snake_case for all modules/files
• Run cargo clippy --all-targets --all-features and cargo fmt --all before commits

Logging

• Use tracing for structured logging — never println!
• Never log secrets, passwords, keys, or tokens
• Include context: tracing::info!(user_id = %id, "Action")

Container & Security

App Manifests

• All manifests in apps/{app-id}/manifest.yml
• Follow spec in docs/app-manifest-spec.md
• Use archipelago_container::PodmanClient — NEVER call Docker directly

Security Requirements (Non-Negotiable)

• ALWAYS readonly_root: true unless explicitly needed
• ALWAYS drop all capabilities, add only required ones
• ALWAYS run as non-root user (UID > 1000)
• ALWAYS no-new-privileges: true
• NEVER use latest tag — pin specific image versions
• NEVER hardcode secrets — use core/security/secrets_manager.rs

App Icons

Single source of truth: neode-ui/public/assets/img/app-icons/ Naming: {app-id}.{png|webp|svg} — do not duplicate elsewhere.

Security Standards (Post-Pentest — Mandatory)

These rules come from a full penetration test (33 findings, all remediated). Follow them for ALL new code.

Backend (Rust)

• Backend binds to 127.0.0.1 ONLY — never 0.0.0.0. All external access goes through nginx.
• Validate ALL user input before path construction — reject .., /, \, null bytes. Use the existing validate_app_id() pattern in tor.rs.
• Never pass user input to sudo commands — if unavoidable, validate strictly against an allowlist of characters [a-zA-Z0-9_-].
• Every HTTP endpoint that returns sensitive data MUST check authentication — use self.is_authenticated(&headers).await or be in UNAUTHENTICATED_METHODS with justification.
• Rate-limit authentication endpoints — extract_client_ip() must only trust X-Real-IP from the loopback interface (127.0.0.1).
• Federation messages require ed25519 signatures — never accept unsigned peer-joined messages.
• RBAC: use explicit allowlists, not prefix matching — method.starts_with("node.") is BANNED. List exact methods per role.
• Session cookies: SameSite=Lax; HttpOnly; Path=/ — Strict breaks iframe app fetches. Lax still prevents CSRF on POST.
• Destructive operations require password re-verification — factory reset, onboarding reset, identity export.
• Remember-me secrets: use OsRng random bytes — never derive from /etc/machine-id or other public data.
• Rotate session tokens after privilege escalation — TOTP verification must issue a new token, invalidating the pending one.
• Tar archive extraction: validate every entry path — never use archive.unpack(). Iterate entries and verify no .. components or paths escaping the target directory.

Frontend (Vue/TypeScript)

• Validate redirect URLs — use isLocalRedirect() from router/index.ts before any window.location.href assignment. Reject javascript:, protocol-relative (//), and external URLs.
• Never use v-html with user input — if unavoidable, always sanitize with DOMPurify.sanitize().
• CSP: no unsafe-inline in script-src — Vite builds don't need it. Keep unsafe-inline only in style-src for Tailwind.

Nginx

• Session validation: $cookie_session (not $cookie_session_id) — cookie name must match the Rust backend's session= cookie.
• Prefer auth_request over cookie-presence checks — if ($cookie_session = "") only checks presence, not validity. For sensitive endpoints, use nginx auth_request to validate against the backend.
• All /app/* proxies are unauthenticated at nginx level — each app must handle its own auth. Never expose apps with default credentials (change Grafana admin/admin on first boot, etc.).

SSRF Prevention

• Validate all user-supplied URLs — require https:// scheme, reject private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1, fc00::/7).
• Disable redirect following — use redirect(Policy::none()) on reqwest clients that fetch user-supplied URLs.
• Onion addresses: validate v3 format — exactly 56 base32 [a-z2-7] chars + .onion.
• Webhook URLs: parse with Url::parse — don't split on : for host extraction (breaks IPv6).

Container Security

• Memory limits on every container — use --memory=$(mem_limit <name>) pattern from first-boot-containers.sh. Prevents one container from OOM-killing the system.
• Health checks on every container — define via --health-cmd in podman run.
• User-stopped tracking — when a user stops a container via UI, record in user-stopped.json so crash recovery and health monitor don't auto-restart it.

Code Quality

• Zero compiler warnings (Rust and TypeScript)
• Zero linter errors (clippy, eslint)
• Functions under 50 lines, single responsibility
• Comment WHY not WHAT — code should be self-documenting
• Remove dead code entirely — never comment it out
• No TODO/FIXME in commits — fix now or create issues
• Workspace-relative paths only — NEVER hardcode /Users/dorian/...

Git Conventions

Commit Format

type: description

Types: feat:, fix:, docs:, refactor:, test:, chore:, perf:

Rules

• Atomic commits — one logical change per commit
• main branch always production-ready
• Feature branches: feature/description, bug fixes: fix/description
• Never commit secrets, .env files, or credentials
• Tag releases: v1.2.3 (SemVer)

App Integration Checklist

When adding or fixing apps, every file below must be checked. Missing any one causes failures on fresh installs.

Backend (Rust)

• core/archipelago/src/api/rpc/package.rs — get_app_config(): ports, volumes, env vars, custom args
• core/archipelago/src/api/rpc/package.rs — needs_archy_net: add if app needs container DNS
• core/archipelago/src/api/rpc/package.rs — get_app_capabilities(): add required caps (CHOWN, etc.)
• core/archipelago/src/api/rpc/package.rs — dependency checks (e.g., electrs requires bitcoin)
• core/archipelago/src/container/docker_packages.rs — get_app_metadata(): title, description, icon, repo
• core/archipelago/src/container/docker_packages.rs — UI address mapping (e.g., http://localhost:50002)

Frontend (Vue)

• neode-ui/src/views/Marketplace.vue — getCuratedAppList(): marketplace entry with dockerImage
• neode-ui/src/stores/appLauncher.ts — port-to-proxy mapping (if app has custom UI port)
• neode-ui/src/views/AppDetails.vue — route ID mapping (if app ID differs from container name)

Nginx

• image-recipe/configs/nginx-archipelago.conf — /app/{id}/ proxy in HTTP block
• image-recipe/configs/snippets/archipelago-https-app-proxies.conf — /app/{id}/ proxy in HTTPS block
• Any custom status endpoints (e.g., /electrs-status) proxied before the SPA catch-all

Deploy & First Boot

• scripts/deploy-to-target.sh — container creation/update logic
• scripts/first-boot-containers.sh — container created on fresh ISO install
• Custom UI containers (e.g., electrs-ui): built and started in both deploy and first-boot

ISO Build

• image-recipe/build-auto-installer-iso.sh — CAPTURE_PATTERNS: image captured from live server
• image-recipe/build-auto-installer-iso.sh — CONTAINER_IMAGES: fallback image pulled from registry
• image-recipe/build-auto-installer-iso.sh — docker UI source files bundled for build fallback
• image-recipe/build-auto-installer-iso.sh — installer copies files to target disk

Runtime Verification

• Test the app UI loads on its configured port
• Auto-connect dependencies (Bitcoin RPC, LND, etc.) — apps must work out of the box
• Most apps launch in iframe; BTCPay (23000) and Home Assistant (8123) open in new tab (X-Frame-Options)

ISO Build

Build on the target server (has all dependencies):

ssh archipelago@192.168.1.228
cd ~/archy/image-recipe
sudo ./build-auto-installer-iso.sh
# Result: results/archipelago-auto-installer-*.iso

After testing on live server, always update ISO build to include changes. Sync system configs:

• archipelago.service → image-recipe/configs/
• nginx-archipelago.conf → image-recipe/configs/

Key Documentation

• docs/architecture.md — System architecture
• docs/current-state.md — Current development phase
• docs/development-setup.md — Local dev setup
• docs/app-manifest-spec.md — YAML manifest spec
• BUILD-GUIDE.md — ISO build guide
• DEPLOYMENT.md — Deployment details
• CHANGELOG.md — Version history