home-hosted 0.6.7 → 0.7.0

package/AGENTS.md

@@ -1,16 +1,20 @@
 # AGENTS.md
 
 `home-hosted` is a Node 24 / TypeScript harness for self-hosted servers: `up` starts a Hono/srvx
-panel (default `127.0.0.1:3999`) that supervises the entries in `$HHOSTED_HOME/servers.config.json`
-and serves a UI. User docs: `README.md`, `docs/SERVERS.md` (entries and port conflicts),
-`docs/NOTIFICATIONS.md`, `docs/DDNS.md`; UI authors: `docs/UI_CREATION.md`.
+panel (default `127.0.0.1:3999`) that supervises the entries in each workspace's
+`servers.config.json` and serves a UI. User docs: `README.md`, `docs/SERVERS.md` (entries and port
+conflicts), `docs/NOTIFICATIONS.md`, `docs/DDNS.md`; UI authors: `docs/UI_CREATION.md`.
 
-State lives only in `$HHOSTED_HOME` (default `~/.home-hosted`): `servers.config.json`,
-`.control-secrets.json` (0600: password hash, API token hash, Telegram bot token, DDNS credentials),
-`.logs/`, `.tls/`, `.backups/`, `.ui/`, `.state/` (a persistent entry's nanny state, plus its 0600
-spawn spec until the nanny reads it, plus `ddns.json` — the last address each target confirmed), and
-`run.json` — the live daemon's pid/url/token, 0600. The package ships **no servers**: never commit a
-config, a seed entry, or a path that names one.
+State lives only in `$HHOSTED_HOME/.hh` (default `~/.home-hosted/.hh`). Global files sit at its top
+level: `settings.json` (listener, auth, TLS policy, host vitals, backups), `workspaces.json`,
+`.control-secrets.json` (0600: password hash, API token hash), `.tls/`, `.backups/`, `.ui/`, `.logs/`
+(the panel console), and `run.json` — the live daemon's pid/url/token, 0600. Every workspace owns
+`.hh/<id>/`: `settings.json` (server defaults, log retention, notifications, DDNS), `servers.config.json`,
+`.secrets.json` (0600: Telegram bot token and DDNS credentials sealed with AES-256-GCM under
+`HHOSTED_DDNS_SECRET`), `.logs/`, and `.state/` (a persistent entry's nanny state plus its 0600 spawn
+spec until the nanny reads it, plus `ddns.json`). A pre-`.hh` instance is relocated automatically by
+`ensureLayout()` (`src/config/layout.ts`). The package ships **no servers**: never commit a config, a
+seed entry, or a path that names one.
 
 ## Commands
 
@@ -83,10 +87,15 @@ a minor without one.
 - `src/api/**` — one file per URL group (`$.routes.ts` = several routes), mirroring the path.
 - `src/shared/contracts.ts` — every ArkType schema (config, API and SSE DTOs), shared with the UIs;
   the OpenAPI spec is generated from it, never hand-written.
-- `src/config/` — `schema.ts` (on-disk shape, including the `meta` stamp), `parse.ts` (the tolerant
-  reader: unknown keys are reported and kept, everything else blocking), `store.ts` (validate/merge/
-  atomic commit, reports `configError`/`configWarnings` instead of throwing on a bad file),
-  `migrations.ts` (the schema constant and the ordered step registry), `secrets.ts`, `seed.ts`.
+- `src/config/` — split by scope. `settings.ts` (`GlobalSettingsStore`: `.hh/settings.json` — listener,
+  auth, TLS policy, host vitals, backups) and `store.ts` (`WorkspaceStore`: a workspace's
+  `settings.json` + `servers.config.json`, validate/merge/atomic commit, reporting
+  `configError`/`configWarnings` instead of throwing on a bad file). `workspaces.ts` is the registry
+  (`workspaces.json`), `layout.ts` the one-time relocation of a pre-workspace `$HHOSTED_HOME`.
+  `schema.ts` holds the three on-disk shapes plus the `meta` stamp, `parse.ts` the tolerant readers
+  (`parseGlobalSettings`/`parseWorkspaceSettings`/`parseServersFile`: unknown keys are reported and
+  kept, everything else blocking), `patch.ts` the merge helpers, `migrations.ts` the schema constant
+  and ordered step registry, and `secrets.ts`/`seed.ts` the two secret scopes and the seeds.
 - `src/providers/` — stateless leaves: `process` (spawn, `terminate`, `terminatePid` for a process we
   adopted), `port` (probe, holder lookup, `terminatePids`), `proc` (the sampler, plus
   `processCarriesServerId` for the environment marker and `processTreePids` for tree ownership),
@@ -95,12 +104,13 @@ a minor without one.
   `log-tail` (an offset reader that survives rotation and truncation), `ddns/` (one `DdnsProvider` per
   registrar over one HTTP call each, plus `ip` and `zone` helpers), health-check, host, telegram,
   archive.
-- `src/services/` — stateful orchestration: supervisor, control-server, config-watch, state,
-  auth + exposure, dependencies, history, log-buffer/log-files, notifications, host-monitor, ddns,
-  backups, tls, ui, plus `init` (the scaffold behind `home-hosted init`: a manifest, a `.gitignore`,
-  and the prompts stay in the CLI), `nanny` (the process a persistent entry runs under) and
-  `log-relay` (the tailer that feeds its lines to the supervisor). It names no server — the scaffold
-  must stay as neutral as the supervisor.
+- `src/services/` — stateful orchestration: `panel` (one `WorkspaceRuntime` per workspace, workspace
+  CRUD, and the single aggregate state frame — every per-workspace service hangs off it), supervisor,
+  control-server, config-watch, state, auth + exposure, dependencies, history, log-buffer/log-files,
+  notifications, host-monitor, ddns, backups, tls, ui, plus `init` (the scaffold behind
+  `home-hosted init`: a manifest, a `.gitignore`, and the prompts stay in the CLI), `nanny` (the
+  process a persistent entry runs under) and `log-relay` (the tailer that feeds its lines to the
+  supervisor). It names no server — the scaffold must stay as neutral as the supervisor.
 - `src/middleware/auth.ts` — the `/api/*` guard, and `requestIdentity()`, the one place a request's
   credentials are read: the `hh_session` cookie or `Authorization: Bearer <api token>`. A token is
   a first-class credential (same authority as a signed-in browser) and is verified from the secrets
@@ -111,7 +121,7 @@ a minor without one.
 - `uis/<name>/` — each UI is a Vite app (Vue 3 + Tailwind v4) built through `uis/vite.shared.ts`;
   `stock` is the one shipped inside the package. Aliases: `@` → that UI's `src`, `@shared` →
   `src/shared`, `@server` → `src` (**types only** — never import runtime server code into a UI).
-  Its `public/ui.json` is the UI's identity: `name` and `version` (what Settings shows),
+  Its `public/ui.json` is the UI's identity: `name` and `version` (what Global Settings → Interface shows),
   `repo`/`tag`/`asset` (which release carries it, for `ui-update`) and `unix` (when it was built).
   `UiService` carries those fields into the installed `$HHOSTED_HOME/.ui/ui.json` unchanged and adds
   `uploadedAt`/`files` of its own.
@@ -140,7 +150,7 @@ a minor without one.
 - A single on/off setting is a `ToggleSwitch`; `CheckField` is only for picking items out of a set
   (the restore plan). A checkbox in a `FieldGroup` grid reads as misaligned next to the inputs.
 - A create body carries only what differs from what the entry would inherit — the schema's defaults
-  with the panel's `Settings → Server defaults` on top (`inheritBaseline` + `diffFields` in both
+  with `Workspace Settings → Server defaults` on top (`inheritBaseline` + `diffFields` in both
   UIs). A value written into `servers.config.json` stops following those defaults, so anything the
   person did not decide stays out; the editor applies the same rule to an edit.
 - ArkType at every runtime boundary: routes use `validate('json'|'query'|'param', schema)` then
@@ -149,7 +159,9 @@ a minor without one.
   envelope `{ message, code, detail }`. Never hand-roll `c.json({ error })`.
 - Document routes with `describeRoute` + `jsonBody(schema)`; `jsonBody` needs a real schema.
 - Patch schemas carry no defaults; nested groups (`restart`/`health`/`stop`/`auth`/`tls`/`telegram`/
-  `http`) merge key-by-key, and an explicit `null` clears a key.
+  `http`) merge key-by-key, and an explicit `null` clears a key. `ddns` is the exception: its
+  `accounts`/`domains` lists are **replaced** (a merge cannot express removing a hostname), and only
+  `ipv4`/`ipv6` merge.
 - Two-sided bounds read inclusively (`'1 <= number.integer <= 512'`). `test/shared/contracts.test.ts`
   pins every boundary and the patch/schema parity — update it with any schema change.
 - A new field in a **response** DTO is optional (`'x?'`) and its clients read it defensively. An
@@ -165,6 +177,12 @@ a minor without one.
 - A destructive action that is one click away confirms in a **popover** (`KillPortButton.vue`),
   never by arming the same button for a second press: an impatient double click on an arming
   button fires it. Keep the safe choice first in the popover's tab order.
+- **Docs ship with the change.** A user-visible change updates the docs that describe it
+  (`README.md`, `docs/*.md`) in the same commit — do not forget them; a stale doc is a bug like
+  stale code.
+- **UIs move together.** `uis/stock` is not the only client: a change to it — or to a shared
+  contract it reads — lands in every other UI under `uis/`, and each altered UI bumps its
+  `ui.json` per the rule above.
 
 ## Compatibility
 
@@ -194,10 +212,14 @@ either is a last resort, and never an accidental one.
 - **Unknown keys are dropped from the resolved config, kept on disk, and listed in a startup
   warning.** Dropping one is the normal way a newer config looks here, so it must never fail the
   group it sits in (that used to reset `control` — port, bind, auth policy — to schema defaults).
+  A *write* to a group validates the same tolerant way (`parseTolerant` via the store), so a key this
+  release does not know never blocks a save — removing a key from a schema must not brick the page
+  that writes it.
 - **Migrations ship inside the package** (`src/config/migrations.ts`), are ordered, idempotent and
-  described in one line each. `home-hosted migrate` prints the plan, keeps `servers.config.json.bak`,
-  refuses to write a config it cannot read, and needs consent: `--yes`, `HHOSTED_MIGRATE=allow`, or a
-  person at a terminal. A detached daemon never migrates on its own. Starting a fetch of migration
+  described in one line each. `home-hosted migrate` prints the plan, keeps a `.bak` beside each file it
+  rewrites, refuses to write a config it cannot read, and needs consent: `--yes`, `HHOSTED_MIGRATE=allow`,
+  or a person at a terminal. The layout relocation is not a schema change: it runs automatically from
+  the CLI pre-pass (`ensureLayout()`), so an upgrade never starts against a half-moved directory. Starting a fetch of migration
   code from GitHub was considered and rejected: the panel supervises processes, so remote code is an
   RCE surface, and a migration would age against a newer store API anyway.
 
@@ -205,11 +227,13 @@ either is a last resort, and never an accidental one.
 
 - **Server-agnostic.** No blessed ids, no `dataDir`-style globals: a server gets only its own
   `command`/`args`/`env`/`dataEnvs`/`envFile`/`bootstrap`. A test fails if a core file learns one.
-- **Paths.** `dataRoot` is state; `projectDir` is the base for relative entry paths. `{id}{port}`
+- **Paths.** `dataRoot` is state, and the state itself lives under `dataRoot/.hh` (global files plus
+  one directory per workspace); `projectDir` is the base for relative entry paths. `{id}{port}`
   `{host}{bind}{cwd}{projectDir}{dataRoot}{home}` and `${ENV}` expand in config; there is no
   package-relative state.
-- **Secrets never enter the config.** The password hash, API token hash and bot token live in the
-  0600 secrets file, and the TLS pair in `.tls/`; the config holds policy.
+- **Secrets never enter the config.** Global `.hh/.control-secrets.json` holds the password hash and
+  API token hash, each workspace's `.secrets.json` holds its Telegram token and DDNS credentials, and
+  the TLS pair sits in `.hh/.tls/`; every one is 0600 and the config holds only policy.
 - **A port holder that is this entry's own successor is not a stranger.** A program that restarts
   itself leaves a detached process behind; with `follow` the panel adopts it as-is (pid, liveness,
   health, resources, stop — but not its output); with `reclaim` it stops that successor and starts a
@@ -252,8 +276,14 @@ either is a last resort, and never an accidental one.
 - **The CLI drives a running panel through `/_hh`, never `/api`.** `down` and `start`/`stop` read
   run.json's token and speak over loopback through one guard (`assertLocalCall`), so they need no
   session, password or API token — and a new local command must not open an unauthenticated `/api` route.
+- **A server id is only unique inside its workspace.** Anything keyed by id alone — SSE
+  (`EventHub` scopes on `serverKey(workspaceId, serverId)`), log buffers, series, route params — must key
+  on the pair, or two workspaces' same-named servers mix frames.
+- **A workspace is the ownership boundary.** Servers, secrets, logs and nanny state belong to exactly
+  one workspace; only listener, auth, TLS, host vitals, backups, UI and `run.json` are panel-wide.
+  A per-workspace service is reached through `PanelService.requireWorkspace(id)`, never a module global.
 - **UIs are external clients.** Nothing in `src/**` may know a UI's markup or files;
-  `$HHOSTED_HOME/.ui` overrides the packaged UI at runtime.
+  `$HHOSTED_HOME/.hh/.ui` overrides the packaged UI at runtime.
 - **A restore writes only where a config says** — archive allowlist, `origin` matching first,
   symlinks never recreated.
 - **Cross-platform.** Linux/macOS/Windows: `/proc` vs `ps` vs Win32_Process, process groups vs
@@ -263,7 +293,11 @@ either is a last resort, and never an accidental one.
 ## Gotchas
 
 - `run.json` is the daemon's identity and `down`'s credential; keep `runtimeSchema` in sync with the
-  `Runtime` written in `src/index.ts`.
+  `Runtime` written in `src/index.ts`. It now lives at `.hh/run.json`.
+- **`ensureLayout()` runs before any command resolves a state path** (the CLI pre-pass) and is
+  idempotent. It moves rather than copies, never overwrites an existing `.hh` file, and removes a
+  legacy directory only when every entry in it actually moved — a refused move must not become a
+  delete.
 - Moving the listener (host/port/TLS) kills the connection answering that request, so
   `PATCH /api/settings`, the TLS routes and `/_hh/shutdown` defer with `afterResponse()`.
 - `Supervisor.start()` sets `starting` synchronously before its first await, and `stop()` sets
@@ -273,15 +307,15 @@ either is a last resort, and never an accidental one.
   is true, one Stop on an already-stopped server made that entry unstartable until a daemon restart.
 - Timers and `void`-ed promises in the supervisor carry a `.catch`: a throw in the tick or in a retry
   is an unhandled rejection, and Node 24 ends the process on one.
-- **`Settings → Server defaults` merge into the nested groups key by key** (`mergeDefaults` in
-  `src/config/schema.ts`, used by both the config parser and `validateServer`). A shallow
+- **`Workspace Settings → Server defaults` merge into the nested groups key by key** (`mergeDefaults`
+  in `src/config/schema.ts`, used by the servers parser and `validateServer`). A shallow
   `{ ...defaults, ...entry }` lets an entry that decides `restart.maxRetries` silently drop the
-  panel's `restart.baseDelayMs` — and the create/edit diff flow depends on inheriting exactly that.
+  workspace's `restart.baseDelayMs` — and the create/edit diff flow depends on inheriting exactly that.
 - The curated CLI dispatch reads only the **flag** forms (`--help`/`-h`, `--version`/`-v`) after a
   command name, never a bare `help`/`version`: that is an option's value (`init --name help`).
 - Port preflight re-probes after 300 ms — a just-closed listener can still complete a handshake.
-- **The config is re-read whenever the file changes on disk** (`src/services/config-watch.ts` →
-  `ConfigStore.reloadFromDisk()`, wired in `src/index.ts`). The watch is on the *directory*, because
+- **A workspace's config is re-read whenever its files change on disk** (`src/services/config-watch.ts`
+  → `WorkspaceStore.reloadFromDisk()`, wired per workspace in `src/services/panel.ts`). The watch is on the *directory*, because
   an editor's save is a temporary file renamed over the target — the inode changes, the name does not
   — and a two-second poll backs it up where `fs.watch` is undependable (network mounts). The store
   compares the bytes it last read and the bytes it wrote, so the panel's own saves never reload
@@ -344,11 +378,14 @@ either is a last resort, and never an accidental one.
 ## Where to extend
 
 - **Route**: `src/api/<x>.ts` (chained factory) → mount in `src/app.ts` → schemas in
-  `src/shared/contracts.ts` → `describeRoute` + `jsonBody`.
-- **Server field**: `serverSchema` + its patch in contracts, merge keys in `config/store.ts` when
+  `src/shared/contracts.ts` → `describeRoute` + `jsonBody`. A workspace-scoped route takes
+  `?workspace=<id>` (`workspaceQuerySchema` + `requireWorkspace` in `src/helpers/workspace.ts`); an
+  omitted id means the default workspace, never another one.
+- **Server field**: `serverSchema` + its patch in contracts, merge keys in `config/patch.ts` when
   nested, the form in `uis/stock/src/components/settings/`, and the contract tests.
 - **UI**: a new `uis/<name>/` with a `vite.config.ts` from the shared factory;
-  `node scripts/build-uis.mjs <name> --zip`. The contract is `docs/UI_CREATION.md`.
+  `node scripts/build-uis.mjs <name> --zip`. The contract is `docs/UI_CREATION.md`. A change to one
+  UI (`stock`, `noc-console`) is carried to the others in the same commit.
 - **Capability**: a stateless `src/providers/*` returning plain data; a DDNS provider is one file plus
   a registry line (`src/providers/ddns/index.ts`), and the settings form, credentials and validation
   follow from its metadata — see `docs/DDNS.md`.

package/README.md

@@ -7,7 +7,8 @@
 <sub>The harness for your servers.</sub>
 
 Point it at the things you run — a gateway, a media server, a bot, a database — and it starts
-them, watches them, restarts what dies, and shows you one page of what is going on. Or
+them, watches them, restarts what dies, and shows you one page of what is going on. Split them into
+[workspaces](#-workspaces) when one panel holds more than one setup. Or
 [BYOU](#-bring-your-own-ui-byou), for a specialized UI that fits you exactly.
 
 [![npm](https://img.shields.io/npm/v/home-hosted.svg)](https://www.npmjs.com/package/home-hosted)
@@ -16,7 +17,7 @@ them, watches them, restarts what dies, and shows you one page of what is going
 [![License](https://img.shields.io/npm/l/home-hosted.svg)](./LICENSE)
 [![Node](https://img.shields.io/node/v/home-hosted.svg)](https://nodejs.org)
 
-[🚀 Quick start](#-quick-start) · [🤖 Agents & API](#-agents-scripts-and-tools) · [✨ Features](#-features) · [🧩 Servers](./docs/SERVERS.md) · [🛠 CLI](#-cli) · [🔔 Notifications](./docs/NOTIFICATIONS.md) · [🎨 BYOU](#-bring-your-own-ui-byou)
+[🚀 Quick start](#-quick-start) · [🗂 Workspaces](#-workspaces) · [🧩 Servers](./docs/SERVERS.md) · [🤖 Agents & API](#-agents-scripts-and-tools) · [✨ Features](#-features) · [🛠 CLI](#-cli) · [🔔 Notifications](./docs/NOTIFICATIONS.md) · [🎨 BYOU](#-bring-your-own-ui-byou)
 
 </div>
 
@@ -101,7 +102,7 @@ npx home-hosted down       # stops the panel *and* everything it started
 
 > [!NOTE]
 > The first boot writes a default password (`hh`) so the panel is never unprotected. Change
-> it under **Settings → Authentication** — binding beyond `127.0.0.1` stays refused until you do.
+> it under **Global settings → Authentication** — binding beyond `127.0.0.1` stays refused until you do.
 
 <details>
 <summary><b>📦 Install it instead of npx-ing it</b></summary>
@@ -111,8 +112,8 @@ npm install -g home-hosted      # or: pnpm add -g home-hosted
 home-hosted up                  # `hh up` does the same
 ```
 
-Everything it owns — config, secrets, logs, TLS, backups — lives in `$HHOSTED_HOME`, default
-`~/.home-hosted`. Delete that and nothing of yours is left behind.
+Everything it owns — workspaces, settings, secrets, logs, TLS, backups — lives under
+`$HHOSTED_HOME/.hh`, default `~/.home-hosted/.hh`. Delete that and nothing of yours is left behind.
 
 <sub>An installed home-hosted answers to **`hh`** too — `hh up`, `hh status`, `hh down`. Only the
 installed form gets it; npx stays `npx home-hosted …`.</sub>
@@ -146,9 +147,13 @@ It writes a manifest whose scripts all pass `--home ./state`:
 
 ```gitignore
 node_modules/
-state/*                       # secrets, logs, TLS keys and archives stay local…
-!state/servers.config.json    # …but the server definitions are committed
-data/                         # per-server data directories, declared through dataEnvs
+state/.hh/*                             # secrets, logs, TLS keys and archives stay local…
+!state/.hh/settings.json                 # …but the workspace definitions are committed
+!state/.hh/workspaces.json
+state/.hh/*/*
+!state/.hh/*/settings.json
+!state/.hh/*/servers.config.json
+data/                                   # per-server data directories, declared through dataEnvs
 ```
 
 One clone, `pnpm install --frozen-lockfile`, `pnpm run up` — the setup is up on any machine with Node.
@@ -196,25 +201,27 @@ home-hosted set-token --generate
 #   hh_9uA2…                     (printed once; only its hash is kept, mode 0600)
 
 curl -H "Authorization: Bearer hh_9uA2…" http://127.0.0.1:3999/api/state
-curl -H "Authorization: Bearer hh_9uA2…" -X POST http://127.0.0.1:3999/api/servers/omniroute/restart
-curl -N -H "Authorization: Bearer hh_9uA2…" 'http://127.0.0.1:3999/api/events?serverId=omniroute'   # SSE
+curl -H "Authorization: Bearer hh_9uA2…" -X POST 'http://127.0.0.1:3999/api/servers/omniroute/restart?workspace=default'
+curl -N -H "Authorization: Bearer hh_9uA2…" 'http://127.0.0.1:3999/api/servers/omniroute/stream?workspace=default'   # SSE
 home-hosted status --json        # machine-readable: pid, url, health, paths
 ```
 
 A token has the same authority as a signed-in browser and outlives restarts; `set-token --clear`
-revokes it instantly.
+revokes it instantly. Workspace-scoped routes take `?workspace=<id>`; omitting it means the panel's
+default workspace.
 
 <details>
 <summary><b>🌐 The endpoints worth knowing</b></summary>
 
 | | |
 | --- | --- |
-| `GET /api/state` | the full snapshot: config, live status, host vitals |
-| `GET /api/events` | SSE: the live state, plus logs (`?logs=0`, `?serverId=…`) |
-| `GET /api/servers/:id/stream` | SSE: one server's state and logs |
-| `POST /api/servers/:id/{start,stop,restart}` | lifecycle |
+| `GET /api/state` | the full snapshot: global settings, every workspace with its servers, host vitals |
+| `GET`/`POST /api/workspaces`, `PATCH`/`DELETE /api/workspaces/:id` | the registry: list, create, rename, remove |
+| `GET /api/events` | SSE: the live state, plus logs (`?logs=0`, `?serverId=…`; a `server` payload carries its `workspaceId`) |
+| `GET /api/servers/:id/stream` | SSE: one server's state and logs (`?workspace=…`) |
+| `POST /api/servers/:id/{start,stop,restart}` | lifecycle (workspace-scoped) |
 | `POST /api/servers/:id/free-port` | ask whatever holds that server's port to stop |
-| `PATCH /api/servers/:id`, `PATCH /api/settings` | edit configuration |
+| `PATCH /api/servers/:id`, `PATCH /api/settings`, `PATCH /api/settings/workspace` | edit configuration |
 | `GET /api/logs`, `/api/backups` | history and archives |
 | `PUT`/`DELETE /api/notifications/token`, `POST /api/notifications/{test,detect-chats}` | the bot credential, a test send |
 | `GET /healthz` | no session needed — the one an external monitor wants (its per-server detail needs a credential) |
@@ -246,8 +253,9 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 
 | | |
 | --- | --- |
+| 🗂 **Workspaces** | One panel, many scopes: pick a workspace in the header and it owns its servers, secrets, logs and settings. Create, rename and delete them there. Panel-wide things — listener, auth, host vitals, backups, TLS, UI — stay in **Global settings**. |
 | 🚦 **Lifecycle** | Start, stop, restart from the panel or the API; `autostart` entries come up with it. |
-| 📝 **Hand edits welcome** | Change `servers.config.json` in an editor, a `git checkout` or a config tool: the panel notices within seconds, no restart. A file it cannot read is reported in the panel, and the running servers are left alone. |
+| 📝 **Hand edits welcome** | Change a workspace's `servers.config.json` in an editor, a `git checkout` or a config tool: the panel notices within seconds, no restart. A file it cannot read is reported in the panel, and the running servers are left alone. |
 | ♻️ **Auto-restart** | Exponential backoff on crash, with the counter reset once a process stays up. |
 | 🩺 **Health that acts** | TCP or HTTP probes per server: warn on the card, force a restart after a timeout, check ports before starting — and [follow or replace](./docs/SERVERS.md#when-a-program-restarts-itself) a program that restarts itself. |
 | 🔗 **Ordered startup** | `dependsOn` waits for a dependency to be *healthy* — not merely spawned — and stops in reverse. |
@@ -257,7 +265,7 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 | 🤖 **Token API** | Scripts and agents drive it with `Authorization: Bearer` — no browser, no session. [↑](#-agents-scripts-and-tools) |
 | 🔔 **Notifications** | Telegram on crash, unhealthy, forced restart, recovery, host thresholds and DNS changes — [setup here](./docs/NOTIFICATIONS.md). |
 | 🌐 **Dynamic DNS** | Keep hostnames pointed at your public IP — Cloudflare, Namecheap, Spaceship, Porkbun, GoDaddy, Gandi and more. [DDNS.md](./docs/DDNS.md) |
-| 💾 **Backups** | One click for config, secrets, TLS and your declared data directories — plain `.zip`, or AES-256 with a password, restored per path. |
+| 💾 **Backups** | Two levels: pick global settings, global secrets, TLS or a whole workspace at the top, then the pieces inside it (settings, servers, secrets, data directories) — plain `.zip`, or AES-256 with a password, restored per path. |
 | 🎨 **BYOU — Bring Your Own UI** | Upload a static build, `ui-update` to follow its releases, `ui-revert` to go back. [UI_CREATION.md](./docs/UI_CREATION.md) |
 | 🔐 **Security** | Cookie sessions, API tokens, scrypt hashes, per-IP lockout, optional TLS, and a refusal to expose itself without a password. |
 | 🧩 **No special treatment** | A server is `command` + `args` + `env` + `cwd`; nothing is built in for any particular app. |
@@ -265,9 +273,46 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 
 ---
 
+## 🗂 Workspaces
+
+A workspace is the ownership boundary: its own servers, secrets, logs, nanny state and settings. The
+header picker is the whole control — choose one, create one, rename it, or delete it (which stops
+what it supervises first). The first boot creates a `default` workspace; a pre-workspaces instance is
+relocated into one automatically.
+
+> [!IMPORTANT]
+> **Upgrading from before workspaces (0.6 → 0.7)?** That release is breaking: state moves under
+> `$HHOSTED_HOME/.hh`, settings split global vs. per-workspace, and backups become two-level. The
+> relocation runs on the next command — `home-hosted migrate` reports it and stamps every file. See
+> [Upgrading](#-cli).
+
+| page | url | scope |
+| --- | --- | --- |
+| **Overview** | `/w/<workspace>` | the selected workspace: its servers, counts and live status |
+| **Servers** · **Logs** · **Workspace settings** | `/w/<workspace>/servers` · `/w/<workspace>/logs` · `/w/<workspace>/settings` | the selected workspace |
+| **Global Overview** | `/global/overview` | host vitals plus every server from every workspace |
+| **Global settings** | `/global/settings` | Listener, Authentication, Host vitals, Backups, TLS, Interface, Paths |
+
+Every page is bookmarked by its own URL: the workspace id is part of it, so a link opens the same
+workspace even in a browser that never selected it. `/` opens **Global Overview**. The sidebar lists
+the panel-wide pages first, then the selected workspace's.
+
+<details>
+<summary><b>🗂 What lives where</b></summary>
+
+| | |
+| --- | --- |
+| global — `$HHOSTED_HOME/.hh/` | `settings.json` (listener, auth, TLS, host vitals, backups), `workspaces.json`, `.control-secrets.json` (password + API token, 0600), `.tls/`, `.ui/`, `.backups/`, `.logs/`, `run.json` |
+| workspace — `.hh/<id>/` | `settings.json` (server defaults, logs, notifications, DDNS), `servers.config.json`, `.secrets.json` (Telegram + DDNS credentials, 0600), `.logs/`, `.state/` |
+
+</details>
+
+---
+
 ## 🧩 Servers
 
-An entry is a few lines. Add one with **➕ Add server**, or write it into `servers.config.json`:
+An entry is a few lines. Add one with **➕ Add server**, or write it into the selected workspace's
+`servers.config.json` (`$HHOSTED_HOME/.hh/<workspace>/servers.config.json`):
 
 ```json
 {
@@ -294,11 +339,11 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | `home-hosted down` | stop it cleanly — supervised processes included, persistent entries left running |
 | `home-hosted restart` | `down`, then `up` |
 | `home-hosted status` | pid, URL, health, uptime, state and log paths (`--json` for scripts) |
-| `home-hosted start <id>` | start one server — and anything it `dependsOn` |
-| `home-hosted stop <id>` | stop one server, nothing else |
+| `home-hosted start <id>` | start one server in the default workspace — and anything it `dependsOn` (`--workspace <id>`) |
+| `home-hosted stop <id>` | stop one server, nothing else (`--workspace <id>`) |
 | `home-hosted set-password` | set the panel password without opening a browser |
 | `home-hosted set-token` | set the API token scripts and agents use (`--generate`, `--clear`) |
-| `home-hosted migrate` | bring `servers.config.json` up to this release's schema (`--dry-run`, `--yes`) |
+| `home-hosted migrate` | relocate a pre-workspaces state directory and stamp every config for this release (`--dry-run`, `--yes`) |
 | `home-hosted init` | scaffold a project that keeps `state/` and its data in the repo |
 | `home-hosted ui-switch` | install a UI from a release asset, a zip file or a URL (interactive) |
 | `home-hosted ui-update` | bring an installed UI up to date, or pick a release (`--old`, `--check`) |
@@ -314,7 +359,7 @@ up, restart       -c/--config -p/--port --host --open --no-autostart --foregroun
 
 down              (no flags)
 status            --json
-start, stop       <id>   (the server's id in servers.config.json; both need the panel up)
+start, stop       <id> [-w/--workspace <id>]   (both need the panel up)
 init              --dir --name --pm --no-install -y/--yes
 set-password      --clear
 set-token         --generate --clear
@@ -328,14 +373,34 @@ env vars          HHOSTED_PASSWORD, HHOSTED_MIGRATE=allow, HHOSTED_TOKEN, GITHUB
 ```
 
 `up` and `restart` share the same flags: `restart` is `down`, then `up` with exactly what it was given.
+`-c/--config` is the **default workspace's** servers file (`<state>/.hh/default/servers.config.json`),
+for a launcher that pins one; a workspace picked in the UI keeps its own. `start`/`stop` omit
+`--workspace` to act in the panel's default workspace.
 
 </details>
 
 <details>
 <summary><b>🧭 Upgrading, and why the panel sometimes refuses to start</b></summary>
 
-`servers.config.json` records what wrote it: `meta.writtenBy` (the release) and `meta.schema` (the
-config shape). That buys two guarantees:
+> **Breaking in 0.7 — workspaces.** State moved under `$HHOSTED_HOME/.hh`: global files at its top
+> level, one directory per workspace. Settings split into panel-wide **Global settings** and
+> per-workspace **Workspace settings**, backups became two-level, and `--config` now points at the
+> default workspace's servers file. The old `servers.config.json` becomes
+> `.hh/default/servers.config.json`.
+
+Relocation is automatic: the CLI relocates a pre-`.hh` `$HHOSTED_HOME` before any command runs, so an
+existing instance keeps working after the upgrade. `home-hosted migrate` reports what it moved and
+stamps every file for this release:
+
+```bash
+home-hosted migrate --dry-run   # print the steps, write nothing
+home-hosted migrate             # ask, then write — keeps a .bak beside each rewritten file
+```
+
+Unattended, consent comes from `--yes` or `HHOSTED_MIGRATE=allow`; without it the command stops.
+
+Each config records what wrote it: `meta.writtenBy` (the release) and `meta.schema` (the shape). That
+buys two guarantees:
 
 - **A newer home-hosted always reads an older config** — every existing key keeps its meaning.
 - **Keys a newer release added are ignored, not fatal.** The panel names them in its log, leaves them
@@ -346,15 +411,6 @@ or a config whose schema is newer than the running release stops `up` with the e
 than starting with defaults that quietly differ from your file. Fix the file, or install the release
 that wrote it.
 
-When a release changes the shape itself, `home-hosted migrate` applies the steps it ships:
-
-```bash
-home-hosted migrate --dry-run   # print the steps, write nothing
-home-hosted migrate             # ask, then write — keeps servers.config.json.bak
-```
-
-Unattended, consent comes from `--yes` or `HHOSTED_MIGRATE=allow`; without it the command stops.
-
 </details>
 
 ---
@@ -375,8 +431,10 @@ Everything binds `127.0.0.1` until you say otherwise.
   never taken from the message, and anything the panel supervises is refused, not killed. A server
   that [restarts itself](./docs/SERVERS.md#when-a-program-restarts-itself) can be followed, or replaced
   with a supervised copy.
-- **Secrets never enter the config**: the password hash, the API token hash and the Telegram bot
-  token live in `$HHOSTED_HOME/.control-secrets.json` with mode `0600`; the TLS pair in `.tls/`.
+- **Secrets never enter the config**: the password hash and API token hash live in the global
+  `.hh/.control-secrets.json`, each workspace's Telegram bot token and DDNS credentials in its own
+  `.hh/<workspace>/.secrets.json`, all mode `0600`; the TLS pair sits in `.hh/.tls/`. DDNS credentials
+  are sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET` (default `hh` — set your own).
 - **Behind a proxy** turn on `trustProxy` and let `cookieSecure: auto` add `Secure` on https, or
   upload a PEM pair and let home-hosted terminate TLS itself.
 
@@ -393,19 +451,23 @@ stays in the secrets file. **Two minutes of setup: [NOTIFICATIONS.md](./docs/NOT
 
 ## 🌐 Dynamic DNS
 
-**Settings → Dynamic DNS** keeps a list of hostnames pointed at this machine's public IP — add an
-account, paste its credentials, add hostnames. The panel checks the address on an interval and calls a
-provider only when it actually changed, and the last confirmed address survives a restart. Provider
-tokens stay in the secrets file. **Providers and the config shape: [DDNS.md](./docs/DDNS.md).**
+**Workspace Settings → Dynamic DNS** keeps a list of hostnames pointed at this machine's public IP —
+add an account, paste its credentials, add hostnames. The panel checks the address on an interval and
+calls a provider only when it actually changed, and the last confirmed address survives a restart.
+Provider tokens stay in the workspace's secrets file. **Providers and the config shape:
+[DDNS.md](./docs/DDNS.md).**
 
 ---
 
 ## 💾 Backups
 
-**Settings → Backups** archives the config, secrets, TLS pair and every data directory your entries
-declare — an ordinary `.zip`, or WinZip AES-256 with a password, restored per path. Known build output
-and dependency directories (`node_modules`, `dist`, `.next`, framework caches) are skipped per entry;
-`backupIgnoreGenerated: false` captures them anyway.
+**Global settings → Backups** archives the panel's own settings, its secrets and the TLS pair — plus
+every workspace you pick. It is two-level: the top of *Create backup…* lists the global items and
+each workspace; opening a workspace lists its **settings**, **servers**, **secrets** and every data
+directory its entries declare, and you can drop any single piece. *Restore…* shows the same list from
+an archive before anything is written. Either way it is an ordinary `.zip`, or WinZip AES-256 with a
+password, restored per path. Known build output and dependency directories (`node_modules`, `dist`,
+`.next`, framework caches) are skipped per entry; `backupIgnoreGenerated: false` captures them anyway.
 
 <details>
 <summary><b>🚚 One archive is a whole setup</b></summary>
@@ -414,9 +476,11 @@ Start a **blank** home-hosted anywhere — another machine, another user, a fres
 archive and restore. Definitions come back, data lands where *this* machine's config says, and
 `autostart` entries come up immediately.
 
-It works because an archive carries its own `servers.config.json` and paths are matched by the
-**declaration** (`omniroute:DATA_DIR`), not by an absolute path from the source machine. A restore never
-writes where no config declares.
+It works because an archive carries each workspace's `settings.json` and `servers.config.json`, and
+paths are matched by the **declaration** (`omniroute:DATA_DIR`), not by an absolute path from the
+source machine. A restore never writes where no config declares. A declaration using `{projectDir}`,
+`{dataRoot}` or `{home}` follows the restoring panel (`{projectDir}` is `HHOSTED_PROJECT` or the
+panel's cwd, not `HHOSTED_HOME`); a literal absolute path is restored to that same path.
 
 </details>
 
@@ -424,9 +488,9 @@ writes where no config declares.
 
 ## 🎨 Bring your own UI (BYOU)
 
-The panel is a static site: `$HHOSTED_HOME/.ui` overrides the packaged one, and **Settings →
-Interface** takes a zip. No restart, no fork — and `home-hosted ui-revert` brings back the stock
-panel if yours breaks.
+The panel is a static site: `$HHOSTED_HOME/.hh/.ui` overrides the packaged one, and **Global
+settings → Interface** takes a zip. No restart, no fork — and `home-hosted ui-revert` brings back the
+stock panel if yours breaks.
 
 Two ship in this repo: `uis/stock`, and `uis/noc-console` for TUI and shortcuts wizards; a release
 attaches both as `home-hosted-ui-<name>.zip`. Yours can be anything that compiles to static files —
@@ -486,16 +550,24 @@ opened.
 <details>
 <summary><b>Where is my state?</b></summary>
 
-`$HHOSTED_HOME`, default `~/.home-hosted`:
+`$HHOSTED_HOME/.hh`, default `~/.home-hosted/.hh`. Global files at the top level, one directory per
+workspace:
 
 ```text
-servers.config.json          your servers, plus meta: which release and schema wrote it
-servers.config.schema.json   regenerated on every start, for editor autocomplete
-.control-secrets.json        password hash + API token hash + Telegram token (mode 0600)
-.logs/                       rotated per-server logs + history
+settings.json                panel-wide: listener, auth, TLS policy, host vitals, backups
+workspaces.json              the registry: ids and labels, in selector order
+.control-secrets.json        password hash + API token hash (mode 0600)
 .tls/                        an uploaded PEM pair
+.ui/                         an installed custom UI
 .backups/                    zip archives
+.logs/                       the panel's own console log
 run.json                     the running panel (pid, url, token, mode 0600)
+
+<workspace>/settings.json    server defaults, log retention, notifications, DDNS
+<workspace>/servers.config.json  your servers, plus meta: which release and schema wrote it
+<workspace>/.secrets.json    Telegram token + DDNS credentials (mode 0600)
+<workspace>/.logs/           rotated per-server logs + history
+<workspace>/.state/          persistent entries' nanny state
 ```
 
 `home-hosted status` prints the paths.