home-hosted 0.6.8 → 0.7.1

package/docs/DDNS.md

@@ -2,11 +2,12 @@
 
 Keep a list of hostnames pointed at this machine's public IP. The panel checks the address on an
 interval and calls a provider only when it actually changed — restart-safe, because the last
-confirmed address per hostname is kept in `$HHOSTED_HOME/.state/ddns.json`.
+confirmed address per hostname is kept in the workspace's `.hh/<workspace>/.state/ddns.json`.
 
-**Settings → Dynamic DNS** is the whole setup: add an account, paste its credentials, add hostnames.
-The block is saved by the page's own **Save settings**, like every other section on it; the credentials
-button saves on its own, being a secret. Provider credentials never enter `servers.config.json`.
+**Workspace Settings → Dynamic DNS** is the whole setup: add an account, paste its credentials, add
+hostnames. The block is saved by the page's own **Save settings**, like every other section on it; the
+credentials button saves on its own, being a secret. Provider credentials never enter
+`servers.config.json`.
 
 ```json
 {
@@ -27,11 +28,13 @@ button saves on its own, being a secret. Provider credentials never enter `serve
 }
 ```
 
-Credentials live in `.control-secrets.json` (0600), keyed by the account `id` and sealed with
+Credentials live in the workspace's `.secrets.json` (0600), keyed by the account `id` and sealed with
 AES-256-GCM under `HHOSTED_DDNS_SECRET` — set your own, or the default `hh` only stops a casual
-read. The account does not have to be saved first, and the provider is stored with the entry, so an
-id that later changes provider does not silently keep the old secret. Removing an account drops its
-credentials on the next save.
+read. The block above is the workspace's `.hh/<workspace>/settings.json`; the credentials are cached
+separately in `.secrets.json`, both beside that workspace's `servers.config.json`. The account does
+not have to be saved first, and the provider is stored with the entry, so an id that later changes
+provider does not silently keep the old secret. Removing an account drops its credentials on the next
+save.
 
 Header fields:
 
@@ -72,7 +75,7 @@ DNS API), and the Namecheap XML API (a full zone rewrite per update).
 ## Notifications
 
 Telegram carries one message per pass that changed a record, and one for a pass that failed — the
-same switch as every other event, under Settings → Notifications → *Dynamic DNS changes and
+same switch as every other event, under Workspace Settings → Notifications → *Dynamic DNS changes and
 failures* (`telegram.onDdns`). There is no second switch in this section.
 
 ## Adding a provider

package/docs/NOTIFICATIONS.md

@@ -6,7 +6,7 @@ opt-in, and the bot token never leaves the secrets file.
 ## Setup
 
 1. Talk to [@BotFather](https://t.me/BotFather), run `/newbot`, and copy the token it prints.
-2. In the panel: **Settings → Notifications**, paste the token, press **Detect chats**.
+2. In the panel: **Workspace Settings → Notifications**, paste the token, press **Detect chats**.
 3. Send your bot a message from the chat you want the alerts in — a bot cannot open a conversation —
    then pick that chat from the list (or paste its id).
 4. Press **Test**: the chat gets a message, and the panel shows the result and its timestamp.
@@ -49,9 +49,9 @@ curl -X POST http://127.0.0.1:3999/api/notifications/test \
 | host thresholds breached, and recovered | `onHost` | ✅ |
 | a dynamic DNS record changed, or a pass failed | `onDdns` | ✅ |
 
-Host thresholds themselves — disk, memory, swap, load, temperature — are **Settings → Host**.
-Dynamic DNS carries one message per pass that changed a record, and one per failed pass — see
-[DDNS.md](./DDNS.md).
+Host thresholds themselves — disk, memory, swap, load, temperature — are **Global settings → Host
+vitals**. Dynamic DNS carries one message per pass that changed a record, and one per failed pass —
+see [DDNS.md](./DDNS.md).
 
 ## Quiet periods
 
@@ -61,12 +61,14 @@ disables the throttle.
 
 ## Where the token lives
 
-`$HHOSTED_HOME/.control-secrets.json`, mode `0600`, next to the password and API-token hashes. It is
-never written into `servers.config.json`, so committing or sharing a config cannot leak it — and
-`GET /api/settings` reports `tokenSet: true|false`, never the token itself.
+The workspace's `.hh/<workspace>/.secrets.json`, mode `0600`, next to that workspace's DDNS
+credentials. The password and API-token hashes are panel-wide and live in
+`.hh/.control-secrets.json`. The token is never written into `servers.config.json`, so committing or
+sharing a config cannot leak it — and `GET /api/settings/workspace` reports `tokenSet: true|false`,
+never the token itself.
 
 ## Delivery failures
 
 Sends are fire-and-forget: supervision never waits on a chat API. A failure is logged and the last
-result is shown in **Settings → Notifications** (`lastResult`, `lastResultAt`), so a wrong chat id is
-visible there instead of silently swallowing alerts.
+result is shown in **Workspace Settings → Notifications** (`lastResult`, `lastResultAt`), so a wrong
+chat id is visible there instead of silently swallowing alerts.

package/docs/SERVERS.md

@@ -1,7 +1,13 @@
 # Servers
 
-Every supervised process is one entry in `$HHOSTED_HOME/servers.config.json`. Add it with **➕ Add
-server** in the panel, or write it by hand — the panel writes the same file.
+Every supervised process is one entry in a **workspace**'s `servers.config.json` —
+`$HHOSTED_HOME/.hh/<workspace-id>/servers.config.json`, default `~/.home-hosted/.hh/default/…`.
+Add it with **➕ Add server** in the panel, or write it by hand — the panel writes the same file.
+
+<sub>A workspace is the ownership boundary: its servers, secrets, logs and nanny state are its own.
+Pick one in the header; the workspace's server defaults and log retention sit in
+**Workspace Settings**. Panel-wide things (listener, auth, TLS, host vitals, backups, UI) stay in
+**Global settings**.</sub>
 
 ```json
 {
@@ -140,14 +146,14 @@ holder it cannot prove is yours.
 ## Persistent entries
 
 `"persistent": true` means "keep this running whatever happens to the panel". It is off by default,
-it is per entry (not a `Settings → Server defaults` field), and it covers the three ways the panel can
-go away: `down`, a restart, or being killed outright.
+it is per entry (not a **Workspace Settings → Server defaults** field), and it covers the three ways
+the panel can go away: `down`, a restart, or being killed outright.
 
 How it works: the panel does not run the entry directly. It spawns a **nanny** — the same CLI, hidden
 `__nanny` mode — which starts the entry, owns its pipes and writes its output to the entry's own log
 file. The nanny is what survives; the panel reattaches to it on the next boot through
-`$HHOSTED_HOME/.state/<id>.json`, and a stale file is how it learns how a child ended while nobody was
-watching.
+`.hh/<workspace>/.state/<id>.json`, and a stale file is how it learns how a child ended while nobody
+was watching.
 
 What that changes:
 
@@ -157,8 +163,8 @@ What that changes:
   that is already running is adopted, because leaving it unmanaged would make the panel treat its own
   server as a stranger on the port.
 - **Logs keep flowing.** The panel tails the nanny's file, so history survives the panel being down;
-  `logs.persist: false` still keeps it out of the Logs page — but a file has to exist in
-  `.logs/`, because there is no pipe to carry the output.
+  `logs.persist: false` still keeps it out of the Logs page — but a file has to exist in the
+  workspace's `.logs/`, because there is no pipe to carry the output.
 - **A crash while the panel is away is reported, not restarted.** Retries and backoff remain the
   panel's job, so an entry that dies with nobody watching shows up as **crashed** on the next boot
   with the exit code in its log.

package/docs/UI_CREATION.md

@@ -22,15 +22,15 @@ care what your UI looks like.
 ## Install it
 
 ```text
-$HHOSTED_HOME/.ui/            ← where your build lives
+$HHOSTED_HOME/.hh/.ui/        ← where your build lives
   index.html                  ← required, at the root
   assets/…
   ui.json                     ← optional, but see below
 ```
 
-**Settings → Interface** → pick a `.zip` → *Install UI* (refresh to see it). Or drop the files into
-`$HHOSTED_HOME/.ui` yourself. The zip may hold the files at its root or inside one wrapper directory
-(`zip -r ui.zip dist` works too).
+**Global settings → Interface** → pick a `.zip` → *Install UI* (refresh to see it). Or drop the files
+into `$HHOSTED_HOME/.hh/.ui` yourself. The zip may hold the files at its root or inside one wrapper
+directory (`zip -r ui.zip dist` works too).
 
 Without the settings page, `home-hosted ui-switch` installs one from a GitHub release asset (its
 default), from a local `.zip` (`--file ./ui.zip`), or from a URL (`--file https://…/ui.zip`).
@@ -53,7 +53,7 @@ installed, and what lets it offer you the next version:
 
 | field | |
 | --- | --- |
-| `name`, `version` | what Settings shows as installed |
+| `name`, `version` | what Global settings → Interface shows as installed |
 | `repo` | `owner/name` the releases come from — the one field `ui-update` needs |
 | `tag` | the release this build came from, so an update can tell newer from older |
 | `asset` | the release asset name, when a release carries more than one UI |
@@ -71,8 +71,8 @@ Nothing is built on the server side: whatever you upload is served as-is, so shi
 HTML/JS/CSS or the output of your own Vite/Next/Astro build with relative asset paths.
 
 **If it breaks:** `home-hosted ui-revert` puts the stock panel back (or *Revert to stock* in
-Settings). The CLI also prints a reminder at startup while a custom UI is active — a broken UI must
-never lock you out of your own machine.
+Global settings). The CLI also prints a reminder at startup while a custom UI is active — a broken UI
+must never lock you out of your own machine.
 
 ## Rules of the road
 
@@ -107,20 +107,25 @@ responses at runtime. Either style is fine.
 
 ### Endpoints you will actually use
 
+Workspace-scoped routes take `?workspace=<id>`. Omitting it means the panel's default workspace;
+naming one that does not exist is a `404 UNKNOWN_WORKSPACE`, never a silent fallback.
+
 | endpoint | what it gives you |
 | --- | --- |
-| `GET /api/state` | everything: panel settings, servers with live status, host vitals |
+| `GET /api/state` | everything: global settings, every workspace with its servers and live status, host vitals |
+| `GET` / `POST /api/workspaces`, `PATCH` / `DELETE /api/workspaces/:id` | the registry: list, create, rename, remove (removal stops and disposes that workspace's servers) |
 | `GET /api/events` | **the live feed**: `hello` carries the full state, then `state`, `server`, `log` |
 | `GET /api/servers/:id/stream` | one server's `server` + `log` frames |
-| `POST /api/servers/:id/{start,stop,restart}`, `/api/servers/{start-all,stop-all}` | lifecycle |
+| `POST /api/servers/:id/{start,stop,restart}`, `/api/servers/{start-all,stop-all}` | lifecycle (workspace-scoped) |
 | `POST /api/servers/:id/free-port` | ask whatever holds that server's port to stop (`403`-safe: supervised listeners are refused) |
-| `GET` / `POST /api/servers`, `PATCH` / `DELETE /api/servers/:id` | the entries themselves |
-| `GET /api/logs`, `/api/logs/:id?tail=&search=`, `/api/logs/:id/download?file=` | persisted logs |
-| `GET` / `PATCH /api/settings` | the panel's own config (`control.label`, host thresholds, backups, …) |
-| `POST` / `DELETE /api/settings/ui` | install or revert a UI — what the settings page calls |
+| `GET` / `POST /api/servers`, `PATCH` / `DELETE /api/servers/:id` | the entries themselves, in one workspace |
+| `GET /api/logs`, `/api/logs/:id?tail=&search=`, `/api/logs/:id/download?file=` | persisted logs, for one workspace |
+| `GET` / `PATCH /api/settings` | the panel-wide settings (`control.label`, host thresholds, backups, UI) |
+| `GET` / `PATCH /api/settings/workspace` | one workspace's settings: server defaults, log retention, notifications |
+| `POST` / `DELETE /api/settings/ui` | install or revert a UI — what Global settings calls |
 | `POST` / `DELETE /api/settings/tls` | upload or clear a PEM pair |
-| `GET` / `POST /api/backups`, `/api/backups/restore`, `/api/backups/:name/download` | archives; a create body may carry `include` (item ids `config`, `secrets`, `tls`, `data:<path>`, from `GET /api/backups`), and a restore body `include` selects what to apply |
-| `POST` / `DELETE /api/notifications/token`, `/api/notifications/test`, `/detect-chats` | Telegram |
+| `GET` / `POST /api/backups`, `/api/backups/restore`, `/api/backups/:name/download` | archives; entries are global (`global:settings`, `global:secrets`, `global:tls`) or per workspace, whose leaves are `workspace:<id>:settings`, `:servers`, `:secrets` plus `data:<path>`; a create/restore body `include` selects them |
+| `POST` / `DELETE /api/notifications/token`, `/api/notifications/test`, `/detect-chats` | Telegram, per workspace |
 | `POST /api/auth/login`, `GET /api/auth/session`, `POST /api/auth/logout` | the session |
 | `GET /healthz` | liveness — **no session**, and `503` when an autostart server has crashed |
 | `GET /api/metrics` | Prometheus text (needs a session) |
@@ -128,6 +133,10 @@ responses at runtime. Either style is fine.
 `GET /healthz` and `GET /openapi/*` are the only unauthenticated reads; the SPA shell itself is
 public, so your app can load before a session exists.
 
+A `ServerView` carries `workspaceId` — the same server id can exist in two workspaces, so key a list
+by the pair, not by `serverId` alone. A `server` frame embeds that view; a `log` frame carries only
+`serverId`, so match it against the workspace's servers.
+
 Anything calling the API from outside a browser — a script, a test, an agent, a native shell — can
 skip the login dance with an API token: `home-hosted set-token --generate` prints one once, and
 `Authorization: Bearer <token>` authenticates every `/api` request with the same authority as a
@@ -137,7 +146,7 @@ Two settings worth reflecting: `control.label` is the panel's own name (the stoc
 and `GET /api/settings` includes `ui` — which UI is being served, and its metadata.
 
 An entry body is partial by design: `POST /api/servers` and `PATCH /api/servers/:id` take only the
-fields the person decided, and the panel's **Server defaults** fill the rest. Sending a value the
+fields the person decided, and the workspace's **Server defaults** fill the rest. Sending a value the
 person never chose freezes it against those defaults, so build the body as a diff
 (`inheritBaseline` and `diffFields` in `src/shared/patch-diff.ts`).
 
@@ -158,14 +167,16 @@ session, 403 bad token or origin, 404 unknown id, 409 conflict, 413 too large.
 | `event:` | `data:` |
 | --- | --- |
 | `hello` | `{ ts, state }` — the first frame, the complete snapshot |
-| `state` | `{ ts, state }` — anything changed: a status, a resource sample, host vitals |
-| `server` | `{ ts, serverId, server }` — one entry, after an action or a probe |
+| `state` | `{ ts, state }` — anything changed: a status, a resource sample, host vitals, a workspace |
+| `server` | `{ ts, serverId, server }` — one entry, `server.workspaceId` says which workspace |
 | `log` | `{ ts, serverId, lines }` — new output (dropped under backpressure, never state) |
 | `ping` | the current time, every 15 s |
 
-Send `?logs=0` to skip log frames, or `?serverId=<id>` to follow one server. The exact shapes are
-`sseMessageSchema` in `src/shared/contracts.ts` — the server validates against it before writing, so
-that schema is also your best type source.
+`GET /api/events` takes `?logs=0` to skip log frames and `?serverId=<id>` to follow one server — but
+it matches on the id alone, so an id used in two workspaces mixes their frames. Use
+`GET /api/servers/:id/stream?workspace=<id>` for one server: it validates the pair and replays the
+current state first. The exact shapes are `sseMessageSchema` in `src/shared/contracts.ts` — the
+server validates against it before writing, so that schema is also your best type source.
 
 ## Editing settings without fighting the stream
 
@@ -203,7 +214,8 @@ node scripts/build-uis.mjs <name> --zip   # builds it, writes uis/dist/home-host
 pnpm run build:uis                        # every UI, zipped; releases attach them as assets
 ```
 
-Only `stock` ships inside the npm package; the rest are release assets you install from Settings.
+Only `stock` ships inside the npm package; the rest are release assets you install from Global
+settings.
 `pnpm run quickcheck` type-checks every UI, and `pnpm test` picks up any `test/*.test.ts` you add
 (use relative imports — the `@` alias points at `stock`).
 
@@ -218,13 +230,15 @@ pnpm run build                      # → dist/
 # 2. keep the API base relative, then zip the build
 cd dist && zip -r ../my-panel.zip . && cd ..
 
-# 3. Settings → Interface → Install UI, then refresh
+# 3. Global settings → Interface → Install UI, then refresh
 ```
 
 Your client needs the session cookie, which the browser sends automatically once you log in on that
 origin (a non-browser client uses an API token instead, above). For local development `pnpm dev` runs
-the panel on 3999 and a Vite dev server on 3998 with `/api` proxied — point your own dev server at
-`http://127.0.0.1:3999` the same way.
+the panel on `6000` and a Vite dev server on `6001` with `/api` proxied — point your own dev server at
+`http://127.0.0.1:6000` the same way. Both stay in the 6xxx range so a dev instance never collides
+with an installed panel on the default 3999; override with `--port`/`--ui-port` or
+`HHOSTED_DEV_PANEL_PORT`/`HHOSTED_DEV_UI_PORT`.
 
 ## Checklist
 
@@ -235,4 +249,4 @@ the panel on 3999 and a Vite dev server on 3998 with `/api` proxied — point yo
 - [ ] deep links render (the server falls back to `index.html`)
 - [ ] assets self-hosted, no CDN
 - [ ] works over plain http on a LAN
-- [ ] `ui.json` with a name and version, so Settings can tell you what is installed — plus `repo`/`tag`/`asset` if you want `ui-update` to follow your releases
+- [ ] `ui.json` with a name and version, so Global settings can tell you what is installed — plus `repo`/`tag`/`asset` if you want `ui-update` to follow your releases

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "home-hosted",
   "type": "module",
-  "version": "0.6.8",
+  "version": "0.7.1",
   "packageManager": "pnpm@12.5.1",
   "description": "Self-hosted control panel that keeps your home-server processes alive: supervision, restarts, port conflicts, logs — and a UI you can replace.",
   "author": "NamesMT <dangquoctrung123@gmail.com>",