@volter/browser-host-node

The hosted backend's guest side. It composes the unchanged engine-neutral kernel from @volter/browser-runtime onto a machine: a disk-backed implementation of the filesystem contract, a shell lane that runs every command the kernel does not route to a registered program, discovery of guest listening sockets onto the virtual port table, PTY sessions on the guest's own script, per-process profiler rows, and an HTTP agent that exposes one runtime to a client outside the guest.

import { createNodeHost, serveAgent } from "@volter/browser-host-node";

const host = createNodeHost({ root: "/", confinement: { request: { filesystem: "workspace", network: "loopback" } } });
const result = await host.runtime.spawn("echo $((21 * 2))", { cwd: "/workspace" });
console.log(result.stdout); // 42

await serveAgent({ host, token: process.env.SUBSTRATE_TOKEN!, port: 8787 });

browser-substrate-agent runs the agent from the environment: SUBSTRATE_TOKEN (required), SUBSTRATE_ROOT (default a temporary directory; / inside a guest), PORT (8787), HOST (::), and the confinement request in SUBSTRATE_CONFINEMENT, SUBSTRATE_NETWORK, and SUBSTRATE_CONFINEMENT_ESCALATION. Guest processes inherit the host environment minus anything named SUBSTRATE_*.

PTY sessions use the prebuilt @lydell/node-pty allocator when it is installed (the guest image installs it), which makes resize real on any platform; without it, Linux guests fall back to util-linux script, where the initial size applies and resize is absent. Passing terminal to the ordinary runtime process API uses this same allocator, so callers do not need a separate PTY launch path.

browser-substrate-pglite-host serves a Postgres wire-protocol front over PGlite on loopback, the program the compose runner starts for image: postgres on a host without containers.

The wire

The agent describes itself at GET / as substrate-agent/1 with its route catalogue under /v1; every response carries x-substrate-protocol, and a client stating another version is refused with 426. The descriptor needs no token; the catalogue does. The contract lives in @volter/browser-runtime/browser-hosted-protocol.js and is walked by runHostedContract from @volter/browser-sandboxes.