diff --git a/controller/cli.mjs b/controller/cli.mjs index 46683e0..4a02d99 100644 --- a/controller/cli.mjs +++ b/controller/cli.mjs @@ -330,6 +330,8 @@ const CAPTURE_NOTE = "Most backends capture a running VM live (libvirt and cloud const SIZE_FLAGS = /** @type {[string, string][]} */ ([["--shape S", "A size from boxery shapes"], ["--cpus N", "CPUs"], ["--mem MiB", "Memory, in MiB"], ["--disk GiB", "Disk, in GiB"]]); const HOST_MGMT = "--host does not apply to host management"; const RUN_RULES = "Arguments are passed exactly as given, like docker exec: quotes, $, ~, globs and ; are not re-parsed in the VM. For pipes, &&, ~ or $VAR, run a shell: bash -c '...'."; +const PROFILE_QUERY_NOTE = "Selected-host commands may refresh this controller's SSH configuration, feature cache and control connections. Read-only does not mean offline or no local cache writes; trusted computed profile configs can also run their own commands."; +const GRANT_LIST_NOTE = "Listing reads this controller's saved grant specifications, not every controller's permissions. With records, no inventory query is needed; with none, the host is asked whether the VM exists. If inventory cannot be read, listing falls back to no locally recorded grants, not proof that the VM has no access. Listing never executes value commands or reads granted files or environment values; stored --cmd text is shown verbatim, so keep secrets out of command literals."; /** Every boxery command and its help (boxery help and COMMAND --help are rendered from this). @type {Record} */ export const COMMANDS = { @@ -350,7 +352,7 @@ export const COMMANDS = { defaultAction: "ls", help: { group: "families", summary: "named hosts, and maintenance of the selected host", list: "host add|ls|show|use|rm|…", usage: [], - details: ["add, ls, show, use and rm manage this machine's registry and take no --host. add NAME DEST runs setup on DEST; importing --config-dir and the other registry actions stay local. Maintenance actions act on the selected host (--host NAME, else the default)."], + details: ["add, ls, show, use and rm manage this machine's registry and take no --host. add NAME DEST runs setup on DEST; importing --config-dir and the other registry actions make no Boxery host requests. Trusted computed profile configs can run their own commands. Maintenance actions use the selected host (--host NAME, else the default), locally or over SSH."], examples: [["Add a second machine and make it the default", "boxery host add hornet you@hornet && boxery host use hornet"], ["One command on another host", "boxery --host hornet ls"], ["Upgrade boxery on a registered host", "boxery --host hornet host upgrade --check"]], seeAlso: ["setup"], docs: "hosts.md", }, @@ -364,7 +366,7 @@ export const COMMANDS = { examples: [["A machine you reach over ssh", "boxery host add hornet you@hornet"], ["A second backend on this machine", "boxery host add exe local --backend exe"]], docs: "hosts.md", }, }, - ls: { scope: "registry", noHost: HOST_MGMT, help: { summary: "list hosts: where each runs and its backend", usage: ["host ls [--json]"], flags: [JSON_FLAG], docs: "hosts.md" } }, + ls: { scope: "registry", noHost: HOST_MGMT, help: { summary: "list hosts: where each runs and its backend", usage: ["host ls [--json]"], details: ["Reads the local registry, profile settings and recorded backend without requesting host inventory. A computed profile is a trusted shell program, not an offline sandbox; the CLI may source it to find its destination."], flags: [JSON_FLAG], docs: "hosts.md" } }, show: { scope: "registry", noHost: HOST_MGMT, help: { summary: "print a host's profile directory", usage: ["host show NAME"], docs: "hosts.md" } }, use: { scope: "registry", noHost: HOST_MGMT, help: { summary: "make NAME the default host", usage: ["host use NAME"], docs: "hosts.md" } }, rm: { scope: "registry", noHost: HOST_MGMT, help: { summary: "forget a host (its VMs and profile data stay)", usage: ["host rm NAME"], docs: "hosts.md" } }, @@ -386,7 +388,7 @@ export const COMMANDS = { ls: { help: { group: "vms", summary: "list VMs: every host's, a section each (--host NAME: one)", usage: ["ls [--json] [--refresh] [--running]"], - details: ["One header for every host's rows. STATUS says what is worth knowing about a VM: its pool lease, outdated guest software (see boxery patch) and grants. Notes come after the table, on stderr; a host that can't be reached fails ls once the others are listed. --json lists one host."], + details: ["One header for every host's rows. STATUS says what is worth knowing about a VM: its pool lease, outdated guest software (see boxery patch) and grants. Notes come after the table, on stderr; a host that can't be reached fails ls once the others are listed. --json lists one host.", "Always asks the selected hosts for inventory. Guest software records are cached on each host; --refresh queries running guests and updates those records, without patching guest software.", PROFILE_QUERY_NOTE], flags: [JSON_FLAG, ["--refresh", "Read the guest software record from each running VM first"], ["--running", "Only running VMs"]], examples: [["Every host's VMs", "boxery ls"], ["One host's running VMs", "boxery --host hornet ls --running"]], seeAlso: ["patch", "host"], docs: "cli.md#lifecycle", @@ -653,7 +655,7 @@ export const COMMANDS = { run: async (s, args) => { needHost(s); await (await grants()).revoke(s, args); }, }, grants: { - help: { group: "legacy", summary: "show a VM's grants, or push them again (apply)", list: "grants NAME [apply]", usage: ["grants NAME [apply [--quiet] | --json]"], flags: [JSON_FLAG], docs: "grants.md" }, + help: { group: "legacy", summary: "show a VM's grants, or push them again (apply)", list: "grants NAME [apply]", usage: ["grants NAME [apply [--quiet] | --json]"], details: [GRANT_LIST_NOTE, "apply pushes existing grants again; listing never grants, revokes or applies.", PROFILE_QUERY_NOTE], flags: [JSON_FLAG], docs: "grants.md" }, run: async (s, args) => (await grants()).grantsCommand(s, args), }, "agent-forward": { @@ -676,7 +678,7 @@ export const COMMANDS = { ls: { command: "grants", args: (a) => { if (a.length > 2 || (a.length === 2 && a[1] !== "--json")) usage("access", { sub: "ls" }); return a; }, - help: { summary: "show a VM's grant kinds and settings (read-only)", usage: ["access ls NAME [--json]"], details: ["Shows saved specifications, including --cmd text, without executing value commands or reading granted files or environment values. With none recorded, checks the host's inventory to catch a missing VM. A secret embedded in a command literal is therefore visible; use commands that read a secret store instead."], examples: [["What demo has been granted", "boxery access ls demo"]] }, + help: { summary: "show a VM's grant kinds and settings (read-only)", usage: ["access ls NAME [--json]"], details: [GRANT_LIST_NOTE, PROFILE_QUERY_NOTE], examples: [["What demo has been granted", "boxery access ls demo"]] }, }, apply: { command: "grants", @@ -745,7 +747,7 @@ export const COMMANDS = { // ------------------------------------------------ host & diagnostics version: { - help: { group: "more", summary: "controller and host versions; warns when the host is behind", usage: ["version [--json]"], details: ["boxery --version and boxery -V are the same as boxery version."], flags: [JSON_FLAG], seeAlso: ["host upgrade"] }, + help: { group: "more", summary: "controller and host versions; warns when the host is behind", usage: ["version [--json]"], details: ["boxery --version and boxery -V are the same as boxery version.", "Without a configured host, reports only the controller. Otherwise queries the selected host; an unreachable host is reported as unknown without failing the controller version report."], flags: [JSON_FLAG], seeAlso: ["host upgrade"] }, run: async (s, args) => cmdVersion(s, args), local: (args) => cmdVersion(null, args), contract: { hostOptional: true }, @@ -761,15 +763,15 @@ export const COMMANDS = { run: cmdUpgradeHost, }, backends: { - help: { group: "legacy", summary: "backend support, requirements and capabilities", usage: ["backends [--json]"], flags: [JSON_FLAG], docs: "backends.md" }, + help: { group: "legacy", summary: "backend support, requirements and capabilities", usage: ["backends [--json]"], details: ["Reads declarations from boxery-host on the selected host (over SSH for a remote host), not from the controller's platform. No provider requests or backend startup.", PROFILE_QUERY_NOTE], flags: [JSON_FLAG], docs: "backends.md" }, run: async (s, args) => hostPass(s, ["backends", ...args]), }, capabilities: { - help: { group: "legacy", summary: "the selected host's platform and capabilities", usage: ["capabilities [--json | --check]"], flags: [JSON_FLAG, ["--check", "Run the backend preflight; fails when a requirement is missing"]], docs: "backends.md" }, + help: { group: "legacy", summary: "the selected host's platform and capabilities", usage: ["capabilities [--json | --check]"], details: ["Queries and checks requirements on the selected host, locally or over SSH. Does not start a backend or contact its provider; --check fails when a locally checkable requirement is missing.", PROFILE_QUERY_NOTE], flags: [JSON_FLAG, ["--check", "Run the backend preflight; fails when a requirement is missing"]], docs: "backends.md" }, run: async (s, args) => hostPass(s, ["capabilities", ...args]), }, backend: { - help: { group: "legacy", summary: "the host's VM backend (recorded for host ls)", usage: ["backend"] }, + help: { group: "legacy", summary: "the host's VM backend (recorded for host ls)", usage: ["backend"], details: ["Asks the selected host for its current backend and updates the controller's recorded backend used by host ls.", PROFILE_QUERY_NOTE] }, run: async (s, args) => { needHost(s); await backendCommand(s.host, args); }, }, "proxy-log": { diff --git a/docs/backends.md b/docs/backends.md index edb4917..298efa3 100644 --- a/docs/backends.md +++ b/docs/backends.md @@ -3,7 +3,7 @@ Query the declarations with `boxery host backends --json` (or `boxery-host backends --json`; `boxery backends` is the older spelling). Query the **selected host's** configuration and local requirements with `boxery host capabilities --json`. Agents use `vm_info {action:"capabilities"}` in both -MCP and pi. These queries do not start a backend, contact a provider or change files. +MCP and pi. These discovery handlers run on the selected **host**, over SSH when it is remote; they do not start a backend, contact its provider or change backend configuration. The controller may still refresh its SSH configuration, feature-cache files or control connections. Read-only discovery is not an offline guarantee. Use `boxery host capabilities --check` for setup preflight (nonzero on unsupported configurations or missing locally checkable setup requirements). diff --git a/docs/cli.md b/docs/cli.md index a3eed09..978d90d 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -13,6 +13,7 @@ Exit status: `0` on success; a command that runs something in the VM (`run`, `ssh`, `attach`, `wait` and the like) exits with its status, so a script can't tell boxery's codes from the command's. boxery's own failures exit `1`, and its usage errors (an unknown command or flag, a missing argument or flag value, arguments that don't fit the command's usage) exit `2`. A value that is refused (an invalid name, a VM that doesn't exist) is a failure, `1`, and so is a usage error that the host reports for a command boxery passes to it (`images`, `pool`, `runners`, …). - [Command families](#command-families) +- [Read-only queries and offline behavior](#read-only-is-not-necessarily-offline) - [All commands](#all-commands), generated from the same help ### Command families @@ -37,6 +38,23 @@ The everyday commands stay top level: `new`, `ls`, `start`, `stop`, `rm`, `resiz - **Mistakes.** An unknown action names the family's actions (`unknown snapshot action: restroe (did you mean restore?); actions: …`) and exits 2, before any host, profile or grant is read. - **Payload words are not options.** `boxery run` and `boxery ssh` hand every word after the VM name to the VM, `--help` included. Family actions recognise help only immediately after the action (`job logs --help`), so `agent prompt demo --help` sends `--help` as task text. Older top-level spellings retain their help conventions, including `snap demo --help` and `prompt demo --help`. +### Read-only is not necessarily offline + +A read-only query does not request changes to VM software or permissions. It can still contact a host and refresh metadata or connection caches: + +| Query | Source and contact | +|---|---| +| `host ls`, `host show` | Local registry/profile metadata; `host ls` uses the recorded backend, not a live host query. | +| `access ls NAME`, `grants NAME` | This controller's grant records. With none, asks the selected host whether the VM exists. If inventory is unavailable, falls back to no locally recorded grants. | +| `ls` | Live inventory from the host(s), but cached guest-software records. `--refresh` queries running guests and updates those records; it does not patch software. An unreachable host causes exit 1 after other hosts are listed. | +| `host backends`, `host capabilities` | Declarations and local requirement checks on the selected host, reached over SSH when remote. No backend startup or provider requests. | +| `host backend` | Live host backend, then a refresh of this controller's recorded backend. | +| `version` | Controller only before setup; otherwise also queries the selected host. An unreachable host is reported as unknown without failing the controller version report. | + +In particular, an empty grant list is **not an audit of every controller's access**. Listing never executes grant value commands, reads granted files/environment values, or reapplies permissions; stored `--cmd` text is still visible ([Grants](grants.md)). + +Ordinary selected-host dispatch can refresh `ssh_config`, feature-cache files and SSH control connections even for a query. Registry scope is not an offline promise either: `host add NAME DEST` runs setup at its explicit destination, unlike an import with `--config-dir`. Plain setup-generated profiles contain assignments; a computed profile is a trusted shell program whose own network and filesystem effects are not constrained by the query's read-only intent. + ### Named hosts ```bash @@ -59,7 +77,7 @@ Without `--host`, `ls` lists every registered host's VMs under one header, a sec ### Backend discovery `boxery host backends [--json]` lists backend platform support, requirements and capabilities. -`boxery host capabilities [--json | --check]` assesses the selected **host**, not the controller. +`boxery host capabilities [--json | --check]` assesses the selected **host**, not the controller. Both commands run boxery-host on that host (over SSH when remote), even though their discovery handlers neither start a backend nor contact a provider. Both are also available as the top-level `backends` and `capabilities`, and directly as `boxery-host` commands. Agents use `vm_info {action:"capabilities"}`. See the [metadata contract](backends.md) for supported versus tested configurations and conditional features. Setup checks @@ -723,7 +741,7 @@ The controller (`boxery acquire`, `vm_lease`) asks for it when the host's `help` | `~/.boxery/host-registry/HOST`, `~/.boxery/default-host` | Registered hosts and the default one ([Named hosts](hosts.md)) | | `~/.boxery/profiles/HOST/config` | Controller: host, host binary path, identity | | `~/.boxery/profiles/HOST/ssh_config` | Generated. `*.boxery` hosts via `ProxyCommand`. | -| `~/.boxery/profiles/HOST/grants/NAME` | Grant names and paths (never values) | +| `~/.boxery/profiles/HOST/grants/NAME` | Grant specifications, paths and command text (not resolved values) | | `~/.boxery/profiles/HOST/leases/` | Your leases and their per-lease ssh keys | | `~/.config/boxery/host.env` (host) | Backend and overrides (`BOXERY_BACKEND`, `BOXERY_LIMA_VMTYPE`, …) | | `~/.config/boxery/proxy.env` (host) | Extra LLM provider keys (VMs still need an `llm:` grant to use them) | diff --git a/docs/grants.md b/docs/grants.md index 48ac8d8..e856d8d 100644 --- a/docs/grants.md +++ b/docs/grants.md @@ -19,7 +19,13 @@ boxery access ls demo # saved kinds boxery access revoke demo env:GH_TOKEN # or: access revoke demo all ``` -`access ls` reads saved specifications without running value commands, reading granted files or environment values, or reapplying access. With none recorded, it asks the host whether the VM exists, so a typo reports `no such vm` rather than `no grants`. Stored `--cmd` text is shown verbatim, so a secret embedded in a command literal would be visible. Use commands that read a secret store instead. +## Listing: read-only, not necessarily offline + +`access ls` (also `grants NAME`) reads **this controller's** saved specifications. With records, it needs no host inventory query; with none, it asks the selected host whether the VM exists, so a typo reports `no such vm` rather than `no grants`. If inventory cannot be read, including when the host is unreachable, it falls back to no locally recorded grants. An empty list is not proof that other controllers have granted no access. + +Listing never executes grant value commands, reads granted files or environment values, or reapplies access. Stored `--cmd` text is shown verbatim, so a secret embedded in a command literal would be visible. Use commands that read a secret store instead. As with other selected-host commands, ordinary dispatch may refresh SSH configuration, feature caches or control connections; read-only refers to permissions, not an offline or filesystem-free execution guarantee. + +## Grant at creation or from pi You can also grant at creation time, or from pi: diff --git a/docs/hosts.md b/docs/hosts.md index 34d8ad3..c5802ca 100644 --- a/docs/hosts.md +++ b/docs/hosts.md @@ -63,7 +63,7 @@ On the host, `boxery-host profiles` lists every profile (backend, port, service, ## Where each host runs -`boxery host ls` (and `--json`, and MCP `vm_info {action:"hosts"}`) says where each registered host runs, read from local profile files without contacting any host: +`boxery host ls` (and `--json`, and MCP `vm_info {action:"hosts"}`) describes registered hosts from local profile files rather than requesting live host inventory. A computed CLI profile is trusted shell code and can run its own commands, so local metadata scope is not a network sandbox: ```text NAME DEFAULT CONFIG_DIR DESTINATION BACKEND SAME_AS @@ -73,9 +73,11 @@ local * /home/you/.boxery/profiles/local local lima - ``` * **DESTINATION** is the profile's `HOST`: `local` means the VM host is the machine running the controller (or the MCP server); otherwise it is the ssh destination or ssh-config alias. The CLI sources the trusted profile config to find it; MCP never executes it and parses only plain assignments (as `setup` writes them), so a computed value shows as unknown (`-` / `null`). -* **BACKEND** lives on the VM host (`host.env`), so it is not read live. `setup` and `host add` record it in the profile's `backend` file (one line of data); `boxery [--host NAME] backend` asks the host and refreshes the record. Profiles set up earlier, or hosts that predate `boxery-host backend`, show `-` / `null` until then. +* **BACKEND** lives on the VM host (`host.env`), so it is not read live. `setup` and `host add` record it in the profile's `backend` file (one line of data); `boxery [--host NAME] host backend` asks the host and refreshes the record. Profiles set up earlier, or hosts that predate `boxery-host backend`, show `-` / `null` until then. * **SAME_AS** lists the other names for the same host: registered for the same profile directory (for example after `host add laptop --config-dir ~/.boxery/profiles/local`), or for the same destination and host-side profile (`host add lab2 local --profile exe` next to an `exe` host already registered for that profile, which gets a directory of its own). `local` and `laptop` are one host with the same VMs, not two, and `ls` lists them once. The host-side profile is read from `HOST_PROFILE`, or, for a registration from before host profiles whose `HOST_BIN` is a wrapper script on this machine, from the wrapper's `BOXERY_CONF=$HOME/.config/boxery-P` or `--profile P` when those are literal and agree (anything else, or a wrapper on another machine, matches only by directory). Grants and lease keys stay with each name's profile directory: `--host lab2 grant …` is lab2's, and `ls` shows it in that host's section as `grants (lab2) …`, next to the listed name's own. +Selected-host queries are different from registry inspection: `boxery ls` asks the hosts for VM inventory; `host capabilities` and `host backends` run discovery on the selected host (over SSH when remote). Even read-only queries can refresh local SSH configuration, feature caches and control connections. `host add NAME DEST` also contacts its explicit destination for setup; it does not use the selected host. See [query sources](cli.md#read-only-is-not-necessarily-offline). + ## Importing two existing profiles Import does **not** run setup, contact either host, copy credentials, regenerate SSH configuration or move grants: