feat: support preferred external ports besides 443

.claude/settings.json

@@ -1,5 +1 @@
-{
-  "attribution": {
-    "commit": ""
-  }
-}
+{}

.github/workflows/startos-iso.yaml

@@ -25,10 +25,13 @@ on:
           - ALL
           - x86_64
           - x86_64-nonfree
+          - x86_64-nvidia
           - aarch64
           - aarch64-nonfree
+          - aarch64-nvidia
           # - raspberrypi
           - riscv64
+          - riscv64-nonfree
       deploy:
         type: choice
         description: Deploy
@@ -65,10 +68,13 @@ jobs:
             fromJson('{
               "x86_64": ["x86_64"],
               "x86_64-nonfree": ["x86_64"],
+              "x86_64-nvidia": ["x86_64"],
               "aarch64": ["aarch64"],
               "aarch64-nonfree": ["aarch64"],
+              "aarch64-nvidia": ["aarch64"],
               "raspberrypi": ["aarch64"],
               "riscv64": ["riscv64"],
+              "riscv64-nonfree": ["riscv64"],
               "ALL": ["x86_64", "aarch64", "riscv64"]
             }')[github.event.inputs.platform || 'ALL']
           }}
@@ -125,7 +131,7 @@ jobs:
               format(
                 '[
                   ["{0}"],
-                  ["x86_64", "x86_64-nonfree", "aarch64", "aarch64-nonfree", "riscv64"]
+                  ["x86_64", "x86_64-nonfree", "x86_64-nvidia", "aarch64", "aarch64-nonfree", "aarch64-nvidia", "riscv64", "riscv64-nonfree"]
                 ]',
                 github.event.inputs.platform || 'ALL'
               )
@@ -139,18 +145,24 @@ jobs:
             fromJson('{
               "x86_64": "ubuntu-latest",
               "x86_64-nonfree": "ubuntu-latest",
+              "x86_64-nvidia": "ubuntu-latest",
               "aarch64": "ubuntu-24.04-arm",
               "aarch64-nonfree": "ubuntu-24.04-arm",
+              "aarch64-nvidia": "ubuntu-24.04-arm",
               "raspberrypi": "ubuntu-24.04-arm",
               "riscv64": "ubuntu-24.04-arm",
+              "riscv64-nonfree": "ubuntu-24.04-arm",
             }')[matrix.platform],
             fromJson('{
               "x86_64": "buildjet-8vcpu-ubuntu-2204",
               "x86_64-nonfree": "buildjet-8vcpu-ubuntu-2204",
+              "x86_64-nvidia": "buildjet-8vcpu-ubuntu-2204",
               "aarch64": "buildjet-8vcpu-ubuntu-2204-arm",
               "aarch64-nonfree": "buildjet-8vcpu-ubuntu-2204-arm",
+              "aarch64-nvidia": "buildjet-8vcpu-ubuntu-2204-arm",
               "raspberrypi": "buildjet-8vcpu-ubuntu-2204-arm",
               "riscv64": "buildjet-8vcpu-ubuntu-2204",
+              "riscv64-nonfree": "buildjet-8vcpu-ubuntu-2204",
             }')[matrix.platform]
           )
         )[github.event.inputs.runner == 'fast']
@@ -161,10 +173,13 @@ jobs:
           fromJson('{
             "x86_64": "x86_64",
             "x86_64-nonfree": "x86_64",
+            "x86_64-nvidia": "x86_64",
             "aarch64": "aarch64",
             "aarch64-nonfree": "aarch64",
+            "aarch64-nvidia": "aarch64",
             "raspberrypi": "aarch64",
             "riscv64": "riscv64",
+            "riscv64-nonfree": "riscv64",
           }')[matrix.platform]
         }}
     steps:

.gitignore

@@ -21,4 +21,4 @@ secrets.db
 /build/lib/firmware
 tmp
 web/.i18n-checked
-agents/USER.md
+docs/USER.md

ARCHITECTURE.md

@@ -0,0 +1,101 @@
+# Architecture
+
+StartOS is an open-source Linux distribution for running personal servers. It manages discovery, installation, network configuration, backups, and health monitoring of self-hosted services.
+
+## Tech Stack
+
+- Backend: Rust (async/Tokio, Axum web framework)
+- Frontend: Angular 20 + TypeScript + TaigaUI
+- Container runtime: Node.js/TypeScript with LXC
+- Database/State: Patch-DB (git submodule) - storage layer with reactive frontend sync
+- API: JSON-RPC via rpc-toolkit (see `core/rpc-toolkit.md`)
+- Auth: Password + session cookie, public/private key signatures, local authcookie (see `core/src/middleware/auth/`)
+
+## Project Structure
+
+```bash
+/
+├── assets/              # Screenshots for README
+├── build/               # Auxiliary files and scripts for deployed images
+├── container-runtime/   # Node.js program managing package containers
+├── core/                # Rust backend: API, daemon (startd), CLI (start-cli)
+├── debian/              # Debian package maintainer scripts
+├── image-recipe/        # Scripts for building StartOS images
+├── patch-db/            # (submodule) Diff-based data store for frontend sync
+├── sdk/                 # TypeScript SDK for building StartOS packages
+└── web/                 # Web UIs (Angular)
+```
+
+## Components
+
+- **`core/`** — Rust backend daemon. Produces a single binary `startbox` that is symlinked as `startd` (main daemon), `start-cli` (CLI), `start-container` (runs inside LXC containers), `registrybox` (package registry), and `tunnelbox` (VPN/tunnel). Handles all backend logic: RPC API, service lifecycle, networking (DNS, ACME, WiFi, Tor, WireGuard), backups, and database state management. See [core/ARCHITECTURE.md](core/ARCHITECTURE.md).
+
+- **`web/`** — Angular 20 + TypeScript workspace using Taiga UI. Contains three applications (admin UI, setup wizard, VPN management) and two shared libraries (common components/services, marketplace). Communicates with the backend exclusively via JSON-RPC. See [web/ARCHITECTURE.md](web/ARCHITECTURE.md).
+
+- **`container-runtime/`** — Node.js runtime that runs inside each service's LXC container. Loads the service's JavaScript from its S9PK package and manages subcontainers. Communicates with the host daemon via JSON-RPC over Unix socket. See [container-runtime/CLAUDE.md](container-runtime/CLAUDE.md).
+
+- **`sdk/`** — TypeScript SDK for packaging services for StartOS (`@start9labs/start-sdk`). Split into `base/` (core types, ABI definitions, effects interface, consumed by web as `@start9labs/start-sdk-base`) and `package/` (full SDK for service developers, consumed by container-runtime as `@start9labs/start-sdk`).
+
+- **`patch-db/`** — Git submodule providing diff-based state synchronization. Uses CBOR encoding. Backend mutations produce diffs that are pushed to the frontend via WebSocket, enabling reactive UI updates without polling. See [patch-db repo](https://github.com/Start9Labs/patch-db).
+
+## Build Pipeline
+
+Components have a strict dependency chain. Changes flow in one direction:
+
+```
+Rust (core/)
+  → cargo test exports ts-rs types to core/bindings/
+    → rsync copies to sdk/base/lib/osBindings/
+      → SDK build produces baseDist/ and dist/
+        → web/ consumes baseDist/ (via @start9labs/start-sdk-base)
+        → container-runtime/ consumes dist/ (via @start9labs/start-sdk)
+```
+
+Key make targets along this chain:
+
+| Step | Command | What it does |
+|---|---|---|
+| 1 | `cargo check -p start-os` | Verify Rust compiles |
+| 2 | `make ts-bindings` | Export ts-rs types → rsync to SDK |
+| 3 | `cd sdk && make baseDist dist` | Build SDK packages |
+| 4 | `cd web && npm run check` | Type-check Angular projects |
+| 5 | `cd container-runtime && npm run check` | Type-check runtime |
+
+**Important**: Editing `sdk/base/lib/osBindings/*.ts` alone is NOT sufficient — you must rebuild the SDK bundle (step 3) before web/container-runtime can see the changes.
+
+## Cross-Layer Verification
+
+When making changes across multiple layers (Rust, SDK, web, container-runtime), verify in this order:
+
+1. **Rust**: `cargo check -p start-os` — verifies core compiles
+2. **TS bindings**: `make ts-bindings` — regenerates TypeScript types from Rust `#[ts(export)]` structs
+   - Runs `./core/build/build-ts.sh` to export ts-rs types to `core/bindings/`
+   - Syncs `core/bindings/` → `sdk/base/lib/osBindings/` via rsync
+   - If you manually edit files in `sdk/base/lib/osBindings/`, you must still rebuild the SDK (step 3)
+3. **SDK bundle**: `cd sdk && make baseDist dist` — compiles SDK source into packages
+   - `baseDist/` is consumed by `/web` (via `@start9labs/start-sdk-base`)
+   - `dist/` is consumed by `/container-runtime` (via `@start9labs/start-sdk`)
+   - Web and container-runtime reference the **built** SDK, not source files
+4. **Web type check**: `cd web && npm run check` — type-checks all Angular projects
+5. **Container runtime type check**: `cd container-runtime && npm run check` — type-checks the runtime
+
+## Data Flow: Backend to Frontend
+
+StartOS uses Patch-DB for reactive state synchronization:
+
+1. The backend mutates state via `db.mutate()`, producing CBOR diffs
+2. Diffs are pushed to the frontend over a persistent WebSocket connection
+3. The frontend applies diffs to its local state copy and notifies observers
+4. Components watch specific database paths via `PatchDB.watch$()`, receiving updates reactively
+
+This means the UI is always eventually consistent with the backend — after any mutating API call, the frontend waits for the corresponding PatchDB diff before resolving, so the UI reflects the result immediately.
+
+## Further Reading
+
+- [core/ARCHITECTURE.md](core/ARCHITECTURE.md) — Rust backend architecture
+- [web/ARCHITECTURE.md](web/ARCHITECTURE.md) — Angular frontend architecture
+- [container-runtime/CLAUDE.md](container-runtime/CLAUDE.md) — Container runtime details
+- [core/rpc-toolkit.md](core/rpc-toolkit.md) — JSON-RPC handler patterns
+- [core/s9pk-structure.md](core/s9pk-structure.md) — S9PK package format
+- [docs/exver.md](docs/exver.md) — Extended versioning format
+- [docs/VERSION_BUMP.md](docs/VERSION_BUMP.md) — Version bumping guide

CLAUDE.md

@@ -2,142 +2,55 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Project Overview
+## Architecture
 
-StartOS is an open-source Linux distribution for running personal servers. It manages discovery, installation, network configuration, backups, and health monitoring of self-hosted services.
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full system architecture, component map, build pipeline, and cross-layer verification order.
 
-**Tech Stack:**
-- Backend: Rust (async/Tokio, Axum web framework)
-- Frontend: Angular 20 + TypeScript + TaigaUI
-- Container runtime: Node.js/TypeScript with LXC
-- Database/State: Patch-DB (git submodule) - storage layer with reactive frontend sync
-- API: JSON-RPC via rpc-toolkit (see `agents/rpc-toolkit.md`)
-- Auth: Password + session cookie, public/private key signatures, local authcookie (see `core/src/middleware/auth/`)
+Each major component has its own `CLAUDE.md` with detailed guidance: `core/`, `web/`, `container-runtime/`, `sdk/`.
 
 ## Build & Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
 - Environment setup and requirements
 - Build commands and make targets
 - Testing and formatting commands
 - Environment variables
 
 **Quick reference:**
+
 ```bash
 . ./devmode.sh                            # Enable dev mode
 make update-startbox REMOTE=start9@<ip>   # Fastest iteration (binary + UI)
 make test-core                            # Run Rust tests
 ```
 
-## Architecture
-
-### Core (`/core`)
-The Rust backend daemon. Main binaries:
-- `startbox` - Main daemon (runs as `startd`)
-- `start-cli` - CLI interface
-- `start-container` - Runs inside LXC containers; communicates with host and manages subcontainers
-- `registrybox` - Registry daemon
-- `tunnelbox` - VPN/tunnel daemon
-
-**Key modules:**
-- `src/context/` - Context types (RpcContext, CliContext, InitContext, DiagnosticContext)
-- `src/service/` - Service lifecycle management with actor pattern (`service_actor.rs`)
-- `src/db/model/` - Patch-DB models (`public.rs` synced to frontend, `private.rs` backend-only)
-- `src/net/` - Networking (DNS, ACME, WiFi, Tor via Arti, WireGuard)
-- `src/s9pk/` - S9PK package format (merkle archive)
-- `src/registry/` - Package registry management
-
-**RPC Pattern:** See `agents/rpc-toolkit.md`
-
-### Web (`/web`)
-Angular projects sharing common code:
-- `projects/ui/` - Main admin interface
-- `projects/setup-wizard/` - Initial setup
-- `projects/start-tunnel/` - VPN management UI
-- `projects/shared/` - Common library (API clients, components)
-- `projects/marketplace/` - Service discovery
-
-**Development:**
-```bash
-cd web
-npm ci
-npm run start:ui        # Dev server with mocks
-npm run build:ui        # Production build
-npm run check           # Type check all projects
-```
-
-### Container Runtime (`/container-runtime`)
-Node.js runtime that manages service containers via RPC. See `RPCSpec.md` for protocol.
-
-**Container Architecture:**
-```
-LXC Container (uniform base for all services)
-└── systemd
-    └── container-runtime.service
-        └── Loads /usr/lib/startos/package/index.js (from s9pk javascript.squashfs)
-            └── Package JS launches subcontainers (from images in s9pk)
-```
-
-The container runtime communicates with the host via JSON-RPC over Unix socket. Package JavaScript must export functions conforming to the `ABI` type defined in `sdk/base/lib/types.ts`.
-
-**`/media/startos/` directory (mounted by host into container):**
-
-| Path | Description |
-|------|-------------|
-| `volumes/<name>/` | Package data volumes (id-mapped, persistent) |
-| `assets/` | Read-only assets from s9pk `assets.squashfs` |
-| `images/<name>/` | Container images (squashfs, used for subcontainers) |
-| `images/<name>.env` | Environment variables for image |
-| `images/<name>.json` | Image metadata |
-| `backup/` | Backup mount point (mounted during backup operations) |
-| `rpc/service.sock` | RPC socket (container runtime listens here) |
-| `rpc/host.sock` | Host RPC socket (for effects callbacks to host) |
-
-**S9PK Structure:** See `agents/s9pk-structure.md`
-
-### SDK (`/sdk`)
-TypeScript SDK for packaging services (`@start9labs/start-sdk`).
-
-- `base/` - Core types, ABI definitions, effects interface (`@start9labs/start-sdk-base`)
-- `package/` - Full SDK for package developers, re-exports base
+## Operating Rules
 
-### Patch-DB (`/patch-db`)
-Git submodule providing diff-based state synchronization. Changes to `db/model/public.rs` automatically sync to the frontend.
-
-**Key patterns:**
-- `db.peek().await` - Get a read-only snapshot of the database state
-- `db.mutate(|db| { ... }).await` - Apply mutations atomically, returns `MutateResult`
-- `#[derive(HasModel)]` - Derive macro for types stored in the database, generates typed accessors
-
-**Generated accessor types** (from `HasModel` derive):
-- `as_field()` - Immutable reference: `&Model<T>`
-- `as_field_mut()` - Mutable reference: `&mut Model<T>`
-- `into_field()` - Owned value: `Model<T>`
-
-**`Model<T>` APIs** (from `db/prelude.rs`):
-- `.de()` - Deserialize to `T`
-- `.ser(&value)` - Serialize from `T`
-- `.mutate(|v| ...)` - Deserialize, mutate, reserialize
-- For maps: `.keys()`, `.as_idx(&key)`, `.as_idx_mut(&key)`, `.insert()`, `.remove()`, `.contains_key()`
+- Always verify cross-layer changes using the order described in [ARCHITECTURE.md](ARCHITECTURE.md#cross-layer-verification)
+- Check component-level CLAUDE.md files for component-specific conventions. ALWAYS read it before operating on that component.
+- Follow existing patterns before inventing new ones
+- Always use `make` recipes when they exist for testing builds rather than manually invoking build commands
 
 ## Supplementary Documentation
 
-The `agents/` directory contains detailed documentation for AI assistants:
+The `docs/` directory contains cross-cutting documentation for AI assistants:
 
 - `TODO.md` - Pending tasks for AI agents (check this first, remove items when completed)
 - `USER.md` - Current user identifier (gitignored, see below)
-- `rpc-toolkit.md` - JSON-RPC patterns and handler configuration
-- `core-rust-patterns.md` - Common utilities and patterns for Rust code in `/core` (guard pattern, mount guards, etc.)
-- `s9pk-structure.md` - S9PK package format structure
-- `i18n-patterns.md` - Internationalization key conventions and usage in `/core`
+- `exver.md` - Extended versioning format (used across core, sdk, and web)
+- `VERSION_BUMP.md` - Guide for bumping the StartOS version across the codebase
+
+Component-specific docs live alongside their code (e.g., `core/rpc-toolkit.md`, `core/i18n-patterns.md`).
 
 ### Session Startup
 
 On startup:
 
-1. **Check for `agents/USER.md`** - If it doesn't exist, prompt the user for their name/identifier and create it. This file is gitignored since it varies per developer.
+1. **Check for `docs/USER.md`** - If it doesn't exist, prompt the user for their name/identifier and create it. This file is gitignored since it varies per developer.
+
+2. **Check `docs/TODO.md` for relevant tasks** - Show TODOs that either:
 
-2. **Check `agents/TODO.md` for relevant tasks** - Show TODOs that either:
    - Have no `@username` tag (relevant to everyone)
    - Are tagged with the current user's identifier