Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions controller/cli.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, Entry>} */
export const COMMANDS = {
Expand All @@ -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",
},
Expand All @@ -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" } },
Expand All @@ -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",
Expand Down Expand Up @@ -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": {
Expand All @@ -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",
Expand Down Expand Up @@ -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 },
Expand All @@ -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": {
Expand Down
2 changes: 1 addition & 1 deletion docs/backends.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
22 changes: 20 additions & 2 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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) |
Expand Down
8 changes: 7 additions & 1 deletion docs/grants.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
Loading
Loading