@kontextmind/kxm 0.7.164 → 0.7.166

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.164",
+      "version": "0.7.166",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -6,6 +6,31 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **Hub project identity and its access key live in `.kxm/config.yaml`.**
+  `hub.local` and `hub.cloud` hold the URL, the project id to present, and a
+  key reference (`key.op` is an `op://` reference, `key.env` is an environment
+  variable name). A literal token is refused. `op read` runs at use time and
+  the resolved value is not saved. The same order is used everywhere: flag,
+  `KXM_PROJECT`, the active mode's config project, `.kxm/project.yaml`, the
+  package name, then the directory name. `kxm hub bind` and
+  `kxm hub bind --cloud` write the non-secret fields, and `kxm hub view`
+  prints the mode, URL, project id, and key source. The hub's
+  `hub.projects` map uses the same references. `KXM_PROJECT_TOKENS` still
+  replaces that map. Setups whose hub map is keyed by the package name should
+  set `hub.local.project` or `hub.cloud.project` to that name, or keep passing
+  `KXM_PROJECT`: a checkout with `.kxm/project.yaml` otherwise sends that id
+  and gets `project_token_missing`. See
+  [Operate a KXM hub](docs/operations.md#hub-identity-in-config).
+
+- **`kxm hub bind --cloud` attaches a client to a remote hub reached through a loopback forward.**
+  The binding records `--token-env` and/or `--token-command` and never the token.
+  Later commands, including the environment for a Pi worker, use that source and
+  do not fall back to this machine's hub-env token. Peer commands and
+  `kxm tenant status` resolve one project id: flag or `KXM_PROJECT`, then
+  `.kxm/project.yaml`, then `package.json`, then the directory name. The
+  SSH-forward recipe is in
+  [Operate a KXM hub](docs/operations.md#cross-box-peer-attach).
+
 - **A live agent step uses a configurable one-shot timeout, and a cancelling run recovers when its child has already exited.**
   The bound is the step `timeoutMs`, or the project `limits.agentStepTimeoutMs`
   when the step omits it (minimum 60 seconds, default one hour). A wider step

package/README.md

@@ -105,6 +105,8 @@ You need Node.js 22.19 or newer on the 22.x line, or Node.js 24 or newer, plus G
    kxm hub view
    ```
 
+   A hub on another machine, reached through an SSH forward to loopback, uses `kxm hub bind --cloud` so this machine's hub-env token is not sent. The recipe is in [Operate a KXM hub](docs/operations.md#cross-box-peer-attach).
+
    Expected output:
 
    ```text

package/docs/README.md

@@ -96,6 +96,7 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 
 | Page | For | What you get |
 |---|---|---|
+| [Operate a KXM hub](operations.md) | Hub operators | Index of the operations guides, and cross-box attach over an SSH forward |
 | [Deploy KXM](operations/deploy.md) | Hub operators | Deployment classes, supervision, and hosted per-tenant hubs behind a proxy |
 | [Monitor KXM](operations/monitoring.md) | Hub operators | `kxm dash`, health and readiness, metrics, logs and alerts |
 | [Back up and restore KXM](operations/backup-and-restore.md) | Hub operators | `kxm backup` and `kxm restore`, the state roots, and a stopped-hub recipe |

package/docs/architecture/inventory.md

@@ -32,9 +32,10 @@ On macOS the user state root is `Library/Application Support/KXM` under the
 home directory (`kxmUserStateRoot` in `plugins/kxm/src/bindings.ts`). Windows
 uses `AppData/Local/KXM`. Other platforms use `$XDG_STATE_HOME/kxm` or
 `.local/state/kxm`. `KXM_STATE_HOME` overrides that root when it is absolute.
-The tracker mentions `docs/operations.md` for the six backup roots. That file
-is not in this checkout. The six roots are described in
-[Backup and restore](../operations/backup-and-restore.md).
+The tracker mentions `docs/operations.md` for the six backup roots. That page
+indexes the operations guides and links the six roots to
+[Backup and restore](../operations/backup-and-restore.md). It also holds
+[Cross-box peer attach](../operations.md#cross-box-peer-attach).
 
 ## Related
 

package/docs/concepts/trust-model.md

@@ -56,7 +56,7 @@ flowchart LR
 - **Claude Code plugin.** The MCP server uses the plugin's `auth_token` setting, else the project token the hub saved for this project. It never falls back to the saved admin token; without a project token, its tools report that and do nothing.
 - **SessionStart hook.** It reads local state read-only. It mints no token, writes no file, and never prints a token.
 - **Pi extension.** It uses `KXM_AUTH_TOKEN`, else the project token the hub saved for this project. It never uses the saved admin token, nor the one a hub it auto-started generated; without a project token it reports the fix and stays offline.
-- **`kxm peer` and `kxm workflow` agent commands.** They act as a peer agent, so they choose a token as the Pi extension does, and exit 2 with `project_token_missing` when none resolves.
+- **`kxm peer` and `kxm workflow` agent commands.** They act as a peer agent, so they choose a token as the Pi extension does, and exit 2 with `project_token_missing` when none resolves. The message names the project id that was sent and where it came from.
 - **Dashboard and Runtime supervisor.** Operator tools use `KXM_AUTH_TOKEN`, else the saved project token, else the saved admin token.
 
 ## Project isolation

package/docs/glossary.md

@@ -38,7 +38,7 @@ The service that authenticates [agents](#agent), stores [messages](#message) and
 
 ### Hub binding
 
-The record that `kxm hub bind <url>` writes to `hub-binding.json` in the [user state root](#user-state-root), naming the hub this machine uses. `kxm hub view` checks it, and the Runtime syncs to it. Binding a remote hub requires a credential.
+The record that `kxm hub bind <url>` writes to `hub-binding.json` in the [user state root](#user-state-root), naming the hub this machine uses. `kxm hub view` checks it, and the Runtime syncs to it. Binding a remote hub requires a credential. `kxm hub bind --cloud` marks a loopback forward as remote and records a token variable or command, never the token.
 
 ### KontextMind
 
@@ -104,15 +104,15 @@ Another [agent](#agent) in the same [project](#project). `kxm_list` and `kxm pee
 
 ### Project
 
-The authentication and discovery namespace on the hub. An agent names it with `KXM_PROJECT` (otherwise the `package.json` name, then the directory name), and its key in the hub's `KXM_PROJECT_TOKENS` holds its token. Agents see only peers in the same project. Compare [project ID](#project-id).
+The authentication and discovery namespace on the hub. Every command resolves it the same way: `--project` or `KXM_PROJECT`, then the active mode's `project` in `.kxm/config.yaml`, then the [project ID](#project-id) in `.kxm/project.yaml`, then the `package.json` name, then the directory name. Its token is a key reference in that config, or the matching key in the hub's `KXM_PROJECT_TOKENS`. Agents see only peers in the same project.
 
 ### Project ID
 
-The stable `prj_` identifier in `.kxm/project.yaml`. The [Runtime](#runtime) and hub sync use it. It is not the hub [project](#project) name, even though both describe the same body of work.
+The stable `prj_` identifier in `.kxm/project.yaml`. It is the hub [project](#project) name unless `--project` or `KXM_PROJECT` overrides it. The [Runtime](#runtime) store keeps this id as the local key.
 
 ### Project token
 
-The credential that the agents of one [project](#project) use. The operator sets it in the hub's `KXM_PROJECT_TOKENS` JSON map, and agents receive it as `KXM_AUTH_TOKEN` or the plugin's `auth_token`. Setting `KXM_PROJECT_TOKENS` replaces the hub's saved map, so list every project each time.
+The credential that the agents of one [project](#project) use. The operator points config at it with `key.op` (`op://vault/item/field`) or `key.env` (an environment variable name), or sets the hub's `KXM_PROJECT_TOKENS` JSON map. The config file never holds the token. Agents receive the resolved value as `KXM_AUTH_TOKEN` or the plugin's `auth_token`. Setting `KXM_PROJECT_TOKENS` replaces the hub's saved map, so list every project each time. A config `hub.projects` map is resolved in memory and is not saved.
 
 ### Session token
 

package/docs/operations/troubleshooting.md

@@ -87,6 +87,9 @@ If a malformed claim remains, read the exact `.pid` JSON in the state directory
 | `hub_url_invalid` | Use an `http` or `https` URL without user info, query or fragment |
 | `hub_bind_unauthenticated` | The URL is remote and this machine has no token for the project; export it and bind again |
 | `hub_credential_unreadable` | Repair or remove `hub-env.json` under the user state root |
+| `cloud_token_missing` | A `--cloud` binding's variable is empty and it has no working command. Export the variable or fix `--token-command`. This machine's hub-env token is not sent |
+| `cloud_flag_required` | `--token-command` was passed without `--cloud`. `--token-env` and `--key-op` are key references and are valid on a local bind |
+| 401 after binding a loopback forward | The bind was not `--cloud`, so the client sent the local hub-env token. See [Cross-box peer attach](../operations.md#cross-box-peer-attach) |
 
 ## Claude Code plugin and MCP
 
@@ -96,7 +99,7 @@ The [plugin troubleshooting guide](../../plugins/kxm/README.md#troubleshooting)
 |---|---|
 | `kxm_*` tools do not appear | Check `/mcp` for the `kxm` server, check `node --version`, run `/reload-plugins`, and confirm `claude plugin list` shows `kxm@kxm` enabled |
 | `KXM hub unreachable at <url>` | Start the hub, or correct `server_url` with `/plugin configure kxm@kxm` |
-| `no project token for project <p>` | Enter the project token at `/plugin configure kxm@kxm`, or add `<p>` to the hub's full `KXM_PROJECT_TOKENS` map and restart the hub |
+| `kxm has no project token for project <p>` | The message names where `<p>` came from. Set `hub.local.project` or `hub.cloud.project` and a key reference in `.kxm/config.yaml`, or add `<p>` to the hub's full `KXM_PROJECT_TOKENS` map and restart the hub. Never paste the token into the file |
 | `KXM hub rejected the project token for project <p>` | Enter the token the hub holds for `<p>` |
 | `tool_policy_denied: Session token on disk is malformed or expired` | Run `kxm session token --clear` |
 | Pushed requests never arrive | Start Claude Code with `claude --dangerously-load-development-channels plugin:kxm@kxm` and accept the trust prompt, or use `kxm_inbox` and `kxm_reply` |

package/docs/operations.md

@@ -0,0 +1,208 @@
+# Operate a KXM hub
+
+This page is the operator index for a [hub](glossary.md#hub): where the other
+operations guides live, and how to attach a client on another machine to a hub
+that is not reachable from the internet. The client in that setup is a local
+`kxm` CLI, plus the Pi and Claude Code agents that CLI starts.
+
+## Where each procedure lives
+
+| Procedure | Page |
+|---|---|
+| Install the services on a tenant box, including loopback listeners | [Deploy KXM](operations/deploy.md) |
+| Health, readiness, metrics, logs, and alerts | [Monitor KXM](operations/monitoring.md) |
+| Stopped-state backup of all six state roots, and restore | [Back up and restore KXM](operations/backup-and-restore.md) |
+| Package update, plugin reinstall, and schema ceilings | [Upgrade KXM](operations/upgrade.md) |
+| Runtime outbox, sync refusals, and hub leases | [Operate Runtime sync and leases](operations/runtime-sync.md) |
+| Symptoms, causes, and fixes | [Troubleshoot KXM](operations/troubleshooting.md) |
+
+The six roots are the checkout, the workspace, workspace state, the user state
+root, user config, and federated telemetry. The stopped-state copy of each one
+is in [Back up and restore KXM](operations/backup-and-restore.md).
+
+## Before you begin
+
+- The `kxm` CLI is installed on the client machine.
+- You can open SSH to the hub host, and you already have that host's key.
+- The hub's admin token is in a password manager. 1Password CLI (`op`) is the
+  usual source. The token is never written into `hub-binding.json`.
+
+## Cross-box peer attach
+
+Use this when the hub listens on loopback on a private machine and your client
+reaches it through an SSH local forward. A plain `kxm hub bind` of
+`http://127.0.0.1:17331` is a loopback bind: it stores no credential, and later
+commands send this machine's hub-env admin token. The remote hub rejects that
+token with 401. `--cloud` marks the binding remote even though the URL is
+loopback, and names where the token comes from without storing the token.
+
+### Open the forward with a pinned host key
+
+Pin the host key before the first connection. Do not accept a key on first use.
+
+```bash
+ssh-keyscan -H 10.31.0.21 >> ~/.ssh/known_hosts
+ssh -N \
+  -o ExitOnForwardFailure=yes \
+  -o StrictHostKeyChecking=yes \
+  -o UserKnownHostsFile="$HOME/.ssh/known_hosts" \
+  -L 127.0.0.1:17331:127.0.0.1:7331 \
+  user@10.31.0.21
+```
+
+Leave that SSH session open. Hub traffic then goes to `127.0.0.1:17331` on the
+client and comes out on the hub host's loopback port 7331.
+
+<details><summary>PowerShell</summary>
+
+```powershell
+ssh-keyscan -H 10.31.0.21 >> $env:USERPROFILE\.ssh\known_hosts
+ssh -N `
+  -o ExitOnForwardFailure=yes `
+  -o StrictHostKeyChecking=yes `
+  -o UserKnownHostsFile="$env:USERPROFILE\.ssh\known_hosts" `
+  -L 127.0.0.1:17331:127.0.0.1:7331 `
+  user@10.31.0.21
+```
+
+</details>
+
+### Bind the forward as a cloud hub
+
+Pick one token source. The environment variable is enough when the shell
+already holds the token. The command form asks 1Password each time a command
+needs the token. Do not put the token text in `--token-command`: that string
+is stored in the binding.
+
+```bash
+export KXMD_HUB_TOKEN="$(op read 'op://Private/kxmd/admin-token')"
+kxm hub bind --cloud --token-env KXMD_HUB_TOKEN http://127.0.0.1:17331
+kxm hub view
+```
+
+Or name the 1Password command and skip the variable:
+
+```bash
+kxm hub bind --cloud \
+  --token-command "op read op://Private/kxmd/admin-token" \
+  http://127.0.0.1:17331
+```
+
+Expected output:
+
+```text
+bound hub http://127.0.0.1:17331 · remote · health=on · token is not stored
+hub health=true ready=true · remote hub · mode=cloud project=prj_example (.kxm/config.yaml hub.cloud.project) key=env:KXMD_HUB_TOKEN
+```
+
+`--token-env` and `--token-command` can be combined. A non-empty variable wins.
+Otherwise the command runs. The command is a program and arguments, not a shell
+pipeline (`|`, `&`, `;`, and redirection are refused).
+
+<details><summary>PowerShell</summary>
+
+```powershell
+$env:KXMD_HUB_TOKEN = op read "op://Private/kxmd/admin-token"
+kxm hub bind --cloud --token-env KXMD_HUB_TOKEN http://127.0.0.1:17331
+kxm hub view
+```
+
+</details>
+
+### What --cloud changes
+
+| | Local bind | `--cloud` bind |
+|---|---|---|
+| Loopback URL | Scope `loopback`. No credential required | Scope `remote`, including an SSH forward |
+| Token stored in `hub-binding.json` | No | No. The file names `tokenEnv` and/or `tokenCommand` |
+| Credential later commands send | `KXM_AUTH_TOKEN`, then the active mode's key reference in `.kxm/config.yaml`, then this machine's hub-env | The active mode's key reference, then the binding's named source. Hub-env is not a fallback |
+| Missing source | Agent commands report `project_token_missing` and name the project id that was sent | `cloud_token_missing` or `cloud_token_command_failed`. The local admin token is not sent |
+| `kxm hub start` from an extension | May start a local hub | Does not start a local hub when the forward is down (`cloud_hub_unreachable`) |
+
+`kxm hub view`, `kxm tenant status`, `kxm peer`, `kxm workflow` agent commands,
+`kxm context`, Runtime presence, and the environment exported for a Pi worker
+all use that source. `kxm agent worker` puts `KXM_AUTH_TOKEN` in the child
+process environment only. It does not write the token to disk.
+
+The hub project id is the same value everywhere: `--project` or `KXM_PROJECT`,
+then the active mode's `project` in `.kxm/config.yaml`, then the `id` in
+`.kxm/project.yaml`, then `package.json` `name`, then the directory name.
+
+### Hub identity in config
+
+Hub URL, mode, project id, and key reference live in `.kxm/config.yaml`
+(`kxm.config.v1`), the same file as `hub.autoStart`. `.kxm/project.yaml` stays
+the stable project id. The project file wins over
+`~/.config/kxm/config.yaml`. `KXM_PROJECT` and `KXM_SERVER_URL` select the
+live connection for one process. They do not rewrite the file.
+
+```yaml
+hub:
+  autoStart: background
+  mode: local                 # local | cloud
+  local:
+    url: http://127.0.0.1:7331
+    project: prj_example      # optional; defaults to the project.yaml id
+    key:
+      op: op://Private/kxm/local-project-token
+      env: KXM_LOCAL_PROJECT_TOKEN
+  cloud:
+    url: https://hub.kxmd.dev
+    project: prj_example
+    key:
+      op: op://Private/kxmd/project-token
+      env: KXMD_HUB_TOKEN
+  projects:                   # hub process map; references only
+    prj_example:
+      op: op://Private/kxm/local-project-token
+      env: KXM_LOCAL_PROJECT_TOKEN
+```
+
+`key.op` is an `op://vault/item/field` reference. `key.env` is an environment
+variable name. A non-empty variable wins; otherwise `op read` runs when the
+client or the hub needs the token. The resolved value is not written to
+config, `hub-binding.json`, or `hub-env.json`. A literal token is refused
+with `hub_config_invalid`.
+
+`kxm hub bind` and `kxm hub bind --cloud` write the mode, URL, project id, and
+key reference. `--key-op` is the `op://` reference for either mode.
+`--token-env` names the variable for either mode. `--token-command` stays
+cloud-only. `kxm hub view` prints the mode, URL, project id, and key source.
+It does not print the token. `kxm hub unbind` removes the binding and
+`hub.mode`, and leaves the `local` and `cloud` blocks in place.
+
+On the hub, `hub.projects` is that same kind of map. `KXM_PROJECT_TOKENS`
+still replaces the map and is saved. A config map is resolved in memory and
+does not replace the saved file.
+
+A setup whose hub map is still keyed by the package name should set
+`hub.local.project` or `hub.cloud.project` to that name. Otherwise clients
+send the `.kxm/project.yaml` id and the hub has no token for it.
+
+### Remove the binding
+
+```bash
+kxm hub unbind
+```
+
+Unbind deletes `hub-binding.json` and clears `hub.mode` in `.kxm/config.yaml`.
+The `local` and `cloud` blocks stay, so the next bind can switch mode again.
+It does not delete hub-env, and it does not close the SSH forward. Stop the
+forward by ending the `ssh -N` session.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| 401 `invalid_auth` after binding `127.0.0.1:17331` | The bind was not `--cloud`, so the client sent this machine's hub-env admin token | Bind again with `--cloud` and a token source that holds the remote hub's token. Unset a stale `KXM_AUTH_TOKEN` that points at the local hub |
+| `cloud_token_missing` | `KXMD_HUB_TOKEN` (or the variable you named) is unset or empty, and no command is configured | Export the variable or pass `--token-command`. The local hub-env token is intentionally unused |
+| `project_token_missing` | The project id sent to the hub has no agent token. The message names that id and where it came from | Set `hub.local.project` or `hub.cloud.project` in `.kxm/config.yaml` to the id the hub already knows, and point `key.op` or `key.env` at the token. `KXM_PROJECT` or `--project` overrides the id for one command. Do not paste the token into the file |
+| `cloud_token_command_failed` | `op` exited non-zero, timed out, or printed more than one line | Run the same command in a terminal and sign in to 1Password. Do not paste the token into the binding |
+| Clients through one SSH host get locked out together | The hub rate-limits by agent id, otherwise by source address. Every forward from one SSH session shares `127.0.0.1` on the hub. `sshd` `MaxStartups` and `MaxSessions` can refuse new forwards first | Give each long-lived agent its own name. Raise the SSH limits on that host if many people share one jump host. Do not point two tenants at one hub |
+| `kxm hub view` says `loopback` for the forward | `--cloud` was omitted | Bind again with `--cloud`. `KXM_SERVER_URL` overrides the binding URL and is labeled on its own |
+
+## Next steps
+
+- Deploy the hub itself: [Deploy KXM](operations/deploy.md)
+- Read health and metrics: [Monitor KXM](operations/monitoring.md)
+- Command flags: [kxm hub bind](reference/cli-reference.md#kxm-hub-bind)

package/docs/reference/cli-reference.md

@@ -477,20 +477,20 @@ Starts, inspects, and stops the local KXM hub, and binds this machine to a hub.
 kxm hub view
 ```
 
-Calls `GET /health` and `GET /ready` on the target hub and reports whether the URL is loopback or remote.
+Calls `GET /health` and `GET /ready` on the target hub and reports whether the URL is loopback or remote, plus the mode, project id, and key source in effect. The key source is an environment variable name or an `op://` reference. The token is not printed.
 
 No command-specific options.
 
 - Needs a hub to succeed. Reads only.
-- JSON keys: `target` (`url`, `scope`, and `source: "env"` when `KXM_SERVER_URL` overrides a binding), `health`, `ready`. An unreachable hub reports `{"error":"hub_unreachable"}` for both probes.
-- Exit 0 when both probes succeed, 1 otherwise.
+- JSON keys: `target` (`url`, `scope`, and `source: "env"` when `KXM_SERVER_URL` overrides a binding), `identity` (`mode`, `modeSource`, `url`, `urlSource`, `project`, `projectSource`, `keySource`), `health`, `ready`. An unreachable hub reports `{"error":"hub_unreachable"}` for both probes.
+- Exit 0 when both probes succeed, 1 otherwise. A cloud mode with no resolvable key exits 2 with `cloud_token_missing`.
 
 ```bash
 kxm hub view
 ```
 
 ```text
-hub health=true ready=true · loopback hub
+hub health=true ready=true · loopback hub · mode=local project=prj_example (.kxm/project.yaml id) key=hub-env
 ```
 
 ```bash
@@ -569,16 +569,17 @@ kxm hub stop --wait-ms 8000 --json
 ### `kxm hub bind`
 
 ```text
-kxm hub bind <url>
+kxm hub bind <url> [--cloud] [--token-env <name>] [--token-command <command>] [--key-op <op://vault/item/field>]
 ```
 
-Binds this machine to a running hub by writing `hub-binding.json` under the user state root, then probes the hub's health for up to 300 ms. Every hub client uses the binding when `KXM_SERVER_URL` is unset.
+Binds this machine to a running hub by writing `hub-binding.json` under the user state root and the non-secret endpoint (mode, URL, project id, key reference) into `.kxm/config.yaml`, then probes the hub's health for up to 300 ms. Every hub client uses that endpoint when `KXM_SERVER_URL` is unset. The token is never written.
 
 - Arguments: `<url>`, Hub base URL (http or https).
 - A URL with credentials, a query, a fragment, or a scheme other than http or https fails with `hub_url_invalid` (exit 2).
-- A remote (non-loopback) URL is refused with `hub_bind_unauthenticated` (exit 2, `nextAction: "export_kxm_auth_token"`) unless a credential for the current project resolves from `KXM_AUTH_TOKEN` or the persisted `hub-env.json`. A malformed record fails with `hub_credential_unreadable` (exit 2).
-- Mutates the binding file. `--dry-run` validates and prints the plan without writing.
-- JSON keys: `url`, `scope`, `file`, `health` (`on`, `off`, or `unknown`), `probeMs`.
+- A remote (non-loopback) URL is refused with `hub_bind_unauthenticated` (exit 2, `nextAction: "export_kxm_auth_token"`) unless a credential for the current project resolves from `KXM_AUTH_TOKEN` or the persisted `hub-env.json`. A malformed record fails with `hub_credential_unreadable` (exit 2). A loopback URL without `--cloud` still binds with no credential.
+- `--cloud` marks the binding remote even when the URL is a loopback forward. It requires `--token-env`, `--token-command`, `--key-op`, or a combination. The token is not written. A non-empty variable wins; otherwise an `op://` reference is read with `op read`, or the command runs. `--token-command` without `--cloud` fails with `cloud_flag_required`. `--token-env` and `--key-op` are also valid on a local bind and are stored only as references in config. A missing cloud source later fails with `cloud_token_missing` and does not fall back to hub-env. See [Cross-box peer attach](../operations.md#cross-box-peer-attach).
+- Mutates the binding file and `.kxm/config.yaml`. `--dry-run` validates and prints the plan without writing.
+- JSON keys: `url`, `scope`, `file`, `configFile`, `project`, `health` (`on`, `off`, or `unknown`), `probeMs`. A cloud bind also returns `cloud`, and `tokenEnv` or `tokenCommand` when set.
 
 ```bash
 kxm hub bind http://127.0.0.1:7331 --dry-run
@@ -602,7 +603,7 @@ kxm hub bind https://hub.example.com --dry-run --json
 kxm hub unbind
 ```
 
-Removes this machine's hub binding, including a malformed binding record.
+Removes this machine's hub binding, including a malformed binding record, and clears `hub.mode` in `.kxm/config.yaml`. The `hub.local` and `hub.cloud` blocks stay.
 
 No command-specific options.
 
@@ -2468,7 +2469,7 @@ Captured without a GitHub token. With `GITHUB_TOKEN` set, the same command polls
 
 ## `kxm peer`
 
-Peer agent messaging through the hub. Each invocation connects to the hub as a short-lived agent named `KXM_AGENT_NAME` (default `cli-<pid>`) in project `KXM_PROJECT` (default: the `package.json` name, else the directory name), using `KXM_AUTH_TOKEN`, else this project's saved project token from `hub-env.json`. It never uses the persisted admin token: with neither, the command exits 2 with `project_token_missing` (`nextAction: "export_kxm_auth_token"`) before contacting the hub. The `kxm workflow` agent verbs (`checkpoint`, `record`, `wait`, `get`, `list`) connect the same way. That agent appears in `peer list` and the dashboard. Every subcommand accepts `--payload <json>` with the tool's fields as one object; explicit flags override it. Tool policy from `KXM_ATTEMPT_TOKEN`, `KXM_SESSION_TOKEN`, or the on-disk session token is enforced first (`tool_policy_denied`, `session_token_invalid`, `attempt_token_invalid`).
+Peer agent messaging through the hub. Each invocation connects to the hub as a short-lived agent named `KXM_AGENT_NAME` (default `cli-<pid>`). The project id is `--project`, then `KXM_PROJECT`, then the active mode's `project` in `.kxm/config.yaml`, then the `id` in `.kxm/project.yaml`, then the `package.json` name, then the directory name. The token is `KXM_AUTH_TOKEN`, else the active mode's key reference, else this project's saved project token from `hub-env.json`. It never uses the persisted admin token: with none of those, the command exits 2 with `project_token_missing` (`nextAction: "configure_hub_project"`) and names the project id and where it came from, before contacting the hub. The `kxm workflow` agent verbs (`checkpoint`, `record`, `wait`, `get`, `list`) connect the same way. That agent appears in `peer list` and the dashboard. Every subcommand accepts `--payload <json>` with the tool's fields as one object; explicit flags override it. Tool policy from `KXM_ATTEMPT_TOKEN`, `KXM_SESSION_TOKEN`, or the on-disk session token is enforced first (`tool_policy_denied`, `session_token_invalid`, `attempt_token_invalid`).
 
 All subcommands need a hub, honor `--dry-run` (printing the parsed `args` without connecting), print the hub's result object on success, and print `{"ok":false,"error":"command_failed","detail":"..."}` with exit 1 on failure. Malformed `--payload` exits 2 with `invalid_payload`.
 

package/docs/reference/config-reference.md

@@ -1255,20 +1255,28 @@ in `plugins/kxm/src/config.ts`, then the user file
 `$KXM_USER_CONFIG_DIR/config.yaml` (default `~/.config/kxm/config.yaml`), then
 the project file `.kxm/config.yaml` in the current directory. Later layers win
 key by key; arrays are replaced, not merged. The files need no `schema` key.
-Nothing validates keys or values except `hub.autoStart` and the `improvement.*`
-keys, which fall back to their defaults field by field (see the table), but a file
-that is not valid YAML makes every `kxm config` command fail. `kxm improve` loads
-the project file from its project root (the current directory's Git root when it
-holds `.kxm/project.yaml`) rather than from the current directory.
-
-Two groups of keys change behavior today: `hub.autoStart`, and the `improvement.*`
-keys that shape the report `kxm improve` prints. The **Read by** column lists every
-reader found in `plugins/kxm/src`, `scripts/`, and `packages/`; the `kxm config`
-commands themselves are not counted.
+`hub.autoStart` and the `improvement.*` keys fall back to their defaults field
+by field (see the table). `hub.mode`, `hub.local`, `hub.cloud`, and
+`hub.projects` are validated: a literal token is refused with
+`hub_config_invalid`, and a mode other than `local` or `cloud` is refused. A
+file that is not valid YAML makes every `kxm config` command fail. `kxm improve`
+loads the project file from its project root (the current directory's Git root
+when it holds `.kxm/project.yaml`) rather than from the current directory.
+
+The keys that change behavior are the `hub` section below and the
+`improvement.*` keys that shape the report `kxm improve` prints. Hub URL, mode,
+project id, and key reference live here rather than in `.kxm/project.yaml`
+because `hub.autoStart` was already this file's hub setting, and
+`project.yaml` stays the stable hashed project id. The **Read by** column lists
+every reader found in `plugins/kxm/src`, `scripts/`, and `packages/`; the
+`kxm config` commands themselves are not counted.
 
 | Key | Type and allowed values | Default | Read by |
 |---|---|---|---|
 | `hub.autoStart` | `background` or `off`; any other value falls back to `background` | `background` | The Pi extension on load (`plugins/kxm/src/extension.ts`, `hub-autostart.ts`) |
+| `hub.mode` | `local` or `cloud`. Any other value is `hub_config_invalid`. Unset means local unless a cloud binding exists | unset | Every hub client (`hub-identity.ts`): CLI, Pi extension, MCP server, dash, and `kxm agent worker` |
+| `hub.local`, `hub.cloud` | `url` (http or https, no userinfo, query, or fragment), `project` (one line, no spaces), and `key` | unset | The same clients, for the active mode. `project` defaults to the `.kxm/project.yaml` id when omitted |
+| `hub.local.key`, `hub.cloud.key`, `hub.projects.<id>` | `op` is `op://vault/item/field`. `env` is an environment variable name. A string, or a field named like a token, is refused | unset | Clients resolve the active mode's key at use time. The hub process resolves `hub.projects` in memory (`server.ts`). Neither writes the resolved token |
 | `user.name`, `user.email` | String | none | Not read by any code path yet |
 | `user.preferredHarness`, `user.preferredModel` | String | none | Not read by any code path yet |
 | `user.preferredCritics` | Array of strings | `[reviewer-arch, reviewer-cli]` | Not read by any code path yet |
@@ -1302,9 +1310,26 @@ no recorded cost is never ready.
 
 ```yaml
 # .kxm/config.yaml (project scope) or ~/.config/kxm/config.yaml (user scope).
-# Only hub.autoStart and improvement.* change behavior today.
+# The project file wins. Key fields are references, never tokens.
 hub:
   autoStart: background        # background | off
+  mode: local                  # local | cloud
+  local:
+    url: http://127.0.0.1:7331
+    project: prj_example
+    key:
+      op: op://Private/kxm/local-project-token
+      env: KXM_LOCAL_PROJECT_TOKEN
+  cloud:
+    url: https://hub.kxmd.dev
+    project: prj_example
+    key:
+      op: op://Private/kxmd/project-token
+      env: KXMD_HUB_TOKEN
+  projects:
+    prj_example:
+      op: op://Private/kxm/local-project-token
+      env: KXM_LOCAL_PROJECT_TOKEN
 improvement:
   promotionPolicy: manual_pr   # manual_pr | critic_quorum | auto_threshold (readiness only)
   telemetryHalfLifeDays: 14

package/docs/reference/configuration.md

@@ -108,7 +108,7 @@ Every agent client (the Pi extension, the Claude Code MCP server, and the `kxm p
 |---|---|---|
 | `KXM_SERVER_URL` | `http://127.0.0.1:7331` | Hub base URL. For the CLI, the machine's `kxm hub bind` URL is used when this is unset |
 | `KXM_AUTH_TOKEN` | See below | The project token for this agent's project |
-| `KXM_PROJECT` | `name` in `package.json` in the working directory, else the directory name | Project for discovery and authentication |
+| `KXM_PROJECT` | Active mode's `project` in `.kxm/config.yaml`, else `id` in the nearest `.kxm/project.yaml`, else `name` in `package.json` in the working directory, else the directory name | Project for discovery and authentication. An explicit `--project` flag wins over this variable, and this variable wins over the config file. The same resolver is used by peer commands, tenant status, workers, the Pi extension, dash, and the Claude Code MCP server |
 | `KXM_AGENT_NAME` | Harness-specific (see below) | Name peers see; unique among online agents in the project, compared case-insensitively |
 | `KXM_AGENT_PURPOSE` | Harness-specific (see below) | One line peers use to decide what to send this agent |
 
@@ -120,6 +120,16 @@ Every agent client (the Pi extension, the Claude Code MCP server, and the `kxm p
 
 A clean shutdown marks an identity offline. Reconnecting with the same project and name resumes its durable agent ID and rotates its agent key. If the Claude Code name is already online in the project, the MCP server registers once more as `<name>-<pid>`.
 
+A cloud hub mode replaces this table's token lookup for every client, including agents. The token comes from that mode's key reference in `.kxm/config.yaml` (`key.env`, then `key.op` via `op read`), then from the binding's `--token-env` or `--token-command`. It never comes from this machine's hub-env file, and it is not written to disk. `kxm agent worker` copies it into the child process environment as `KXM_AUTH_TOKEN`. Local mode uses `KXM_AUTH_TOKEN`, then the local key reference, then the saved project token, and still never the admin token.
+
+Also check plugin.json is valid JSON.
+
+And configuration table cell might be very long. That's ok.
+
+Look at harness table "never the admin token" - the new paragraph clarifies cloud. Good.
+
+Plugin README add one sentence under which token.
+
 ## Claude Code plugin settings
 
 The plugin asks for `server_url`, `auth_token`, `agent_name`, `agent_purpose` and `project` when you install it, and passes them to its MCP server as `KXM_SERVER_URL`, `KXM_AUTH_TOKEN`, `KXM_AGENT_NAME`, `KXM_AGENT_PURPOSE` and `KXM_PROJECT`. It also sets `KXM_PROJECT_DIR` to the directory Claude Code started in. Change them with `/plugin configure kxm@kxm`. Every field, default and token rule is in [Claude Code plugin settings](config-reference.md#claude-code-plugin-settings) and the [plugin README](../../plugins/kxm/README.md).

package/docs/reference/tools.md

@@ -64,7 +64,7 @@ Every tool returns its result as JSON text; Pi also attaches the same value as s
 
 | Error text | Harness | Fix |
 |---|---|---|
-| `KXM has no project token for project <p> on this machine` | Claude Code | Set `auth_token` with `/plugin configure kxm@kxm`, or [give the project a token](../start/quickstart-claude-code.md#give-the-project-a-token-on-the-running-hub) on the hub |
+| `kxm has no project token for project <p>` | Claude Code and the Pi extension | The message names where `<p>` came from. Set `hub.local.project` or `hub.cloud.project` and a key reference in `.kxm/config.yaml`, set `auth_token` with `/plugin configure kxm@kxm`, or [give the project a token](../start/quickstart-claude-code.md#give-the-project-a-token-on-the-running-hub) on the hub |
 | `KXM hub unreachable at <url> (<cause>)` | Claude Code | Start the hub with `kxm hub start`, or correct `server_url` |
 | `KXM hub rejected the project token for project <p>` | Claude Code | Enter that project's token from the hub's `KXM_PROJECT_TOKENS` |
 | `kxm hub is not connected; check KXM_SERVER_URL and /kxm hub` | Pi | Start the hub or fix `KXM_SERVER_URL`, then restart the session |

package/docs/start/quickstart-claude-code.md

@@ -181,7 +181,7 @@ Claude Code asks for these options at install. Change them later with `/plugin c
 | `auth_token` | Blank | Blank on the machine that runs the hub. Elsewhere, this project's token. Never the admin token. |
 | `agent_name` | `claude` | The name peers see. A second concurrent session in the project registers as `<name>-<pid>`. |
 | `agent_purpose` | `Claude Code implementation and review agent` | One line that peers use to decide what to send this agent |
-| `project` | Blank | `<hub-project>`. Blank uses the `name` in `package.json`, then the directory name. |
+| `project` | Blank | `<hub-project>`. Blank uses `hub.local.project` or `hub.cloud.project` in `.kxm/config.yaml` for the active mode, then the `id` in `.kxm/project.yaml`, then the `name` in `package.json`, then the directory name. |
 
 With a blank `auth_token`, the plugin uses the project token the hub saved for `project` in `hub-env.json`, and only that token. It never uses the admin token. On another machine, get the project token from whoever runs the hub, through a password manager, and enter it at `/plugin configure kxm@kxm`. [Plugin settings](../reference/config-reference.md#claude-code-plugin-settings) has the full rules.
 
@@ -394,7 +394,7 @@ The `kxm_*` tools and the session brief name the fix for setup problems. Run the
 | Message or symptom | Cause | Fix |
 |---|---|---|
 | `KXM hub unreachable at <url>` | No hub answers at `server_url` | Start the hub with `kxm hub start`, or correct `server_url` and restart Claude Code |
-| `KXM has no project token for project <p> on this machine` | No `auth_token`, and the hub saved no token for `<p>` | Add `<p>` with [step 3](#3-start-the-hub), enter its token, or fix the `project` option |
+| `kxm has no project token for project <p>` | No `auth_token`, and the hub saved no token for `<p>`. The message names where `<p>` came from | Set `hub.<mode>.project` in `.kxm/config.yaml` to the key the hub knows, add a key reference, or add `<p>` with [step 3](#3-start-the-hub). Never paste the token into the file |
 | `KXM hub rejected the project token for project <p>` | `auth_token` is not the hub's token for `<p>` | Enter the right token at `/plugin configure kxm@kxm` |
 | `tool_policy_denied: Session token on disk is malformed or expired` | A stale session token file blocks every tool | Run `kxm session token --clear`; it prints `Session token cleared from disk.` |
 | `tool_policy_denied: KXM_SESSION_TOKEN is malformed or expired` | A bad `KXM_SESSION_TOKEN` in Claude Code's environment | Unset or replace it where you launch Claude Code, then restart it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.164",
+  "version": "0.7.166",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.164",
+  "version": "0.7.166",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",
@@ -65,7 +65,7 @@
     "project": {
       "type": "string",
       "title": "Project",
-      "description": "Hub project key; must match a key in the hub KXM_PROJECT_TOKENS. Blank uses the package.json name, then the directory name",
+      "description": "Hub project key; must match a key in the hub KXM_PROJECT_TOKENS. Blank uses the .kxm/project.yaml id, then the package.json name, then the directory name",
       "required": false
     }
   }

package/plugins/kxm/README.md

@@ -58,7 +58,7 @@ Claude Code asks for these options when you install the plugin. Change them late
 | `auth_token` | `KXM_AUTH_TOKEN` | Blank | This project's token from the hub's `KXM_PROJECT_TOKENS`. Leave it blank on the machine that runs the hub. Never the hub admin token. Marked sensitive. |
 | `agent_name` | `KXM_AGENT_NAME` | `claude` | Name other agents see. The first active session in a project keeps it; a later concurrent session registers as `<name>-<pid>`. |
 | `agent_purpose` | `KXM_AGENT_PURPOSE` | `Claude Code implementation and review agent` | One line that peers use to decide what to send this agent. |
-| `project` | `KXM_PROJECT` | Blank | Hub project key; must match a key in the hub's `KXM_PROJECT_TOKENS`. Blank uses `name` from the project's `package.json`, then the directory name. |
+| `project` | `KXM_PROJECT` | Blank | Hub project key. Blank uses the active mode's `project` in `.kxm/config.yaml`, then the `id` in `.kxm/project.yaml`, then `name` from `package.json`, then the directory name. |
 
 The MCP server also receives `KXM_PROJECT_DIR`, set to the directory Claude Code was started in (`CLAUDE_PROJECT_DIR`). It decides the default project key and whether this is a KXM project (one with a `.kxm/` directory).
 
@@ -67,9 +67,9 @@ The MCP server also receives `KXM_PROJECT_DIR`, set to the directory Claude Code
 The plugin acts as an agent of one hub project and authenticates with that project's token. It never uses the hub admin token.
 
 - On the machine that runs the hub, leave `auth_token` blank. The MCP server then uses the project token the hub saved for this project in `hub-env.json` under the user state root (`KXM_STATE_HOME`, or the platform default listed in [State outside the project](../../docs/reference/config-reference.md#state-outside-the-project)). It uses only that entry, never the admin token saved beside it.
-- On any other machine, enter this project's token at `/plugin configure kxm@kxm`. Get it from whoever runs the hub, through your password manager.
+- On any other machine, enter this project's token at `/plugin configure kxm@kxm`. Get it from whoever runs the hub, through your password manager. When the machine is bound with `kxm hub bind --cloud`, leave `auth_token` blank: the MCP server reads the binding's token source and does not store the token. The recipe is [Cross-box peer attach](../../docs/operations.md#cross-box-peer-attach).
 - Never enter the hub admin token. It is the operator's credential. The hub accepts it for any project that has no token of its own, so an agent holding it could act in projects it was never given.
-- Without a project token, every `kxm_*` tool fails with `KXM has no project token for project <p> on this machine`, and the MCP server does not contact the hub.
+- Without a project token, every `kxm_*` tool fails with `kxm has no project token for project <p>`, naming where that id came from, and the MCP server does not contact the hub.
 
 To give a project a token, the operator adds it to `KXM_PROJECT_TOKENS` and restarts the hub. That variable replaces the hub's saved token map rather than merging with it, so it must list every project, existing and new. [Add Claude Code to an existing project](../../docs/start/quickstart-claude-code.md#add-claude-code-to-an-existing-project) has a command that builds the full map. Run it in your own terminal, and never paste tokens or `hub-env.json` into Claude.
 
@@ -210,7 +210,7 @@ No hub answers at `server_url`. Start it with `kxm hub start`, or correct `serve
 
 ### `no project token for project <p>`
 
-The MCP server found neither an `auth_token` nor a token the hub saved for `<p>`, so it did not contact the hub. Enter the project's token at `/plugin configure kxm@kxm`, or add `<p>` to the hub's `KXM_PROJECT_TOKENS`, listing every existing project too because the variable replaces the saved map, and restart the hub. If `<p>` is not the key you expected, set the `project` option.
+The MCP server found neither an `auth_token` nor a token the hub saved for `<p>`, so it did not contact the hub. The message names where `<p>` came from. Enter the project's token at `/plugin configure kxm@kxm`, set `hub.local.project` or `hub.cloud.project` in `.kxm/config.yaml` to the key the hub already knows, or add `<p>` to the hub's `KXM_PROJECT_TOKENS` or `hub.projects` map. `KXM_PROJECT_TOKENS` replaces the saved map, so list every existing project, then restart the hub. Never paste the token into the config file.
 
 ### `KXM hub rejected the project token for project <p>`