home-hosted 0.6.8 → 0.7.1

package/AGENTS.md

@@ -1,24 +1,28 @@
 # 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, and DDNS
-credentials sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET`), `.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
 
 ```sh
 pnpm run up|down|restart|status    # detached; `down` asks /_hh/shutdown, signals are the fallback
 pnpm run start                     # up --foreground (systemd, docker, a foreground shell)
-pnpm dev                           # tsx-watch panel :3999 + the stock UI's Vite :3998 (proxies /api)
+pnpm dev                           # tsx-watch panel :6000 + the stock UI's Vite :6001 (proxies /api), state in .dev-state/
+pnpm dev --ui noc-console          # the same, for another UI; --port/--ui-port override
 pnpm run build                     # dist/cli.js + the stock UI (uis/stock/dist)
 pnpm run build:uis                 # every UI under uis/, zipped into uis/dist/ (release assets)
 pnpm run quickcheck                # eslint + tsc + vue-tsc for every UI under uis/
@@ -33,6 +37,12 @@ pnpm run media                     # regenerate docs/media (mockups, both served
 
 The published bin is `home-hosted`, with an `hh` alias: both names run the same CLI.
 
+**Dev servers and test instances stay in the 6xxx range** — panel 6000, UI 6001, test-spawned panels
+6100+ (`pnpm dev` takes `--ui`/`--port`/`--ui-port`, or `HHOSTED_DEV_PANEL_PORT` /
+`HHOSTED_DEV_UI_PORT`). Never assume 3999 is free: an installed panel or another dev instance may hold
+it, and the CLI's port preflight runs *before* its config guard, so a busy default port turns config
+tests red for the wrong reason.
+
 Releases are dispatched from `.github/workflows/release.yml` with a version (and a `dry-run` switch
 that stops before pushing). It verifies the version, lints/types/tests, builds the CLI plus the stock
 UI and every UI zip, lets changelogen write the changelog, bump `package.json`, commit and tag
@@ -84,10 +94,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),
@@ -96,12 +111,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
@@ -112,7 +128,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.
@@ -141,7 +157,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
@@ -207,9 +223,10 @@ either is a last resort, and never an accidental one.
   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.
 
@@ -217,11 +234,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
@@ -264,8 +283,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
@@ -275,7 +300,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
@@ -285,15 +314,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
@@ -356,8 +385,10 @@ 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`. A change to one

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,10 +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, the Telegram bot
-  token and the DDNS credentials live in `$HHOSTED_HOME/.control-secrets.json` with mode `0600`; the
-  TLS pair in `.tls/`. DDNS credentials are sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET`
-  (default `hh` — set your own).
+- **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.
 
@@ -395,21 +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. *Create backup…*
-lists what the archive will hold and lets you drop any item; *Restore…* shows the same list from an
-archive before anything is written. 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>
@@ -418,11 +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. 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.
+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>
 
@@ -430,9 +488,9 @@ literal absolute path is restored to that same path.
 
 ## 🎨 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 —
@@ -492,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.
@@ -539,9 +605,10 @@ scripts/        builds, typechecks, media capture, release helpers
 test/           the vitest suite
 ```
 
-`pnpm dev` runs the panel with `tsx watch` plus the stock UI's dev server (state goes to
-`.dev-state/`); `pnpm build` produces `dist/` and `uis/stock/dist/`; `pnpm quickcheck` is lint plus
-types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
+`pnpm dev` runs the panel with `tsx watch` plus one UI's dev server on the 6xxx range — panel `6000`,
+UI `6001` (`pnpm dev --ui noc-console`), state in `.dev-state/` — so a dev instance never fights an
+installed panel's 3999. `pnpm build` produces `dist/` and `uis/stock/dist/`; `pnpm quickcheck` is lint
+plus types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
 
 <details>
 <summary><b>📚 Which doc do I need?</b></summary>