archy/CLAUDE.md

CLAUDE.md — Archipelago (Archy)

Overview

Archipelago is a Bitcoin Node OS — bootable, self-sovereign personal server. Flash to USB, install on hardware, manage via web UI.

Stack: Rust backend + Vue 3 + TypeScript (strict) + Vite 7 + Tailwind + Pinia + Podman on Debian 12 Version: 0.1.0 | Target: x86_64 and ARM64

---

Beta Freeze (2026-03-18)

Phase 1: Feature Testing (internal) — WE ARE HERE

Feature set is LOCKED. Only: bug fixes, security hardening, ISO build fixes, UI polish, testing. No new features, no new apps, no new deps, no scope creep.

Track: docs/BETA-PROGRESS.md | Checklist: docs/BETA-RELEASE-CHECKLIST.md

---

Quick Reference

cd neode-ui && npm start          # Local dev (mock backend :5959, Vite :8100)
cd neode-ui && npm run build      # Build (outputs to web/dist/neode-ui/)
./scripts/deploy-to-target.sh --live  # Deploy to live server (.228)

Infrastructure

What	Where
Dev server	192.168.1.228 (SSH key: ~/.ssh/archipelago-deploy)
Secondary	192.168.1.198
Git remote	git.tx1138.com (remote name: tx1138)
App registry	80.71.235.15:3000/archipelago/ (HTTP, insecure)
CI runner	act_runner on .228, workflow: .gitea/workflows/build-iso.yml
ISO builds	FileBrowser at http://192.168.1.228:8083 → Builds/
SSH creds	Gitignored scripts/deploy-config.sh
Web password	password123

Architecture

Debian 12
  ├── Podman (rootless, user archipelago)
  ├── Nginx (80/443 → backend, app proxies)
  ├── Rust Backend (core/) on 127.0.0.1:5678
  │     ├── core/archipelago/     — Binary, RPC, auth, sessions
  │     └── core/container/       — PodmanClient, manifests, health
  └── Vue.js UI (neode-ui/)
        ├── src/api/rpc-client.ts — All backend communication
        ├── src/stores/           — Pinia state
        ├── src/views/            — Pages
        └── src/style.css         — ALL styling (global classes only)

Data paths: /var/lib/archipelago/{app-id}/ (data), /opt/archipelago/web-ui/ (frontend), /usr/local/bin/archipelago (binary)

Critical Rules

1. Never build Rust on macOS — deploy script handles cross-compilation via rsync + remote build
2. Always deploy after changes — ./scripts/deploy-to-target.sh --live
3. Frontend builds to web/dist/neode-ui/ — not neode-ui/dist/
4. Container images: scripts/image-versions.sh is the single source of truth. All scripts use $*_IMAGE variables, never hardcoded registry paths.
5. Type-check before committing — cd neode-ui && npx vue-tsc -b --noEmit

Frontend

• <script setup lang="ts"> always — no Options API
• Global CSS in style.css — never inline Tailwind
• .glass-button for ALL buttons — .gradient-button is BANNED
• .glass-card for containers, .path-option-card for interactive cards
• translateZ(0) + isolation: isolate on glass elements (Chromium compositor fix)
• Pinia for state, typed RPC client, handle loading/error/empty states

Backend (Rust)

• No unwrap()/expect() — use ? with .context()
• tracing for logging, never println! or log secrets
• Backend binds 127.0.0.1 only — nginx handles external access
• Validate all input before path construction — reject .., /, null bytes
• tokio runtime, timeouts on all external ops

Security (Post-Pentest)

• RBAC: explicit method allowlists, never prefix matching
• Session cookies: SameSite=Lax; HttpOnly; Path=/
• Rate-limit auth endpoints, rotate tokens after privilege escalation
• Validate redirect URLs with isLocalRedirect(), never v-html with user input
• Container security: drop ALL caps, add only required, no-new-privileges, memory limits, health checks
• See .claude/rules/ for detailed crypto, API, container, and Bitcoin rules

ISO Build & CI

CI builds on every push to main via git.tx1138.com Actions.

# Manual build on .228:
ssh archipelago@192.168.1.228
cd ~/archy/image-recipe
sudo UNBUNDLED=1 DEV_SERVER=localhost BUILD_FROM_SOURCE=0 ./build-auto-installer-iso.sh

Debugging fresh installs — SSH in and check:

cat /var/log/archipelago-install.log              # Full installer output
cat /var/log/archipelago-first-boot-diagnostics.log  # Service status, nginx, LUKS, etc.
sudo archipelago-diagnostics                       # Re-run diagnostics anytime

Kiosk: X11 on VT7, console on VT1. Ctrl+Alt+F1 for terminal, Ctrl+Alt+F7 for kiosk. Toggle: sudo archipelago-kiosk enable|disable|toggle

App Integration Checklist

When adding/fixing apps, check ALL of these:

• core/archipelago/src/api/rpc/package/ — config, capabilities, deps
• neode-ui/src/views/marketplace/marketplaceData.ts — marketplace entry
• image-recipe/configs/nginx-archipelago.conf — proxy rules (HTTP + HTTPS)
• scripts/image-versions.sh — pinned image version
• scripts/first-boot-containers.sh — first boot creation
• scripts/deploy-to-target.sh — deploy logic

Git

Commits: type: description (feat:, fix:, docs:, refactor:, test:, chore:, perf:) Push to: git push tx1138 main