Skip to content
Merged
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
2 changes: 1 addition & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ VM (Ubuntu 24.04; XFCE desktop unless --headless)
| `guests/linux.mjs`, `guests/index.mjs` | agent machine and host | What's inside a VM, per guest OS: the agent's home and project, boxery's config and grants directories. `core/` and `host/` both import it instead of keeping their own copies; it imports nothing. Only `linux` exists ([plan](docs/plans/2026-11-03-guest-os-seam.md)) |
| `mcp/boxery-mcp.mjs` | agent machine (stdio) or host (HTTP) | MCP server. stdio, or Streamable HTTP at `/mcp` (bearer token required, optional Tailscale user allowlist, Origin check; meant for `tailscale serve`, never funnel). Sessions keep their own host and VM. `vm_view` + `mcp/desktop-view.html` give MCP Apps clients a live desktop |
| `extension/index.ts` | agent machine | pi extension: explicit `vm_*` tools next to pi's built-ins (which stay local), `--vm NAME/new/pool`, `--vm-host`, `/vm` commands, throwaway VMs and leases tied to the pi session |
| `controller/boxery` + `controller/*.mjs` | agent machine | The CLI. `controller/boxery` is a small Bash shim (it finds Node and passes arguments on byte for byte, like `host/boxery-host`); `controller/cli.mjs` parses commands and runs the same core code MCP and pi do. Its `COMMANDS` table is the one definition of routing and help (and of which long commands report their progress to the terminal, as OSC 7501 on stderr when it is a terminal: a `status` on the entry, run by `controller/status.mjs`): a command has a `run` handler, and a command family (`host`, `snapshot`, `agent`, `job`, `access`, `lease`; `pool` and `runners` parse their own actions) has `actions`, each naming an existing command whose handler it runs, so `boxery job ls` and `boxery jobs` are one code path and the older spellings need no second table. Commands carry an optional `contract` beside their handlers: selected-host or controller scope, help/payload boundaries, optional host selection, all-host listings, SSH-qualified targets and terminal needs. Ordinary commands use selected-host/legacy-help defaults; aliases and family actions inherit their handler's contract. Approval is conditional when granting (`new`, `fork`, `grant`, `agent-forward`); only `attach` unconditionally needs a terminal on stdin, after argument validation. Family actions are resolved before any host or profile is read; `host` registry actions (`add`, `ls`, `show`, `use`, `rm`) explicitly declare `scope: "registry"` and run before host selection. Registry scope is not an offline guarantee: `host add DEST` contacts DEST. Host maintenance uses the ordinary selected-host path. The code behind the commands: `core/lifecycle.mjs` (new/fork/rm/start/stop/resize/snap/revert/pin/pool/patch, listings), `core/leases.mjs`, `core/grants.mjs`, `vm_copy` (`cp`), `core/versions.mjs`. What only the CLI has: argument parsing and output formats (unchanged, [cli.md](docs/cli.md)), `/dev/tty` grant approval (`controller/grants.mjs`), terminal commands (`ssh`, `attach`, `desktop`, `forward`, `run`, jobs in `controller/jobs.mjs`, `runners once` with your `gh` login), and the host registry's CLI (`controller/hosts.mjs`: `setup`, `host add/ls/show/use/rm`, over `core/registry.mjs`, which `vm_manage host_add/host_rm` use too). Profiles: `core/profile.mjs` (config, `hostRun` to boxery-host, ssh_config, shared connections) and `core/ssh-config.mjs` (quoting and the ssh_config text). A profile `config` that only assigns the controller's settings (`HOST`, `HOST_BIN`, `HOST_PROFILE`, `IDENTITY`, `GRANT_CONFIRM`, as `setup` writes them) is parsed; any other config is sourced by bash (`set -eu`, with `$CONF_DIR` and the defaults set), and its exported environment reaches host commands. `test/ssh-config.test.mjs` holds the ssh_config text and quoting to the Bash controller's (`test/fixtures/bash-profile.sh`), word for word. Each profile's `ssh_config`: `*.boxery` → `ProxyCommand ssh HOST boxery-host connect %h %p`, ControlMaster, per-lease identities, per-VM `ForwardAgent` |
| `controller/boxery` + `controller/*.mjs` | agent machine | The CLI. `controller/boxery` is a small Bash shim (it finds Node and passes arguments on byte for byte, like `host/boxery-host`); `controller/cli.mjs` parses commands and runs the same core code MCP and pi do. Its `COMMANDS` table is the one definition of routing and help (and of which long commands report their progress to the terminal, as OSC 7501 on stderr when it is a terminal: a `status` on the entry, run by `controller/status.mjs`): a command has a `run` handler, and a command family (`host`, `snapshot`, `agent`, `job`, `access`, `lease`; `pool` and `runners` parse their own actions) has `actions`, each naming an existing command whose handler it runs, so `boxery job ls` and `boxery jobs` are one code path and the older spellings need no second table. Commands carry an optional `contract` beside their handlers: selected-host or controller scope, help/payload boundaries, optional host selection, all-host listings, SSH-qualified targets and terminal needs. Ordinary commands use selected-host/legacy-help defaults; aliases and family actions inherit their handler's contract. Approval is conditional when granting (`new`, `fork`, `grant`, `agent-forward`); only `attach` unconditionally needs a terminal on stdin, after argument validation. Family actions are resolved before any host or profile is read; `host` registry actions (`add`, `ls`, `show`, `use`, `rm`) explicitly declare `scope: "registry"` and run before host selection. Registry scope is not an offline guarantee: `host add DEST` contacts DEST. Host maintenance uses the ordinary selected-host path. Read-only host-wide text listings use `controller/all-hosts.mjs`, sharing host ordering, same-host deduplication and headings with `controller/ls.mjs`; JSON and explicit `--host` remain single-host, and mutating actions stay selected-host. The code behind the commands: `core/lifecycle.mjs` (new/fork/rm/start/stop/resize/snap/revert/pin/pool/patch, listings), `core/leases.mjs`, `core/grants.mjs`, `vm_copy` (`cp`), `core/versions.mjs`. What only the CLI has: argument parsing and output formats (unchanged, [cli.md](docs/cli.md)), `/dev/tty` grant approval (`controller/grants.mjs`), terminal commands (`ssh`, `attach`, `desktop`, `forward`, `run`, jobs in `controller/jobs.mjs`, `runners once` with your `gh` login), and the host registry's CLI (`controller/hosts.mjs`: `setup`, `host add/ls/show/use/rm`, over `core/registry.mjs`, which `vm_manage host_add/host_rm` use too). Profiles: `core/profile.mjs` (config, `hostRun` to boxery-host, ssh_config, shared connections) and `core/ssh-config.mjs` (quoting and the ssh_config text). A profile `config` that only assigns the controller's settings (`HOST`, `HOST_BIN`, `HOST_PROFILE`, `IDENTITY`, `GRANT_CONFIRM`, as `setup` writes them) is parsed; any other config is sourced by bash (`set -eu`, with `$CONF_DIR` and the defaults set), and its exported environment reaches host commands. `test/ssh-config.test.mjs` holds the ssh_config text and quoting to the Bash controller's (`test/fixtures/bash-profile.sh`), word for word. Each profile's `ssh_config`: `*.boxery` → `ProxyCommand ssh HOST boxery-host connect %h %p`, ControlMaster, per-lease identities, per-VM `ForwardAgent` |
| `host/boxery-host` + `host/*.mjs` | control plane | Backend-agnostic VM manager. Bash entry point; `connect` stays in Bash so the ProxyCommand never pays Node startup; everything else is Node. Ownership per module: [host-modules.md](docs/host-modules.md) |
| `host/backends/*.sh` | control plane | Hypervisor effects only, one allowlisted function per process, arguments as argv ([contract](host/backends/README.md)). libvirt, Lima and exe.dev are stable; Cloud Hypervisor, boat.dev and OpenShell are experimental |
| `proxy/boxery-proxy.mjs` | control plane | Credential proxy: checks the per-VM token, applies per-route method/path allowlists, body/concurrency/time limits, injects the real credential, refuses WebSocket upgrades (clients use SSE) |
Expand Down
87 changes: 87 additions & 0 deletions controller/all-hosts.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
// Text-only, read-only listings. The CLI keeps explicit --host and JSON on their original paths.
import { withHost } from "../core/boxery-core.mjs";
import { hostRun } from "../core/profile.mjs";
import { leaseText } from "./leases.mjs";
import { controllerVersion, skewNote } from "../core/versions.mjs";
import { hostHeading, listedHosts } from "./ls.mjs";
import { needHost, note, quit, say, select, usage } from "./lib.mjs";
/** @import { Selected } from "./lib.mjs" */

/** Whether this invocation is a read-only host-wide listing (not a VM or a mutation).
* @param {string} command @param {string[]} args */
export function isListing(command, args) {
if (args.includes("--json")) return false;
if (command === "pool") return args[0] === "ls";
if (command === "runners") return !args.length || args[0] === "status";
if (command === "upgrade-host") {
// A flag-looking ref/value is not an action selector. Never fan out a real upgrade.
for (let i = 0; i < args.length; i++) {
if (args[i] === "--ref" || args[i] === "--wait") i++;
else if (args[i] === "--check") return true;
}
return false;
}
return ["leases", "images", "version", "shapes", "capabilities", "backends"].includes(command);
}

/** Print a multi-host listing, returning false to retain the original single-host path.
* @param {Selected} s @param {string} command @param {string[]} args */
export async function allHostsListing(s, command, args) {
if (["leases", "version", "shapes"].includes(command) && args.length) usage(command);
const hosts = listedHosts(s);
if (hosts.length <= 1) return false;
const controller = controllerVersion();
if (command === "version") say(`controller ${controller.version}${controller.describe ? ` (${controller.describe})` : ""}`);
const sections = await Promise.all(hosts.map(async (h) => {
let text = "", notes = "", error = null;
try {
const hs = h.name === s.host.name ? s : await select(h.name, h.dir);
needHost(hs);
await withHost(hs.host, async () => {
if (command === "leases") {
text = leaseText();
return;
}
const hostCommand = command === "upgrade-host" ? "upgrade" : command;
text = await hostRun([hostCommand, ...(command === "version" ? ["--json"] : args)], {
host: hs.host, config: hs.config,
onData: (d, from) => { if (from === "stderr") notes += d.toString("utf8"); },
});
if (command === "upgrade-host") {
// Only --check reaches this listing path; its report is written to stderr.
text = notes.trim();
notes = "";
}
if (command === "version") {
const h = JSON.parse(text);
if (typeof h.version !== "string") throw new Error("invalid host version response");
text = `host ${h.version}${h.describe ? ` (${h.describe})` : ""} ${h.install ?? "unknown"} install [${hs.host.name}]`;
const skew = skewNote(controller, h, hs.host.name);
if (skew) notes += `boxery: ${skew}\n`;
}
});
} catch (e) { error = /** @type {Error} */ (e); }
return { name: h.name, heading: hostHeading(h, s), text, notes, error };
}));
if (command === "images") {
// Keep the host's table columns and add provenance, with just one header.
const width = Math.max(4, ...sections.map((sec) => sec.name.length));
const row = (/** @type {string} */ host, /** @type {string} */ text) => `${host.padEnd(width)} ${text}`;
const header = sections.filter((sec) => !sec.error).map((sec) => sec.text.split("\n")[0]).find((line) => /^IMAGE(?:\s|$)/.test(line));
say(row("HOST", header ?? "IMAGE"));
for (const sec of sections) {
if (sec.error) { say(row(sec.name, "(images failed: see below)")); continue; }
const lines = sec.text.split("\n");
if (/^IMAGE(?:\s|$)/.test(lines[0] ?? "")) lines.shift();
for (const line of lines.filter(Boolean)) say(row(sec.name, line));
}
} else {
say(sections.map((sec) => `${sec.heading}\n${sec.error ? `(${command} failed: see below)` : sec.text}`).join("\n\n"));
}
for (const sec of sections) {
if (sec.error) note(`boxery: ${sec.name}: ${sec.error.message.replace(/^boxery: /, "") || `${command} failed`}`);
else if (sec.notes.trim()) note(sec.notes.trim().split("\n").map((l) => l.replace(/^(==> )?/, `$1${sec.name}: `)).join("\n"));
}
if (sections.some((sec) => sec.error)) quit(1);
return true;
}
Loading
Loading