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
5 changes: 3 additions & 2 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ VM (Ubuntu 24.04; XFCE desktop unless --headless)
| `backends/index.mjs` | agent machine and host | What each backend declares: supported and tested boxery-host platforms, runtimes, prerequisites and capabilities, as data (no probes). `host/capabilities.mjs` checks against it, `boxery-host backends`/`capabilities` print it, and `vm_info` lists it; it imports nothing. A backend without a declaration (one added as a `.sh` file) runs unchecked ([backends](docs/backends.md)) |
| `help/index.mjs` | agent machine and host | Renders CLI help from a command table (`PROG help [--all]`, `COMMAND --help`, a family's and an action's help derived from the command each action runs, usage errors, the docs reference) for `controller/cli.mjs` and `host/help.mjs`; it imports nothing |
| `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 |
| `mcp/boxery-mcp.mjs` | agent machine (stdio) or host (HTTP) | MCP server. stdio, or Streamable HTTP at `/mcp` (bearer token required: unscoped, or [scoped](docs/mcp.md#scoped-tokens) to tools, hosts and VMs by `core/mcp-tokens.mjs` and checked where boxery acts by `core/mcp-auth.mjs`; 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. 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) |
Expand Down Expand Up @@ -201,7 +201,7 @@ Nothing in boxery's own state limits that: lock transactions are short, the prox

## Roadmap

1. **Hardening** of what exists: Lima on Linux and Lima guests' reach to the Mac's non-loopback addresses ([#67](https://github.com/modem-dev/boxery/issues/67)), confining HTTP-MCP `local:` copies ([#68](https://github.com/modem-dev/boxery/issues/68)), proxy header and token hardening ([#73](https://github.com/modem-dev/boxery/issues/73)), HTTP MCP bounds and argument validation ([#21](https://github.com/modem-dev/boxery/issues/21), [#72](https://github.com/modem-dev/boxery/issues/72)), scoped MCP tokens ([#3](https://github.com/modem-dev/boxery/issues/3)), default-deny egress ([#4](https://github.com/modem-dev/boxery/issues/4)), per-VM proxy budgets.
1. **Hardening** of what exists: Lima on Linux and Lima guests' reach to the Mac's non-loopback addresses ([#67](https://github.com/modem-dev/boxery/issues/67)), confining HTTP-MCP `local:` copies ([#68](https://github.com/modem-dev/boxery/issues/68)), proxy header and token hardening ([#73](https://github.com/modem-dev/boxery/issues/73)), HTTP MCP bounds and argument validation ([#21](https://github.com/modem-dev/boxery/issues/21), [#72](https://github.com/modem-dev/boxery/issues/72)), default-deny egress ([#4](https://github.com/modem-dev/boxery/issues/4)), per-VM proxy budgets.
2. **Lease enforcement:** the restricted host gateway and authenticated holders ([#71](https://github.com/modem-dev/boxery/issues/71)). First decide the pool's shape ([#75](https://github.com/modem-dev/boxery/issues/75)).
3. **Profiles** (app-agnostic setup on top of images), `--keep`, detach/resume semantics for pi, versioned templates, builder VMs for build-time tokens: [plan](docs/plans/2026-11-01-profiles-and-lease-extensions.md).
4. **Simplification:** align the Node requirement ([#77](https://github.com/modem-dev/boxery/issues/77)). (The controller moved into Node: [#74](https://github.com/modem-dev/boxery/issues/74).)
Expand All @@ -217,6 +217,7 @@ Nothing in boxery's own state limits that: lock transactions are short, the prox
- **Grant operations in Node, approval in front-ends.** As with `cp`, CLI and tools call one implementation so store edits, validation and application cannot drift. Existing lifecycle/connect paths delegate only reconciliation and do not ask again. The CLI uses its already-selected profile directory rather than re-resolving a changed registry entry. Existing-grant reconciliation tolerates incomplete registry entries but still includes their directory pointers in symlink deny checks; new file-grant validation remains strict. Leases (`core/leases.mjs`), profile/ssh_config plumbing (`core/profile.mjs`, `core/ssh-config.mjs`) and lifecycle (`core/lifecycle.mjs`) are Node; the registry (`core/registry.mjs`) and the desktop tunnel (`core/desktop.mjs`) too; core never runs the CLI ([#74](https://github.com/modem-dev/boxery/issues/74)). `vm_manage new` does not pass grants.
- **Node for logic, Bash at the edges.** Where boxery decides something (leases, locks, recovery, grants, profiles, the CLI's commands), it is Node: modules with injected dependencies, tested directly, one implementation for the CLI, MCP and pi ([#18](https://github.com/modem-dev/boxery/issues/18), [#74](https://github.com/modem-dev/boxery/issues/74)). Bash is left where it is the better tool or the only one: entry shims (`controller/boxery`, `host/boxery-host`; `connect`, the ssh ProxyCommand of every VM connection, never starts Node), backends that wrap a hypervisor's command line (`host/backends/*.sh`: libvirt, Lima, cloud-hypervisor; exe.dev's CLI over ssh), and what runs in the guest (`image/layers/*.sh`, the job runner, the grant applier: Node may not be there yet, and they are sent each time). Data both sides need is data, not a copy in each language: the host.env settings are one list (`host/host-env.list`) that `host/backend.sh` and `host/config.mjs` read. A backend whose work is an HTTP API is a Node module behind a Bash contract file (`openshell.sh` → `lib/openshell.mjs`; `boat.sh` → `lib/boat.mjs` for boat.dev's REST API, with ssh and tunnels in Bash).
- **Unsigned fake JWT as the Codex token.** The Codex client derives an account id from a JWT, so a VM gets an `alg: none` JWT whose payload carries `name:secret`. The proxy never treats it as a signed credential.
- **Scoped MCP tokens on the controller, checked where boxery acts.** `boxery-mcp --http` runs on the controller and can drive several hosts, so its tokens live there (`~/.boxery/mcp-tokens.json`, hashed), not on a host, which can't import the core. A tool's arguments name VMs many ways (`vm`, `VM@SNAP`, `HOST/VM:path`, fork targets, generated names), so the scope is checked again where a name finally reaches ssh or a host command (`core/mcp-auth.mjs`), with the grant carried in async context; the HTTP server refuses any operation that lost it. A VM a token created is its own only while its ssh host key matches, so a reused name isn't ([#3](https://github.com/modem-dev/boxery/issues/3)).

## Review log

Expand Down
15 changes: 15 additions & 0 deletions controller/cli.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -391,6 +391,21 @@ export const COMMANDS = {
capabilities: { command: "capabilities" },
},
},
"mcp-token": {
contract: { scope: "controller", noHost: "mcp-token takes --host NAME after new LABEL, to scope a token to that host" },
local: async (args) => (await import("./mcp-tokens.mjs")).mcpTokenCommand(args),
help: {
group: "more", summary: "scoped tokens for the HTTP MCP server (boxery-mcp --http)", list: "mcp-token new|ls|rm",
usage: ["mcp-token new LABEL [--vm PATTERN]... [--host NAME]... [--tools TOOL[:ACTION],... | --read-only] [--admin] [--ttl 30d|12h|never]", "mcp-token ls [--json]", "mcp-token rm LABEL"],
details: [
"A token reaches only its tools, its hosts (default: the server's --host) and its VMs: those matching --vm (* matches any characters) and those created with it. Admin work (build-base, adding hosts, pool leases) needs --admin.",
"new prints the token once; the server stores only its hash, in ~/.boxery/mcp-tokens.json. rm and expiry take effect at the next request, without a restart.",
],
flags: [["--vm PATTERN", "VMs the token may use besides the ones it creates (repeatable; * matches any characters)"], ["--host NAME", "A registered host it may use (repeatable; default: the server's --host)"], ["--tools LIST", "Only these tools, or TOOL:ACTION (e.g. vm_bash,vm_manage:new)"], ["--read-only", "Only vm_read, vm_screenshot and vm_info"], ["--admin", "Also build-base, host_add, host_rm and pool leases"], ["--ttl T", "Lifetime: 90m, 12h, 30d (default) or never"], JSON_FLAG],
examples: [["An agent that may create and use its own VMs, for a week", "boxery mcp-token new ci-agent --ttl 7d"], ["Look at the demo VMs, change nothing", "boxery mcp-token new viewer --vm 'demo-*' --read-only"]],
seeAlso: ["setup"], docs: "mcp.md#scoped-tokens",
},
},
"build-base": {
help: { group: "legacy", summary: "build the host's desktop base image (one time, ~3 min)", usage: ["build-base"], details: ["Headless VMs (new --headless) don't need it."], docs: "cli.md#lifecycle" },
status: {},
Expand Down
64 changes: 64 additions & 0 deletions controller/mcp-tokens.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
// boxery mcp-token new|ls|rm: scoped tokens for the HTTP MCP server (core/mcp-tokens.mjs, docs/mcp.md).
// Only a person mints them: no agent tool does (test/parity.test.mjs says why).
import { resolveHost } from "../core/boxery-core.mjs";
import { toolCatalog } from "../core/boxery-tools.mjs";
import { createToken, describeScope, hostNames, parseTtl, readStore, removeToken, toolsScope, vmPatterns } from "../core/mcp-tokens.mjs";
import { die, say, usage } from "./lib.mjs";

/** @param {number | null} t */
const when = (t) => (t == null ? "never" : new Date(t * 1000).toISOString().replace(/\.\d+Z$/, "Z"));

/** @param {string[]} args */
export async function mcpTokenCommand(args) {
const [action, ...rest] = args;
switch (action) {
case "new": {
const label = rest.shift();
if (!label || label.startsWith("-")) usage("mcp-token");
/** @type {string[]} */
const vms = [], hosts = [];
let tools = /** @type {string | null} */ (null), readOnly = false, admin = false, ttl = "30d";
while (rest.length) {
const a = /** @type {string} */ (rest.shift());
const value = () => rest.shift() ?? die(`${a} needs a value`);
if (a === "--vm") vms.push(value());
else if (a === "--host") hosts.push(value());
else if (a === "--tools") tools = value();
else if (a === "--read-only") readOnly = true;
else if (a === "--admin") admin = true;
else if (a === "--ttl") ttl = value();
else usage("mcp-token");
}
for (const h of hosts) {
try { resolveHost(h); } catch (e) { die(`--host ${h}: ${/** @type {Error} */ (e).message} (boxery host ls lists the hosts)`); }
}
const scope = { tools: toolsScope(toolCatalog(), { tools, readOnly }), hosts: hostNames(hosts), vms: vmPatterns(vms), admin };
const { secret, entry } = createToken(/** @type {string} */ (label), scope, { ttl: parseTtl(ttl) });
say(secret);
process.stderr.write(`boxery: token ${entry.label}: ${describeScope(scope, "the server's --host")}; expires ${when(entry.expires)}.\n` +
"boxery: shown once. Give it to the MCP client as: Authorization: Bearer <token>\n");
return;
}
case "ls": {
const json = rest[0] === "--json";
if (rest.length > (json ? 1 : 0)) usage("mcp-token");
const entries = readStore().map(({ hash: _h, ...e }) => e);
if (json) return say(JSON.stringify(entries, null, 2));
if (!entries.length) return say("no MCP tokens (create one: boxery mcp-token new LABEL)");
for (const e of entries) {
say(`${e.label}\texpires ${when(e.expires)}${e.expires != null && e.expires <= Date.now() / 1000 ? " (expired)" : ""}`);
say(` ${describeScope(e.scope, "the server's --host")}`);
for (const o of e.owned) say(` created ${o.host}/${o.vm}${o.key ? "" : " (identified by name only: its backend manages host keys)"}`);
}
return;
}
case "rm": {
if (rest.length !== 1) usage("mcp-token");
if (!removeToken(rest[0])) die(`no MCP token labelled ${rest[0]}`);
say(`removed MCP token ${rest[0]}; a server using it refuses it from the next request`);
return;
}
default:
usage("mcp-token");
}
}
13 changes: 10 additions & 3 deletions core/boxery-core.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import { q } from "./shell.mjs";
import { streamCopy } from "./copy-stream.mjs";
import { DEFAULT_HOST_BIN, VALID_DEST, localHostBin, parseConfig, shellWord } from "./ssh-config.mjs";
import { acquireLease, findLease, releaseLease, renewLease } from "./leases.mjs";
import { authorizeAdmin, authorizeVm } from "./mcp-auth.mjs";
import * as lifecycle from "./lifecycle.mjs";
import { versions as versionInfo } from "./versions.mjs";
import { parseGrantRequest, grantPrompt, grantCommand, listGrants, addGrants } from "./grants.mjs";
Expand Down Expand Up @@ -255,6 +256,7 @@ export function describeHosts() {
*/
export async function addHost({ name, dest, backend, profile }, { progress } = {}) {
assertHost(name);
authorizeAdmin(`adding host ${name}`);
if (typeof dest !== "string" || !VALID_DEST.test(dest)) throw new Error(`invalid destination "${dest ?? ""}" (local, or an ssh destination such as user@host)`);
if (backend != null && !VALID_HOST.test(backend)) throw new Error(`invalid backend "${backend}"`);
if (profile != null && !VALID_HOST.test(profile)) throw new Error(`invalid host profile "${profile}"`);
Expand All @@ -269,6 +271,7 @@ export async function addHost({ name, dest, backend, profile }, { progress } = {
* grants stay). @param {string} name @returns {Promise<string>} */
export async function removeHost(name) {
assertHost(name);
authorizeAdmin(`removing host ${name}`);
const registry = await import("./registry.mjs");
const { io, text } = registry.textIO();
try { await registry.withRegistryLock(async () => registry.removeHostLocked(name, io)); }
Expand Down Expand Up @@ -345,10 +348,11 @@ export function parseLoc(spec, current) {
* (vmProblem), unless a fresh connection works: then the 255 was the script's own and resolves.
* @param {string} vm @param {string} script @param {SshRunOpts} [opts] @returns {Promise<SshResult>}
*/
export function sshRun(vm, script, opts = {}) {
export async function sshRun(vm, script, opts = {}) {
if (!VALID_NAME.test(vm ?? "")) throw new Error(`invalid VM name "${vm}"`);
const host = currentHost();
await authorizeVm(host, vm); // scoped MCP tokens (core/mcp-auth.mjs)
return new Promise((resolve, reject) => {
if (!VALID_NAME.test(vm ?? "")) return reject(new Error(`invalid VM name "${vm}"`));
const host = currentHost();
const { sshConf } = host;
if (!existsSync(sshConf)) return reject(new Error(`boxery not set up (${sshConf} missing); run: boxery setup user@host`));
// stdin is a pipe whenever it is used (opts.input != null).
Expand Down Expand Up @@ -449,6 +453,7 @@ export const noSuchVm = (vm) => `no such vm: ${vm} on host ${currentHost().name}
*/
export async function vmProblem(vm, { env, signal } = {}) {
assertName(vm);
await authorizeVm(currentHost(), vm);
const probe = await new Promise((/** @type {(r: { code: number | null, stderr: string }) => void} */ resolve) => {
const child = spawn("ssh", ["-F", currentHost().sshConf, "-o", "BatchMode=yes", "-o", "ControlMaster=no", "-o", "ControlPath=none", `${vm}.boxery`, "true"],
{ stdio: ["ignore", "ignore", "pipe"], ...(env ? { env } : {}) });
Expand Down Expand Up @@ -966,6 +971,8 @@ export async function copyTool({ from, to }, { current, localCwd = process.cwd()
};
const source = endpoint(src);
const destination = endpoint(dst, path.posix.basename(source.path));
// The copy's own ssh (core/copy-stream.mjs) carries no host context: check each VM endpoint here, on its host.
for (const loc of [src, dst]) if (loc.vm) await authorizeVm(loc.host, loc.vm);
// (Each endpoint on its own host: HOST/NAME:path may name another.)
const unreachable = (/** @type {CopyEndpoint} */ e) => withHost(e === source ? src.host : dst.host, () => vmProblem(/** @type {string} */ (e.vm), { signal }));
const bytes = await streamCopy(source, destination, { signal, unreachable });
Expand Down
Loading