dev_arc_aws/ROADMAP.md

# ArchNest — Roadmap

Forward-looking work that is **planned but not currently being built**. For
the state of shipped work and the active task, see `HANDOFF.md`. For
historical feature build-out, see `TERMIX_MIGRATION.md`.

---

## Shipped (for context)

The auth roadmap so far — full detail in `HANDOFF.md`:

- **Phase 1** — User menu Profile/Appearance/Security wired up; `?tab=`
  deep-linking in Settings.
- **Phase 2** — Password change, server-tracked sessions, login audit log.
- **Phase 3** — Multi-user accounts: admin/member roles, `active` flag,
  10-seat cap, admin-only user management, `requireAdmin`/`adminOnly` gating.

---

## Phase 4 — Authentik SSO (OIDC) — PAID ADD-ON (AWS deployment)

**Status:** deferred. This is intentionally **not** part of the
self-hosted core build. It is planned as a **paid add-on, shipped when
ArchNest is deployed on AWS** — not on the current `racknerd1` deployment.

Local username/password auth (Phases 1-3) remains the free, always-available
path and the admin recovery path; SSO layers on top of it rather than
replacing it.

### Intended scope (when built)
- Instance-level SSO config (issuer URL, client ID/secret, redirect URI) —
  likely an integration-like settings entry, or a dedicated config
  table / env vars.
- `GET /api/auth/sso/login` → redirect to Authentik.
- `GET /api/auth/sso/callback` → exchange code, look up/create local user by
  SSO subject claim (respecting the 10-user cap from Phase 3), issue the same
  JWT format as today.
- "Sign in with SSO" button on `Login.tsx` alongside username/password
  (local accounts remain — do **not** remove password auth entirely).

### Open scope questions (decide before any code)
1. **Where does SSO config live?** env vars (simplest, redeploy to change) vs.
   a dedicated config table vs. an integration-like settings entry (editable
   in-UI, more work).
2. **First-login provisioning** — auto-create a local `member` for an
   unknown-but-valid SSO user (subject to the 10-seat cap), or require an
   admin to pre-create the account and only *link* it on SSO login?
3. **Role mapping** — do Authentik groups/claims map to admin/member, or do
   all SSO users default to `member` with roles managed locally?

---

## Terminal — window grid view (tiered: self-hosted vs. paid)

**Status:** self-hosted behavior is current; the paid tier is planned.

The Terminal page (`src/pages/Terminal.tsx`) supports a split-pane grid view
within a tab.

- **Self-hosted (current):** capped at a **4-window grid** (1 / 2 / 4 pane
  layouts via the toolbar buttons). This is the free, always-available tier.
- **Paid (planned, AWS deployment):** **as many windows as fit on the
  screen** — dynamic grid sizing beyond the 4-pane cap, laid out responsively
  to the viewport rather than a fixed 1/2/4 choice.

When the paid tier is built, the 4-pane cap becomes a licensing/feature gate
rather than a hard UI limit; the grid layout logic generalizes to an
arbitrary pane count.

---

## LXC container management (Proxmox) — PAID ADD-ON

**Status:** not built; planned as a paid-tier feature.

ArchNest currently has full **Docker** container management (the Containers
page: list/start/stop/restart/pause/remove, logs, interactive exec — backed
by `backend/src/routes/docker.ts` + `backend/src/docker/`). There is **no LXC
equivalent**.

The only place LXC could surface today is the Proxmox integration's
`listResources()` (`backend/src/integrations/proxmox.ts`), and it currently
queries `/api2/json/cluster/resources?type=vm` — i.e. **QEMU VMs only**, so
Proxmox LXC containers (`type=lxc`) are not even listed.

Planned scope (paid tier):
- **List** LXC guests alongside VMs (drop/relax the `type=vm` filter, or also
  fetch `type=lxc`, and label them in the resource grid).
- **Lifecycle** management via Proxmox's per-node LXC API
  (`POST /api2/json/nodes/{node}/lxc/{vmid}/status/{start|stop|shutdown}`) —
  a new route group + `api.ts` entries + UI, mirroring the Docker Containers
  page.
- **Console/shell** into an LXC guest via the Proxmox console/ticket API
  (more involved than Docker exec — separate auth/ticket flow).

Note: the read-only "list LXC in the resource grid" piece is small and
arguably a bug fix (the Proxmox integration silently hides half a cluster's
guests today); if the user later wants just that part in the free tier, it
can be split out from this paid add-on.

---

## Docker monitoring agent — tiered (push self-hosted / pull paid)

ArchNest can manage Docker containers two ways today: the Docker Engine TCP
integration (`backend/src/docker/`) and "Docker over SSH" (runs the `docker`
CLI on a remote SSH host — `backend/src/ssh/docker.ts`,
`backend/src/routes/dockerSsh.ts`). Both are **pull** models where ArchNest
reaches into the host.

A complementary **agent** model is planned, split across tiers:

### Self-hosted — Option 1: push agent (monitoring) — IN PROGRESS
- A lightweight script dropped on each Docker VM (bash + `docker` CLI + curl)
  collects `docker ps` (+ optional per-container stats) and **POSTs** a JSON
  report to an ArchNest ingest endpoint on a timer (cron/systemd).
- VMs need **outbound-only** access to ArchNest over the mesh — no exposed
  port, no SSH, no dockerd socket. Cleanest security story for the free tier.
- ArchNest stores the latest report per host and surfaces it as a read-only
  monitoring view / Infrastructure resource source.
- **Monitoring only** — a one-way push cannot perform actions. Management on
  self-hosted continues to use the existing **Docker-over-SSH** path on
  demand, so nothing is removed: push = constant monitoring (zero exposure),
  SSH = occasional management action.

### Paid — Option 2: pull agent with local API (monitor + manage)
- A small **authenticated HTTP service** runs on each VM, bound to its mesh
  IP, exposing a thin, locked-down wrapper over the Docker socket
  (`/containers`, `/logs`, lifecycle actions, exec).
- ArchNest **pulls** on demand — supports both monitoring and management
  through one uniform mechanism, with real per-agent auth (which the raw
  dockerd TCP socket lacks).
- Tradeoff: exposes a (locked-down, authenticated) port on each VM, and is a
  service to run/secure — hence gated to the paid tier.

---

## Remote Desktop — GNOME & KDE support — ADD-ON

**Status:** not built; **XFCE is confirmed working today**, the others are not.
Full investigation + research lives in `docs/rdp-debug-handoff.md`.

Remote Desktop (Guacamole/`guacd` → RDP) works end-to-end **only with XFCE** on
the target VM, via xrdp's X11 backend. GNOME and KDE do **not** work yet:

- **GNOME (Wayland-only on modern distros)** is blocked two ways: it ships no
  Xorg session for xrdp to launch, *and* its native `gnome-remote-desktop`
  mandates NLA that guacd's bundled **FreeRDP 2.x cannot complete** ("wrong
  security type"). Verified on Fedora 44 / GNOME 50.
- **KDE Plasma 6** is expected to work like XFCE via xrdp + `startplasma-x11`
  (X11 session shipped through ~early 2027), but is **not yet installed/tested**.

Planned scope (add-on):
1. **Custom `guacd` image built against FreeRDP 3** (Apache's official 1.5.5 and
   1.6.0 images both still ship FreeRDP 2.11.x). This is the real unlock for
   GNOME's native Wayland RDP and benefits any modern GNOME / Ubuntu-24.04+
   target — not just this VM. ~30-min from-source build to maintain in
   `docker-compose.yml`.
2. **GNOME headless "system" RDP** (GDM handover, GNOME 46+) — the intended
   modern path; only viable once (1) lands because it still uses NLA.
3. **KDE Plasma** via xrdp + `startplasma-x11` (quick win, no guacd change;
   likely needs a KWin compositing/software-GL tweak on virtual GPUs).
4. **Per-host desktop/session selection** instead of a single global
   `/etc/xrdp/startwm.sh`, so one VM can offer XFCE / KDE / GNOME.

See `docs/rdp-debug-handoff.md` for the suggested order of work and primary-source
references (SUSE headless-GNOME series, jamesnorth GRD setup, RHEL 10 docs, KDE
discuss threads).

---

## Per-integration node tabs — PAID ADD-ON

**Status:** not built; planned as a paid-tier feature.

Node Status on the Infrastructure page collapses every integration (except
Proxmox) into a **single tile per integration** — e.g. 30 EC2 instances under
one "AWS" tile, all of Uptime Kuma's monitors under one "Uptime" tile — with
the individual members only visible in the Node Detail card after selecting
that tile (`ungroupedIntegrationTypes` in `src/pages/Infrastructure.tsx`).
This keeps the grid usable when an integration has dozens/hundreds of
resources, but it means there's currently no way to see *all* nodes of a
given integration laid out at once.

Planned scope (paid tier): a dedicated **tab per integration** (alongside
today's Overview/Network etc. sub-tabs) that lists every node belonging to
that integration — full grid, not just the grouped summary tile — for users
who want to browse/filter dozens of EC2 instances, Docker containers, or
Uptime Kuma monitors directly rather than drilling through Node Detail.

---

## Known non-blocking stubs (cosmetic, not scheduled)

Not flagged as work to do unless explicitly asked:

- `Infrastructure.tsx`'s "Network" sub-tab is **intentionally** disabled
  (`title="Coming soon"`) — leave alone unless explicitly asked.
- `Settings.tsx`'s Appearance section (theme/accent/fontSize/radius/
  sidebarExpanded/animations) is local-state-only — doesn't persist or apply
  anywhere. Recommended fix if picked up: mirror the Terminal page's
  `localStorage`-backed prefs pattern and apply via CSS variables on `:root`.
- `Settings.tsx`'s Notifications section (email/push/sound toggles) has no
  backing delivery mechanism — recommend removing or clearly labeling as
  not-yet-functional rather than persisting settings that do nothing.