@engenty/wizards-runtime 0.7.5 → 0.7.6

package/apps/runtime/dist/cli/environment.js

@@ -36,6 +36,8 @@ const INHERITED = new Set([
     "SANDBOX",
     "SANDBOX_ENABLED",
     "SANDBOX_IMAGE",
+    "SANDBOX_ALLOW_HOSTS",
+    "SANDBOX_ENGINES_DIR",
     "PLUGINS_DIR",
     "PLUGINS_WATCH",
     "ACCOUNT_URL",

package/apps/runtime/dist/cli/main.js

@@ -8,6 +8,7 @@ import { CLIENTS, nodeIsCurrent } from "./machine.js";
 import { mcp } from "./mcp.js";
 import { menu } from "./menu.js";
 import { logsCommand, reportCommand } from "./report.js";
+import { sandboxCommand } from "./sandbox.js";
 import { setup } from "./setup.js";
 import { open, start, studio } from "./start.js";
 import { autostart, restart, status, stop } from "./status.js";
@@ -40,6 +41,8 @@ ${line(`${command()} restart`, "restart it, e.g. to switch to a newly installed
 ${line(`${command()} update`, "install the latest version")}
 ${line(`${command()} autoupdate`, "updates by themselves: add on or off (WIZARDS_DISABLE_AUTOUPDATE=1 is off too)")}
 ${more("(downloaded in the background, used from the next start; never during a run)")}
+${line(`${command()} sandbox`, "the sandbox where AI steps run code, without Docker: add or remove")}
+${more("(agentOS unless you name another engine, about 340 MB; used from the next start)")}
 ${line(`${command()} autostart`, "start it when you log in to this computer: add on or off")}
 ${more("(macOS: a LaunchAgent; Linux: a systemd user service)")}
 ${line(`${command()} connect`, "add your wizards to your AI apps: every app found, or the ones you name:")}
@@ -70,6 +73,7 @@ function parse(argv) {
     const args = {
         command: "",
         value: "",
+        engine: "",
         apps: [],
         paths: [],
         json: false,
@@ -116,10 +120,13 @@ function parse(argv) {
         else if (arg.startsWith("-")) {
             return `Unknown option ${arg}.`;
         }
-        else if (["autostart", "autoupdate", "logs", "account"].includes(args.command) &&
+        else if (["autostart", "autoupdate", "logs", "account", "sandbox"].includes(args.command) &&
             !args.value) {
             args.value = arg;
         }
+        else if (args.command === "sandbox" && !args.engine) {
+            args.engine = arg;
+        }
         else if (["connect", "disconnect", "features"].includes(args.command)) {
             args.apps.push(arg);
         }
@@ -199,6 +206,8 @@ async function main(argv) {
             return autoUpdateCommand(paths, args.value);
         case "account":
             return accountCommand(paths, args.value, { yes: args.yes });
+        case "sandbox":
+            return sandboxCommand(paths, args.value, args.engine);
         case "connect":
         case "disconnect":
             return connectCommand(paths, args.apps, args.command === "disconnect");

package/apps/runtime/dist/cli/sandbox.js

@@ -0,0 +1,77 @@
+import { delimiter, dirname, join } from "node:path";
+import { ENGINE_PACKAGES, engineList, installEngine, installedVersion, removeEngine, } from "../sandbox/install.js";
+import { runtimePath } from "./environment.js";
+import { runLogged } from "./exec.js";
+import { findOnPath } from "./machine.js";
+import { busy, cmd, no, ok, tilde } from "./ui.js";
+/** What `sandbox add` installs when no engine is named. */
+const DEFAULT_ENGINE = "agentos";
+/** Where an engine goes: `SANDBOX_ENGINES_DIR/<name>`, else `engines/<name>` in the install's folder. */
+export const engineDirOf = (paths, name) => join(process.env.SANDBOX_ENGINES_DIR?.trim() || join(paths.home, "engines"), name);
+/** The engines installed here, with their versions and the versions this release installs. */
+export function installedEngines(paths) {
+    return Object.entries(ENGINE_PACKAGES).flatMap(([name, engine]) => {
+        const version = installedVersion(engineDirOf(paths, name));
+        return version ? [{ name, label: engine.label, version, current: engine.version }] : [];
+    });
+}
+/**
+ * `wizards sandbox [add|remove] [engine]`: the sandbox where AI steps run code, without Docker.
+ * The engines are not part of engenty wizards; `add` downloads one beside the install.
+ */
+export async function sandboxCommand(paths, value, engine = "") {
+    const name = engine.toLowerCase() || DEFAULT_ENGINE;
+    if ((value === "add" || value === "remove") && !ENGINE_PACKAGES[name]) {
+        console.error(`${no} There is no engine “${name}”. ${engineList()}`);
+        return 2;
+    }
+    if (value === "add") {
+        return add(paths, name);
+    }
+    if (value === "remove") {
+        removeEngine(engineDirOf(paths, name));
+        console.log(`${ok} The sandbox ${ENGINE_PACKAGES[name].label} is removed. It goes away with the next ${cmd("restart")}.`);
+        return 0;
+    }
+    if (value) {
+        console.error(`Use ${cmd("sandbox add")} or ${cmd("sandbox remove")}.`);
+        return 2;
+    }
+    const installed = installedEngines(paths);
+    if (!installed.length) {
+        console.log(`${no} No sandbox is installed. AI steps can’t run code unless Docker has the engenty-sandbox image. To add one: ${cmd("sandbox add")}`);
+        return 0;
+    }
+    for (const { name, label, version } of installed) {
+        console.log(`${ok} The sandbox ${label} ${version} is in ${tilde(engineDirOf(paths, name))}.`);
+    }
+    console.log(`AI steps run code in ${installed.length === 1 ? "it" : "the first one"}, unless Docker has the engenty-sandbox image or SANDBOX names an engine.`);
+    return 0;
+}
+async function add(paths, name) {
+    const engine = ENGINE_PACKAGES[name];
+    const unsupported = engine.unsupported?.();
+    if (unsupported) {
+        console.error(`${no} ${unsupported}`);
+        return 1;
+    }
+    const npm = findOnPath("npm", [dirname(process.execPath), process.env.PATH ?? ""].join(delimiter));
+    if (!npm) {
+        console.error(`${no} npm wasn’t found next to this Node.js.`);
+        return 1;
+    }
+    const env = { ...process.env, PATH: runtimePath(paths, process.env) };
+    const logFile = join(paths.logs, "install.log");
+    const dir = engineDirOf(paths, name);
+    const spinner = busy(`Installing the sandbox (${engine.label} ${engine.version}, ${engine.size})…`);
+    try {
+        await installEngine(name, dir, (args) => runLogged(npm, args, { env, logFile }));
+    }
+    catch (err) {
+        spinner.fail(`The sandbox couldn’t be installed: ${err.message}`);
+        return 1;
+    }
+    spinner.stop(`${ok} The sandbox is installed in ${tilde(dir)}.`);
+    console.log(`AI steps run code in it from the next start: ${cmd("restart")}`);
+    return 0;
+}

package/apps/runtime/dist/cli/status.js

@@ -6,6 +6,7 @@ import { autoUpdatePolicy, updateNotice } from "./autoupdate.js";
 import { installedByScript, isCheckout, packageRoot, packageVersion } from "./home.js";
 import { detectClients, findChrome, findFfmpeg, nodeIsCurrent } from "./machine.js";
 import { findWizardsProcesses, stopProcesses } from "./processes.js";
+import { installedEngines } from "./sandbox.js";
 import { entryUrl, runningRuntime, settings, startInBackground } from "./start.js";
 import { bad, badge, cmd, cyan, dim, no, ok, tilde } from "./ui.js";
 /**
@@ -45,6 +46,14 @@ export async function status(paths, checks) {
     }
     row("Browser", chrome ? `${ok} ${dim(tilde(chrome))}` : `${no} not found (needed for PDF and PNG)`);
     row("ffmpeg", ffmpeg.path ? `${ok} ${ffmpeg.version ?? ""}` : `${no} not found (needed for MP4)`);
+    const engines = installedEngines(paths);
+    row("Sandbox", engines.length
+        ? engines
+            .map(({ label, version, current }) => version === current
+            ? `${ok} ${label} ${version}`
+            : `${no} ${label} ${version} is outdated (${cmd("sandbox add")} installs ${current})`)
+            .join(", ")
+        : `${no} not installed (${cmd("sandbox add")} lets AI steps run code)`);
     const { updated, pending } = updateNotice(paths, packageVersion());
     if (updated) {
         console.log(`\n  ${ok} Updated to ${updated.to}. What changed: ${cyan(updated.notes)}`);

package/apps/runtime/dist/debug.js

@@ -8,6 +8,7 @@ import { logState, startedAt, tail } from "./log.js";
 import { managed } from "./manage.js";
 import { modelSettings } from "./models.js";
 import { loadedPlugins } from "./plugins/registry.js";
+import { sandboxEngine } from "./sandbox/index.js";
 import { runIndexOf, tenantOfRun } from "./tenants/control.js";
 import { LOCAL_TENANT } from "./tenants/tenant.js";
 /**
@@ -41,7 +42,7 @@ export async function status() {
         appUrl: env.appUrl,
         manageUrl: env.manage.url || null,
         gatewayUrl: (managed ? env.manage.gatewayUrl : env.local.gatewayUrl) || null,
-        sandbox: env.sandbox,
+        sandbox: sandboxEngine()?.name ?? "off",
         browser: env.browserCdpUrl ? "cdp" : "local",
         files: env.s3.bucket ? "s3" : "data folder",
         database: env.databaseUrl ? "libsql" : "file",

package/apps/runtime/dist/docs/user/command-line.md

@@ -21,6 +21,7 @@ version: 0.5.0
 | `wizards stop` | Stops it, with any other copy of it still running in the background. Your data is kept. AI apps that use your wizards start it again when you use one there |
 | `wizards restart` | Stops it and starts it again; after an update, that is the new version. If it isn’t running, it starts in the background |
 | `wizards update` | Installs the latest version |
+| `wizards sandbox add` / `remove` | Adds the sandbox where AI steps run code, or removes it. It is agentOS, about 340 MB, and needs no Docker. Without a sandbox, steps can’t run code. `wizards sandbox` alone shows whether it is there. Name an engine to add another one: `wizards sandbox add agentos` |
 | `wizards autostart on` / `off` | Starts it when you log in, or stops doing so. It is a LaunchAgent on macOS and a systemd user service on Linux |
 | `wizards connect [app …]` | Adds your wizards to your [AI apps](./ai-apps.md): every app found, or the ones you name |
 | `wizards disconnect [app …]` | Takes them out again |
@@ -51,6 +52,7 @@ running, `wizards start` opens the running one instead of starting a second.
 | `~/.engenty/wizards/.env` | The settings file |
 | `~/.engenty/wizards/plugins` | [Plugins](./plugins.md) on this computer |
 | `~/.engenty/wizards/logs` | Logs: `install.log`, `update.log`, `runtime.log` when it runs in the background, `autostart.log` when a Mac starts it at login |
+| `~/.engenty/wizards/engines` | The sandbox, once `wizards sandbox add` put it there: one folder per engine |
 | `~/.engenty/wizards/tools`, `runtime` | Its own Node.js, and engenty wizards itself |
 | `~/.engenty/wizards/bin/wizards` | The command; `~/.local/bin/wizards` links to it |
 
@@ -65,6 +67,7 @@ the studio doesn’t: one `NAME=value` per line. Restart engenty wizards after a
 | `API_PORT` | The port | `24368`; if it is taken, the next free one up to `24387` |
 | `CHROME_PATH` | The browser for PDF and PNG exports and steps on websites: Chrome, Edge, Chromium or Brave | The first one found: on a Mac Google Chrome, Microsoft Edge, Chromium or Brave in `/Applications` or `~/Applications`; on Linux `google-chrome`, `chromium`, `chromium-browser` or `microsoft-edge` on the PATH. `wizards status` names it |
 | `FFMPEG_PATH` | ffmpeg for MP4 videos | `ffmpeg` |
+| `SANDBOX_ALLOW_HOSTS` | Addresses the sandbox reaches besides the npm and PyPI registries, comma-separated: `api.example.com`. It reaches nothing else | not set |
 | `OLLAMA_URL` | Where Ollama answers | `http://127.0.0.1:11434/v1` |
 | `PLUGINS_DIR` | Folders with plugins, comma-separated. If you set it, it replaces the default | `~/.engenty/wizards/plugins` |
 | `PLUGINS_WATCH` | With `0`, plugins no longer load again when their files change | `1` |

package/apps/runtime/dist/docs/user/server.md

@@ -35,7 +35,7 @@ The logs show a link (“Open the studio: …”). Open it once: it signs your b
 | Data | Databases and files are on the `/data` volume. Back that volume up |
 | Models | Your own API keys or Ollama. The subscriptions of AI clients live on your own computer, not on a server |
 | PDF, PNG, browser steps, MP4 | Chromium and ffmpeg are in the image |
-| Code & shell | The sandbox is off in this image, so steps can’t use that tool. `compose.yaml` shows how to switch it on |
+| Code & shell | The sandbox is off in this image, so steps can’t use that tool. `compose.yaml` shows how to switch it on: with Docker, or with agentOS built into the image |
 | Plugins | Put them in a folder that you mount into the container and name in `PLUGINS_DIR` |
 
 ## Update

package/apps/runtime/dist/env.js

@@ -1,9 +1,9 @@
-import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { join, resolve } from "node:path";
 import { findChrome } from "./render/browser-path.js";
+import { enginesDir } from "./sandbox/install.js";
 /** Load `.env.local` then `.env` without overriding the real environment. */
 function loadEnvFiles() {
     for (const name of [".env.local", ".env"]) {
@@ -22,29 +22,6 @@ function loadEnvFiles() {
 }
 loadEnvFiles();
 const str = (key, fallback = "") => process.env[key]?.trim() || fallback;
-/**
- * Without `SANDBOX`: Docker when the sandbox image is on this machine, else none.
- * The image is not published, so a fresh install would otherwise offer a tool that cannot start.
- */
-function sandboxEngine(image) {
-    const engine = str("SANDBOX");
-    if (str("SANDBOX_ENABLED", "1") !== "1" || engine === "off") {
-        return "off";
-    }
-    if (engine) {
-        return "docker";
-    }
-    return dockerHasImage(image) ? "docker" : "off";
-}
-function dockerHasImage(image) {
-    try {
-        execFileSync("docker", ["image", "inspect", image], { stdio: "ignore", timeout: 5000 });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /** A comma-separated list. */
 const list = (key) => str(key)
     .split(",")
@@ -217,9 +194,16 @@ export const env = {
             : "/usr/bin/chromium")),
     /** Encodes widget animations to MP4; without it widgets offer no video. */
     ffmpegPath: str("FFMPEG_PATH", "ffmpeg"),
-    /** What runs an agent's shell and code: a Docker container or nothing. */
-    sandbox: sandboxEngine(sandboxImage),
+    /**
+     * The engine that runs an agent's shell and code (sandbox/index.ts): `off`, an engine's name,
+     * or empty for the first one that is ready here.
+     */
+    sandbox: str("SANDBOX_ENABLED", "1") === "1" ? str("SANDBOX").toLowerCase() : "off",
     sandboxImage,
+    /** Where `wizards sandbox add` installs the engines that aren't part of the runtime. */
+    sandboxEngines: enginesDir(),
+    /** Hosts an agentOS sandbox reaches besides the npm and PyPI registries: `api.example.com`. */
+    sandboxHosts: list("SANDBOX_ALLOW_HOSTS"),
     /** Assets and workspace files in an S3-compatible bucket (R2); empty = the data folder. */
     s3: {
         endpoint: str("S3_ENDPOINT").replace(/\/$/, ""),

package/apps/runtime/dist/sandbox/agentos-package.js

@@ -0,0 +1,73 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+/**
+ * What `wizards sandbox add agentos` installs (install.ts): agentOS's core, about 340 MB, which
+ * only the computers and servers that run the sandbox with it need.
+ */
+export const AGENTOS_VERSION = "0.4.1";
+export const AGENTOS_CORE = "@rivet-dev/agentos-core";
+/** The helper agentOS ships for each platform, beside the core: `<package>/agentos-native-sidecar`. */
+const SIDECAR_PACKAGE = "@rivet-dev/agentos-runtime-sidecar-";
+/** Where the core keeps its programs, compiled to WebAssembly. */
+const COMMANDS = join("node_modules", "@rivet-dev", "agentos-runtime-core", "commands");
+/**
+ * Programs agentOS ships but leaves off the PATH; the install packs them so every VM has them.
+ * The ones from the `@agentos-software` registry are in a format 0.4 no longer reads.
+ */
+export const AGENTOS_EXTRA_COMMANDS = ["curl", "git", "jq", "sqlite3", "unzip", "zip"];
+/** Dependencies of the core that its code never imports: Google and AWS clients, about 140 MB. */
+const UNUSED = ["googleapis", "googleapis-common", "@aws-sdk", "@smithy", "better-sqlite3"];
+/** agentOS ships its helper for macOS and glibc Linux, on arm64 and x64. */
+export function agentOsSupported(platform = process.platform, arch = process.arch) {
+    return ["darwin", "linux"].includes(platform) && ["arm64", "x64"].includes(arch);
+}
+/** The package of extra programs every VM gets (AGENTOS_EXTRA_COMMANDS). */
+export const agentOsExtras = (dir) => join(dir, "extras");
+/** The helper with its routine lines filtered out, or null where there is no bash. */
+export const agentOsSidecar = (dir) => join(dir, "sidecar.sh");
+/** An agentOS package is a folder with a manifest and its programs in `bin/`. */
+function packExtras(dir) {
+    const bin = join(agentOsExtras(dir), "bin");
+    mkdirSync(bin, { recursive: true });
+    for (const command of AGENTOS_EXTRA_COMMANDS) {
+        const target = join(bin, command);
+        copyFileSync(join(dir, COMMANDS, command), target);
+        // Without the mode, the VM finds the program and refuses to run it.
+        chmodSync(target, 0o755);
+    }
+    writeFileSync(join(agentOsExtras(dir), "agentos-package.json"), `${JSON.stringify({ name: "engenty-wizards-extras", version: AGENTOS_VERSION })}\n`);
+}
+/**
+ * The helper prints a line on stderr for every engine it keeps warm, a few per command, and
+ * agentOS passes its stderr on to the server's. The wrapper leaves those lines out.
+ */
+function writeSidecarWrapper(dir) {
+    const bash = ["/bin/bash", "/usr/bin/bash"].find((path) => existsSync(path));
+    const modules = join(dir, "node_modules", "@rivet-dev");
+    const platform = readdirSync(modules).find((name) => `@rivet-dev/${name}`.startsWith(SIDECAR_PACKAGE));
+    const helper = platform && join(modules, platform, "agentos-native-sidecar");
+    if (!bash || !helper || !existsSync(helper)) {
+        return;
+    }
+    const quoted = `'${helper.replaceAll("'", `'\\''`)}'`;
+    writeFileSync(agentOsSidecar(dir), `#!${bash}\n` +
+        "# agentOS's helper without the lines it prints for every engine it keeps warm.\n" +
+        `exec ${quoted} "$@" 2> >(grep --line-buffered -v -e '^agentos-v8-runtime: ' -e 'vfs::posix::tar_fs' >&2)\n`);
+    chmodSync(agentOsSidecar(dir), 0o755);
+}
+export const AGENTOS_PACKAGE = {
+    label: "agentOS",
+    version: AGENTOS_VERSION,
+    packages: [`${AGENTOS_CORE}@${AGENTOS_VERSION}`],
+    size: "about 340 MB",
+    unsupported: () => agentOsSupported()
+        ? null
+        : `agentOS runs on macOS and Linux (arm64, x64), not on ${process.platform} ${process.arch}.`,
+    prepare(dir) {
+        for (const name of UNUSED) {
+            rmSync(join(dir, "node_modules", name), { recursive: true, force: true });
+        }
+        packExtras(dir);
+        writeSidecarWrapper(dir);
+    },
+};

package/apps/runtime/dist/sandbox/agentos.js

@@ -0,0 +1,162 @@
+import { existsSync } from "node:fs";
+import { join, posix } from "node:path";
+import { env } from "../env.js";
+import { AGENTOS_CORE, AGENTOS_EXTRA_COMMANDS, agentOsExtras, agentOsSidecar, } from "./agentos-package.js";
+import { importFromEngine, installedVersion } from "./install.js";
+const WORKDIR = "/workspace";
+const EXEC_TIMEOUT_MS = 120_000;
+/**
+ * Python starts in $HOME, whatever directory the shell is in. Before each command, `python3`
+ * becomes a function that hands it the shell's directory as HOME.
+ */
+const PYTHON_FOLLOWS_CD = 'python3() { HOME="$PWD" command python3 "$@"; }; python() { python3 "$@"; }\n';
+/** Where npm and Python packages come from: every VM reaches them. */
+const REGISTRIES = ["registry.npmjs.org", "pypi.org", "files.pythonhosted.org"];
+/**
+ * What an agentOS VM runs: a Linux userland compiled to WebAssembly (bash, coreutils and the
+ * extra programs the install packs), Node in a V8 isolate and Python 3.13 as Pyodide. No native
+ * programs: no ffmpeg, ImageMagick or LibreOffice.
+ */
+export function agentOsCapabilities(hosts = []) {
+    return {
+        commands: [
+            "bash",
+            "ls",
+            "cat",
+            "head",
+            "sort",
+            "grep",
+            "sed",
+            "awk",
+            "find",
+            "diff",
+            "tar",
+            "gzip",
+            ...AGENTOS_EXTRA_COMMANDS,
+            "node",
+            "npm",
+            "python3",
+        ],
+        network: hosts.length
+            ? `only the npm and PyPI registries and ${hosts.join(", ")}`
+            : "none, except the npm and PyPI registries",
+        notes: "python3 is Pyodide: numpy and pandas load offline; install other pure-Python packages with " +
+            `python3 -c "import micropip; await micropip.install('openpyxl')" (no pip command, no ` +
+            "pillow, matplotlib or scipy). node runs JavaScript, not TypeScript.",
+        uses: "calculations, tables or file conversion",
+        workdir: WORKDIR,
+    };
+}
+let runtime = null;
+/** One native helper process hosts the VMs of every run; the first sandbox starts it. */
+function agentOsRuntime(dir) {
+    runtime ??= (async () => {
+        // agentOS reads the helper's path from the environment when it starts the helper.
+        if (!process.env.AGENTOS_SIDECAR_BIN && existsSync(agentOsSidecar(dir))) {
+            process.env.AGENTOS_SIDECAR_BIN = agentOsSidecar(dir);
+        }
+        const mod = (await importFromEngine("agentos", dir, AGENTOS_CORE));
+        return { agentOs: mod.AgentOs, sidecar: await mod.AgentOs.createSidecar() };
+    })().catch((err) => {
+        runtime = null;
+        throw err;
+    });
+    return runtime;
+}
+/** Stops the helper process. The next sandbox starts a new one. */
+export async function stopAgentOs() {
+    const current = runtime;
+    runtime = null;
+    await (await current?.catch(() => null))?.sidecar.dispose();
+}
+function toResult(result) {
+    const stdout = result.stdout ?? "";
+    let stderr = result.stderr ?? "";
+    if (result.outcome === "timed_out") {
+        stderr = `${stderr}\ntimed out`.trim();
+    }
+    else if (result.outcome !== "succeeded" && !stdout && !stderr) {
+        stderr = result.error?.message ?? result.outcome;
+    }
+    return { exitCode: result.exitCode ?? (result.outcome === "succeeded" ? 0 : 1), stdout, stderr };
+}
+/** Where `wizards sandbox add agentos` put it. */
+export const agentOsDir = () => join(env.sandboxEngines, "agentos");
+/** Ready once `wizards sandbox add agentos` installed it. */
+export const agentOsEngine = {
+    name: "agentos",
+    ready: () => installedVersion(agentOsDir()) !== null,
+    capabilities: () => agentOsCapabilities(env.sandboxHosts),
+    create: () => new AgentOsSandbox(),
+};
+/** One agentOS VM per run, in the server's helper process: no Docker, no container. */
+export class AgentOsSandbox {
+    dir;
+    hosts;
+    capabilities;
+    machine = null;
+    constructor(dir = agentOsDir(), hosts = env.sandboxHosts) {
+        this.dir = dir;
+        this.hosts = hosts;
+        this.capabilities = agentOsCapabilities(hosts);
+    }
+    vm() {
+        this.machine ??= (async () => {
+            const { agentOs, sidecar } = await agentOsRuntime(this.dir);
+            const vm = await agentOs.create({
+                sidecar: { kind: "explicit", handle: sidecar },
+                software: [{ packagePath: agentOsExtras(this.dir) }],
+                // Anything not listed is refused, the host's own loopback and private networks included.
+                permissions: {
+                    fs: "allow",
+                    childProcess: "allow",
+                    process: "allow",
+                    env: "allow",
+                    network: {
+                        default: "deny",
+                        rules: [
+                            {
+                                mode: "allow",
+                                operations: ["*"],
+                                patterns: [...REGISTRIES, ...this.hosts].flatMap((host) => [
+                                    `dns://${host}`,
+                                    `tcp://${host}:443`,
+                                ]),
+                            },
+                        ],
+                    },
+                },
+            });
+            await vm.filesystem.mkdir(WORKDIR, { recursive: true });
+            return vm;
+        })();
+        this.machine.catch(() => {
+            this.machine = null;
+        });
+        return this.machine;
+    }
+    async exec(command, options = {}) {
+        const vm = await this.vm();
+        return toResult(await vm.process.exec(PYTHON_FOLLOWS_CD + command, {
+            cwd: options.cwd ?? WORKDIR,
+            env: { HOME: WORKDIR, ...options.env },
+            timeoutMs: options.timeoutMs ?? EXEC_TIMEOUT_MS,
+            output: { capture: "all" },
+        }));
+    }
+    async writeFile(path, data) {
+        const vm = await this.vm();
+        const target = posix.resolve(WORKDIR, path);
+        await vm.filesystem.mkdir(posix.dirname(target), { recursive: true });
+        await vm.filesystem.writeFile(target, data);
+    }
+    async readFile(path) {
+        const vm = await this.vm();
+        return vm.filesystem.readFile(posix.resolve(WORKDIR, path));
+    }
+    async destroy() {
+        const machine = this.machine;
+        this.machine = null;
+        await (await machine?.catch(() => null))?.dispose();
+    }
+}

package/apps/runtime/dist/sandbox/docker.js

@@ -1,8 +1,9 @@
+import { execFileSync } from "node:child_process";
 import { DockerSandbox } from "@mastra/docker";
+import { env } from "../env.js";
+import { MastraRunSandbox } from "./mastra.js";
 /** The image's own working directory, the one its unprivileged user may write to. */
 const WORKDIR = "/sandbox";
-/** Bytes per append when a file is written through the shell; stays far below ARG_MAX. */
-const WRITE_CHUNK = 48 * 1024;
 /** What the engenty-sandbox image carries. The container sits on Docker's default bridge. */
 export const DOCKER_CAPABILITIES = {
     commands: ["bash", "python3", "pip", "uv", "node", "npm", "bun", "jq", "curl", "git", "unzip"],
@@ -10,66 +11,35 @@ export const DOCKER_CAPABILITIES = {
     uses: "calculations, charts or file conversion",
     workdir: WORKDIR,
 };
-const quote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
-/** One container per run through the host's Docker. */
-export class DockerRunSandbox {
-    runId;
-    image;
-    capabilities = DOCKER_CAPABILITIES;
-    container = null;
-    constructor(runId, image) {
-        this.runId = runId;
-        this.image = image;
-    }
-    start() {
-        this.container ??= (async () => {
-            const sandbox = new DockerSandbox({
-                id: `wizards-${this.runId.toLowerCase()}`,
-                image: this.image,
-                memory: 1024 * 1024 * 1024,
-                pidsLimit: 256,
-                capDrop: ["ALL"],
-                securityOpt: ["no-new-privileges"],
-                workingDir: WORKDIR,
-                labels: { "engenty-wizards.run": this.runId },
-            });
-            await sandbox.start();
-            return sandbox;
-        })();
-        return this.container;
-    }
-    async exec(command, options = {}) {
-        const sandbox = await this.start();
-        const result = await sandbox.executeCommand(command, [], {
-            timeout: options.timeoutMs,
-            cwd: options.cwd,
-            env: options.env,
-        });
-        return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
-    }
-    async writeFile(path, data) {
-        const target = quote(path);
-        const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
-        await this.must(`mkdir -p "$(dirname ${target})" && : > ${target}`);
-        for (let at = 0; at < bytes.length; at += WRITE_CHUNK) {
-            const chunk = bytes.subarray(at, at + WRITE_CHUNK).toString("base64");
-            await this.must(`printf %s ${chunk} | base64 -d >> ${target}`);
-        }
-    }
-    async readFile(path) {
-        const result = await this.must(`base64 -w0 ${quote(path)}`);
-        return Buffer.from(result.stdout.trim(), "base64");
-    }
-    async must(command) {
-        const result = await this.exec(command);
-        if (result.exitCode !== 0) {
-            throw new Error(result.stderr.trim() || `exit code ${result.exitCode}`);
-        }
-        return result;
+/** One container per run through the host's Docker, with Mastra's Docker sandbox. */
+export function dockerSandbox(runId, image) {
+    return new MastraRunSandbox(DOCKER_CAPABILITIES, () => new DockerSandbox({
+        id: `wizards-${runId.toLowerCase()}`,
+        image,
+        memory: 1024 * 1024 * 1024,
+        pidsLimit: 256,
+        capDrop: ["ALL"],
+        securityOpt: ["no-new-privileges"],
+        workingDir: WORKDIR,
+        labels: { "engenty-wizards.run": runId },
+    }));
+}
+export function dockerHasImage(image) {
+    try {
+        execFileSync("docker", ["image", "inspect", image], { stdio: "ignore", timeout: 5000 });
+        return true;
     }
-    async destroy() {
-        const container = this.container;
-        this.container = null;
-        await (await container?.catch(() => null))?.destroy();
+    catch {
+        return false;
     }
 }
+/**
+ * Ready where Docker has the sandbox image (`SANDBOX_IMAGE`). The image is not published, so
+ * without the check a fresh install would offer a tool that cannot start.
+ */
+export const dockerEngine = {
+    name: "docker",
+    ready: () => dockerHasImage(env.sandboxImage),
+    capabilities: () => DOCKER_CAPABILITIES,
+    create: (runId) => dockerSandbox(runId, env.sandboxImage),
+};