@bakers-build/addon-runtime-docker 0.0.0-stage → 0.9.1-next.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @bakers-build/addon-runtime-docker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Start each agent run in its own Docker or Podman container.
+
+Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://github.com/bakers-build/bakers-build (bakers-cli/).

package/dist/src/args.d.ts

@@ -0,0 +1,44 @@
+import type { RuntimeLaunch } from '@bakers-build/conductor/contract';
+export interface DockerOptions {
+    /** The container CLI: `docker`, or `podman`. */
+    docker: string;
+    image: string;
+    /** Extra host paths, mounted read-only at the same path. */
+    mounts: string[];
+    network: 'host' | 'allowlist';
+    /** The conductor-specific internal network used in allowlist mode. */
+    runNetwork: string;
+    /** Allowlist mode: the conductor's proxy sidecar name. */
+    proxy?: string;
+}
+/** Host facts the launch depends on, resolved by the backend. */
+export interface HostPaths {
+    /** The run clone's Git directory, mounted as `<workspace>/.git`. */
+    runGitDir?: string;
+    /** A `shared` clone's parent object store, mounted read-only at its own path. */
+    sharedObjects?: string;
+    /** The per-run home, mounted at its host path. */
+    runHome: string;
+    /** The bakers CLI build, mounted read-only at its host path. */
+    cliRoot: string;
+    uid: number;
+    gid: number;
+}
+/** The image's PATH, behind the run home's `bin` (the `bakers` shim lives there). */
+export declare const RUN_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+export declare const PROXY_PORTS: {
+    readonly egress: 3128;
+    readonly api: 8081;
+    readonly tools: 8082;
+};
+/** What the run sends as its API key in allowlist mode; the proxy swaps in the real one. */
+export declare const API_KEY_PLACEHOLDER = "bb-runtime-placeholder";
+/**
+ * The `docker run` argv for one run. Pure: every secret travels as `-e KEY`
+ * with its value in the returned env, which the executor hands the docker
+ * client; nothing of the operator home is mounted beyond the list below.
+ */
+export declare function dockerArgs(input: RuntimeLaunch, opts: DockerOptions, where: HostPaths): {
+    argv: string[];
+    env: Record<string, string>;
+};

package/dist/src/args.js

@@ -0,0 +1,75 @@
+/** The image's PATH, behind the run home's `bin` (the `bakers` shim lives there). */
+export const RUN_PATH = `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`;
+export const PROXY_PORTS = { egress: 3128, api: 8081, tools: 8082 };
+/** What the run sends as its API key in allowlist mode; the proxy swaps in the real one. */
+export const API_KEY_PLACEHOLDER = 'bb-runtime-placeholder';
+/** Keys whose host value means nothing inside the container. */
+const HOST_ONLY = (key) => key === 'PATH' ||
+    key === 'HOME' ||
+    key === 'TMPDIR' ||
+    key.startsWith('XDG_');
+/**
+ * The `docker run` argv for one run. Pure: every secret travels as `-e KEY`
+ * with its value in the returned env, which the executor hands the docker
+ * client; nothing of the operator home is mounted beyond the list below.
+ */
+export function dockerArgs(input, opts, where) {
+    const ws = input.workspacePath;
+    const api = input.modelApi;
+    const bind = (from, to = from, mode = '') => [
+        '-v',
+        `${from}:${to}${mode}`,
+    ];
+    const env = { ...input.env };
+    const computed = [
+        `HOME=${where.runHome}`,
+        `PATH=${where.runHome}/bin:${RUN_PATH}`,
+    ];
+    const allowlist = opts.network === 'allowlist';
+    if (allowlist && api) {
+        const proxy = `http://${opts.proxy}:${PROXY_PORTS.egress}`;
+        computed.push(`HTTPS_PROXY=${proxy}`, `HTTP_PROXY=${proxy}`, `NO_PROXY=${opts.proxy}`, `${api.baseUrlEnv}=http://${opts.proxy}:${PROXY_PORTS.api}`, `${api.keyEnv}=${API_KEY_PLACEHOLDER}`);
+    }
+    const overridden = new Set(computed.map((c) => c.slice(0, c.indexOf('='))));
+    const credentials = Object.keys(api?.auth ?? {});
+    const forwarded = Object.keys(env).filter((k) => !HOST_ONLY(k) &&
+        !overridden.has(k) &&
+        // Allowlist mode keeps the model credential in the proxy only.
+        !(allowlist && credentials.includes(k)));
+    const ro = (path) => bind(path, path, ':ro');
+    const argv = [
+        opts.docker,
+        'run',
+        '--rm',
+        '-it',
+        '--name',
+        `bb-run-${input.run.uuid}`,
+        '--label',
+        `build.bakers.run=${input.run.uuid}`,
+        '--network',
+        allowlist ? opts.runNetwork : 'host',
+        '--user',
+        `${where.uid}:${where.gid}`,
+        ...(opts.docker.endsWith('podman') ? ['--userns=keep-id'] : []),
+        ...computed.flatMap((c) => ['-e', c]),
+        ...forwarded.flatMap((k) => ['-e', k]),
+        ...bind(ws),
+        // The only Git the run sees; the parent repository is not mounted.
+        ...(where.runGitDir ? bind(where.runGitDir, `${ws}/.git`) : []),
+        ...(where.sharedObjects ? ro(where.sharedObjects) : []),
+        ...bind(where.cliRoot, undefined, ':ro'),
+        ...opts.mounts.flatMap((m) => bind(m, m, ':ro')),
+        ...bind(where.runHome),
+        ...(input.readPaths ?? []).flatMap((path) => ro(path)),
+        ...(input.writePaths ?? []).flatMap((path) => bind(path)),
+        // Shared host files over their placeholders in the run home.
+        ...(input.bindPaths ?? []).flatMap(({ source, target }) => bind(source, target)),
+        '-w',
+        ws,
+        opts.image,
+        'sh',
+        '-c',
+        input.command,
+    ];
+    return { argv, env };
+}

package/dist/src/backend.d.ts

@@ -0,0 +1,35 @@
+import type { BbRuntime } from '@bakers-build/conductor/contract';
+import { type ConductorLogger } from '@bakers-build/core';
+/** The addon's `with` options. */
+export interface RuntimeDockerOptions {
+    /** The container CLI; `podman` works too. */
+    docker?: string;
+    /** An operator image; never built. Default: the shipped image. */
+    image?: string;
+    /** Extra host paths mounted read-only. */
+    mounts?: string[];
+    network?: 'host' | 'allowlist';
+    /** Allowlist mode: hosts the run may reach, exact or `*.suffix`. */
+    allow?: string[];
+}
+export interface BackendDeps {
+    exec(file: string, args: string[]): Promise<{
+        stdout: string;
+    }>;
+    /** The conductor's own environment (the model credential lives here). */
+    env: Record<string, string | undefined>;
+    logger: ConductorLogger;
+    /** The bakers CLI build, mounted read-only at its host path. */
+    cliRoot: string;
+    /** This package's directory; its `image/` holds the Dockerfile. */
+    packageDir: string;
+    version: string;
+    /** The running bakers entry script; the run calls it as `bakers`. Absent: no shim. */
+    bakersEntry?: string;
+    /** Names this conductor's proxy sidecar, so conductors on one host never share one. */
+    conductorKey?: string;
+}
+/** The first 12 hex chars of the sha256 of `text`. */
+export declare const shortHash: (text: string) => string;
+export declare const realExec: BackendDeps['exec'];
+export declare function dockerRuntime(options: RuntimeDockerOptions, deps: BackendDeps): BbRuntime;

package/dist/src/backend.js

@@ -0,0 +1,275 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { shellQuote } from '@bakers-build/core';
+import { API_KEY_PLACEHOLDER, dockerArgs, PROXY_PORTS, } from './args.js';
+const EGRESS_NETWORK = 'bb-runtime-egress';
+/** The first 12 hex chars of the sha256 of `text`. */
+export const shortHash = (text) => createHash('sha256').update(text).digest('hex').slice(0, 12);
+const run = promisify(execFile);
+export const realExec = (file, args) => run(file, args);
+export function dockerRuntime(options, deps) {
+    const docker = options.docker ?? 'docker';
+    const opts = {
+        docker,
+        mounts: options.mounts ?? [],
+        network: options.network ?? 'host',
+        runNetwork: `bb-runtime-${deps.conductorKey ?? 'default'}`,
+    };
+    const allowlist = opts.network === 'allowlist';
+    const proxyName = `bb-runtime-proxy-${deps.conductorKey ?? 'default'}`;
+    if (allowlist)
+        opts.proxy = proxyName;
+    let gateway;
+    let toolsPort;
+    let proxyReady;
+    const cacheHome = deps.env.XDG_CACHE_HOME || join(deps.env.HOME || homedir(), '.cache');
+    // The uuid names a container filter and a directory removed recursively.
+    const plainName = (uuid) => /^[A-Za-z0-9-]+$/.test(uuid);
+    const runHomeOf = (uuid) => {
+        if (!plainName(uuid))
+            throw new Error(`runtime-docker: invalid run uuid ${JSON.stringify(uuid)}`);
+        return join(cacheHome, 'bakers/runtime', uuid);
+    };
+    // One image per agent install; built once each.
+    const imagesReady = new Map();
+    const ensureImage = async (image, install) => {
+        try {
+            await deps.exec(docker, ['image', 'inspect', image]);
+        }
+        catch (err) {
+            if (options.image !== undefined)
+                throw new Error(`runtime-docker: image ${image} is not available (${String(err)}); pull or build it first`);
+            deps.logger.info({ image }, 'building the run image');
+            await deps.exec(docker, [
+                'build',
+                '-t',
+                image,
+                '--build-arg',
+                `AGENT_INSTALL=${install}`,
+                join(deps.packageDir, 'image'),
+            ]);
+        }
+    };
+    const ensureNetwork = async (name, internal) => {
+        try {
+            await deps.exec(docker, ['network', 'inspect', name]);
+        }
+        catch {
+            await deps.exec(docker, [
+                'network',
+                'create',
+                ...(internal ? ['--internal'] : []),
+                name,
+            ]);
+        }
+    };
+    // One sidecar per conductor; recreated only when what it relays changed.
+    // shortcut: one model API per sidecar; agents of different APIs on one conductor recreate it, give each its own when that is needed.
+    const startProxy = async (hash, credentials, api, image) => {
+        const current = await deps
+            .exec(docker, [
+            'inspect',
+            '-f',
+            '{{index .Config.Labels "build.bakers.proxy"}}',
+            proxyName,
+        ])
+            .then((r) => r.stdout.trim(), () => undefined);
+        if (current === hash)
+            return;
+        if (current !== undefined)
+            await deps.exec(docker, ['rm', '-f', proxyName]);
+        await deps.exec(docker, [
+            'run',
+            '-d',
+            '--restart',
+            'unless-stopped',
+            '--name',
+            proxyName,
+            '--label',
+            `build.bakers.proxy=${hash}`,
+            '--network',
+            EGRESS_NETWORK,
+            ...credentials.flatMap((k) => ['-e', k]),
+            '-e',
+            `BB_ALLOW=${(options.allow ?? []).join(',')}`,
+            '-e',
+            `BB_TOOLS=${gateway}:${toolsPort}`,
+            '-e',
+            `BB_API_TARGET=${api.target}`,
+            '-e',
+            `BB_API_AUTH=${JSON.stringify(api.auth)}`,
+            image,
+            'node',
+            '/opt/bb-runtime/proxy.mjs',
+        ]);
+        await deps.exec(docker, ['network', 'connect', opts.runNetwork, proxyName]);
+    };
+    const credentialsFor = (agent) => {
+        const api = agent.modelApi;
+        if (allowlist && !api)
+            throw new Error('runtime-docker: allowlist mode requires model API metadata');
+        const credentials = Object.keys(api?.auth ?? {}).filter((k) => deps.env[k]);
+        if (api && credentials.length === 0)
+            throw new Error(`runtime-docker: ${api.credentialHint}`);
+        return credentials;
+    };
+    const runtime = {
+        id: 'docker',
+        async prepareRun(run, agent) {
+            const credentials = credentialsFor(agent);
+            const homePath = runHomeOf(run.uuid);
+            mkdirSync(homePath, { recursive: true, mode: 0o700 });
+            const env = allowlist
+                ? { [agent.modelApi.keyEnv]: API_KEY_PLACEHOLDER }
+                : Object.fromEntries(credentials.map((k) => [k, deps.env[k]]));
+            return { homePath, env };
+        },
+        async wrap(launch) {
+            const runHome = runHomeOf(launch.run.uuid);
+            if (launch.homePath !== runHome)
+                throw new Error('runtime-docker: private run home was not prepared');
+            const api = launch.modelApi;
+            const credentials = credentialsFor(launch);
+            if (!options.image && !launch.installCommand)
+                throw new Error(`runtime-docker: agent ${launch.harness} has no installCommand; configure an image`);
+            const image = options.image ??
+                `bakers-runtime:${deps.version}-${shortHash(launch.installCommand ?? '')}`;
+            if (!imagesReady.has(image))
+                imagesReady.set(image, ensureImage(image, launch.installCommand ?? '').catch((err) => {
+                    imagesReady.delete(image);
+                    throw err;
+                }));
+            await imagesReady.get(image);
+            if (allowlist) {
+                if (!gateway || !toolsPort)
+                    throw new Error('runtime-docker: allowlist mode needs the conductor tool server; it was not started');
+                const hash = shortHash(JSON.stringify([
+                    gateway,
+                    toolsPort,
+                    options.allow ?? [],
+                    image,
+                    api,
+                    opts.runNetwork,
+                ]));
+                if (proxyReady?.hash !== hash)
+                    proxyReady = {
+                        hash,
+                        ready: startProxy(hash, credentials, api, image).catch((err) => {
+                            proxyReady = undefined;
+                            throw err;
+                        }),
+                    };
+                await proxyReady.ready;
+            }
+            const ws = launch.workspacePath;
+            const runGitDir = launch.gitDir;
+            const within = (path, root) => path === root || path.startsWith(root + sep);
+            if (within(realpathSync(dirname(runHome)), realpathSync(ws)))
+                throw new Error('runtime-docker: private state must stay outside the worktree');
+            if (runGitDir && within(realpathSync(runGitDir), realpathSync(ws)))
+                throw new Error('runtime-docker: the run Git directory must stay outside the workspace');
+            const canonical = (path) => existsSync(path) ? realpathSync(path) : resolve(path);
+            const binds = launch.bindPaths ?? [];
+            for (const { target } of binds)
+                if (target.includes(':') || !within(resolve(target), resolve(runHome)))
+                    throw new Error(`runtime-docker: shared file target outside the run home ${target}`);
+            for (const [paths, write] of [
+                [launch.readPaths ?? [], false],
+                [launch.writePaths ?? [], true],
+                [binds.map(({ source }) => source), true],
+            ]) {
+                for (const path of paths) {
+                    if (!isAbsolute(path) || path.includes(':') || !existsSync(path))
+                        throw new Error(`runtime-docker: invalid prepared path ${path}`);
+                    const actual = canonical(path);
+                    if (actual === '/' ||
+                        (deps.env.HOME && within(canonical(deps.env.HOME), actual)))
+                        throw new Error(`runtime-docker: refusing broad path ${path}`);
+                    if (write &&
+                        [
+                            ...(runGitDir ? [runGitDir] : []),
+                            ...(launch.sharedObjects ? [launch.sharedObjects] : []),
+                            dirname(runHome),
+                            join(ws, '.git'),
+                            deps.cliRoot,
+                            ...(launch.readPaths ?? []),
+                            ...opts.mounts,
+                        ].some((root) => within(actual, canonical(root)) ||
+                            within(canonical(root), actual)))
+                        throw new Error(`runtime-docker: protected write path ${path}`);
+                }
+            }
+            // The CLI build is mounted read-only; this puts the conductor's own CLI on PATH.
+            if (deps.bakersEntry) {
+                mkdirSync(join(runHome, 'bin'), { recursive: true });
+                writeFileSync(join(runHome, 'bin/bakers'), `#!/bin/sh\nexec node ${shellQuote(deps.bakersEntry)} "$@"\n`, { mode: 0o755 });
+            }
+            const env = { ...launch.env };
+            // Allowlist mode: the credential stays with the proxy sidecar.
+            if (!allowlist)
+                for (const k of credentials)
+                    env[k] = deps.env[k];
+            const { argv, env: runEnv } = dockerArgs({ ...launch, env }, { ...opts, image }, {
+                ...(runGitDir ? { runGitDir } : {}),
+                ...(launch.sharedObjects
+                    ? { sharedObjects: launch.sharedObjects }
+                    : {}),
+                runHome,
+                cliRoot: deps.cliRoot,
+                uid: process.getuid?.() ?? 1000,
+                gid: process.getgid?.() ?? 1000,
+            });
+            return { command: argv.map(shellQuote).join(' '), env: runEnv };
+        },
+        async cleanup(r) {
+            if (!plainName(r.uuid)) {
+                deps.logger.warn({ run: r.uuid }, 'runtime cleanup skipped: invalid run uuid');
+                return;
+            }
+            try {
+                const { stdout } = await deps.exec(docker, [
+                    'ps',
+                    '-aq',
+                    '--filter',
+                    `name=^bb-run-${r.uuid}$`,
+                    '--filter',
+                    `label=build.bakers.run=${r.uuid}`,
+                ]);
+                const ids = stdout.split('\n').filter(Boolean);
+                if (ids.length > 0)
+                    await deps.exec(docker, ['rm', '-f', ...ids]);
+            }
+            catch (err) {
+                deps.logger.warn({ run: r.uuid, err: String(err) }, 'runtime container cleanup failed');
+                return;
+            }
+            rmSync(runHomeOf(r.uuid), { recursive: true, force: true });
+        },
+    };
+    if (allowlist) {
+        runtime.toolsUrl = (hostUrl) => {
+            const u = new URL(hostUrl);
+            toolsPort = u.port;
+            const path = u.pathname === '/' ? '' : u.pathname;
+            return `http://${proxyName}:${PROXY_PORTS.tools}${path}${u.search}`;
+        };
+        runtime.toolServerHosts = async () => {
+            await ensureNetwork(opts.runNetwork, true);
+            await ensureNetwork(EGRESS_NETWORK, false);
+            const { stdout } = await deps.exec(docker, [
+                'network',
+                'inspect',
+                '-f',
+                '{{range .IPAM.Config}}{{.Gateway}}{{end}}',
+                EGRESS_NETWORK,
+            ]);
+            gateway = stdout.trim();
+            return [gateway];
+        };
+    }
+    return runtime;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,17 @@
+import type { RuntimePlugin } from '@bakers-build/conductor/contract';
+import { type RuntimeDockerOptions } from './backend.js';
+export * from './args.js';
+export { type BackendDeps, dockerRuntime, type RuntimeDockerOptions, } from './backend.js';
+/**
+ * This package's directory, and the CLI build a run mounts read-only: the
+ * common ancestor of this package and the conductor, widened to the outermost
+ * `node_modules` of an installed CLI so its hoisted dependencies come along.
+ */
+export declare function pluginPaths(): {
+    cliRoot: string;
+    packageDir: string;
+};
+export { cliRootOf } from '@bakers-build/core';
+/** The shipped image's tag: the package version plus a hash of `image/`, so any change rebuilds it. */
+export declare function imageVersion(packageDir: string, version: string): string;
+export declare function runtimeDocker(options?: RuntimeDockerOptions): RuntimePlugin;

package/dist/src/index.js

@@ -0,0 +1,56 @@
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cliRootOf } from '@bakers-build/core';
+import { dockerRuntime, realExec, shortHash, } from './backend.js';
+export * from './args.js';
+export { dockerRuntime, } from './backend.js';
+/** The nearest directory at or above `file` holding a package.json. */
+function packageOf(file) {
+    let dir = dirname(realpathSync(file));
+    while (!existsSync(join(dir, 'package.json')) && dirname(dir) !== dir)
+        dir = dirname(dir);
+    return dir;
+}
+/**
+ * This package's directory, and the CLI build a run mounts read-only: the
+ * common ancestor of this package and the conductor, widened to the outermost
+ * `node_modules` of an installed CLI so its hoisted dependencies come along.
+ */
+export function pluginPaths() {
+    const packageDir = packageOf(fileURLToPath(import.meta.url));
+    const conductor = packageOf(fileURLToPath(import.meta.resolve('@bakers-build/conductor/contract')));
+    return { cliRoot: cliRootOf(packageDir, conductor, homedir()), packageDir };
+}
+export { cliRootOf } from '@bakers-build/core';
+/** The shipped image's tag: the package version plus a hash of `image/`, so any change rebuilds it. */
+export function imageVersion(packageDir, version) {
+    const dir = join(packageDir, 'image');
+    const files = readdirSync(dir).sort();
+    return `${version}-${shortHash(files.map((f) => f + readFileSync(join(dir, f), 'utf8')).join('\0'))}`;
+}
+export function runtimeDocker(options = {}) {
+    return {
+        kind: 'runtime',
+        id: 'docker',
+        isolates: true,
+        requiredModules: [],
+        createRuntime: async (config, { logger }) => {
+            const { cliRoot, packageDir } = pluginPaths();
+            const { version } = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
+            return dockerRuntime(options, {
+                exec: realExec,
+                env: process.env,
+                logger,
+                cliRoot,
+                packageDir,
+                version: imageVersion(packageDir, version),
+                conductorKey: shortHash(config.config_path),
+                ...(process.argv[1]
+                    ? { bakersEntry: realpathSync(process.argv[1]) }
+                    : {}),
+            });
+        },
+    };
+}

package/dist/src/preset.d.ts

@@ -0,0 +1,3 @@
+import type { Preset } from '@bakers-build/conductor/contract';
+export declare const scopes: Preset['scopes'];
+export declare const runtimes: Preset['runtimes'];

package/dist/src/preset.js

@@ -0,0 +1,6 @@
+import { runtimeDocker } from './index.js';
+export const scopes = ['machine'];
+export const runtimes = (acc, options) => [
+    ...acc,
+    runtimeDocker(options),
+];

package/image/Dockerfile

@@ -0,0 +1,11 @@
+# One container per agent run (@bakers-build/addon-runtime-docker). The bakers CLI
+# is not baked in: each run mounts the host build read-only at its host path,
+# because the agent command names the CLI's scripts by that path.
+FROM node:22-slim
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends git ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+# The agent's own install (its `installCommand`); one image per agent.
+ARG AGENT_INSTALL
+RUN test -n "$AGENT_INSTALL" && sh -c "$AGENT_INSTALL"
+COPY proxy.mjs /opt/bb-runtime/proxy.mjs

package/image/proxy.mjs

@@ -0,0 +1,157 @@
+// The egress sidecar of @bakers-build/addon-runtime-docker's allowlist mode.
+// It sits on the internal run network and a normal bridge, and is the run's
+// only way out:
+//   :3128  HTTP CONNECT proxy, to allowed hosts only;
+//   :8081  the model API, with the real credential added here (the run holds a placeholder);
+//   :8082  a TCP relay to the conductor's tool server.
+import { createServer, request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { connect, createServer as createTcpServer } from 'node:net';
+
+/** Exact host, or `*.suffix` for any subdomain; case-insensitive. */
+export function allowed(host, patterns) {
+  const h = String(host).toLowerCase();
+  return patterns.some((p) => {
+    const q = String(p).toLowerCase();
+    return q.startsWith('*.') ? h.endsWith(q.slice(1)) : h === q;
+  });
+}
+
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => resolve(server.address().port));
+  });
+}
+
+function splitHostPort(target) {
+  const at = target.lastIndexOf(':');
+  return {
+    host: target.slice(0, at).replace(/^\[|\]$/g, ''),
+    port: Number(target.slice(at + 1)),
+  };
+}
+
+/**
+ * `auth` maps each credential name, preferred first, to the headers sent with
+ * it: `set` replaces a header (`{value}` is the secret), `append` adds a
+ * comma-separated value. `secrets` holds the credential values (the sidecar's env).
+ * @param {{ allow: string[], host?: string, apiTarget?: string,
+ *   auth?: Record<string, { set: Record<string, string>, append?: Record<string, string> }>,
+ *   secrets?: Record<string, string | undefined>, tools?: string,
+ *   ports?: { egress?: number, api?: number, tools?: number } }} o
+ */
+export async function startProxy(o) {
+  const bind = o.host ?? '0.0.0.0';
+  const servers = [];
+
+  const egress = createServer((_req, res) => {
+    // shortcut: plain-HTTP proxying is refused; allow it when an allowed host needs http://.
+    res.writeHead(403).end('only HTTPS (CONNECT) egress is allowed\n');
+  });
+  egress.on('connect', (req, socket, head) => {
+    // A client may reset any tunnel, refused ones included; unhandled, that kills every stream.
+    let upstream;
+    socket.on('error', () => upstream?.destroy());
+    const { host, port } = splitHostPort(req.url ?? '');
+    if (
+      !host ||
+      !Number.isInteger(port) ||
+      port < 1 ||
+      port > 65535 ||
+      !allowed(host, o.allow)
+    ) {
+      socket.end('HTTP/1.1 403 Forbidden\r\n\r\n');
+      return;
+    }
+    upstream = connect(port, host, () => {
+      socket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+      if (head.length) upstream.write(head);
+      upstream.pipe(socket).pipe(upstream);
+    });
+    upstream.on('error', () => socket.end('HTTP/1.1 502 Bad Gateway\r\n\r\n'));
+  });
+  servers.push(egress);
+  const ports = { egress: await listen(egress, o.ports?.egress ?? 0, bind) };
+
+  const auth = o.auth ?? {};
+  const name = Object.keys(auth).find((k) => o.secrets?.[k]);
+  if (o.apiTarget && name) {
+    const value = String(o.secrets[name]);
+    const { set, append = {} } = auth[name];
+    // The run's placeholder may sit in any credential header.
+    const strip = Object.values(auth).flatMap((a) =>
+      Object.keys(a.set).map((h) => h.toLowerCase()),
+    );
+    const target = new URL(o.apiTarget);
+    const send = target.protocol === 'https:' ? httpsRequest : httpRequest;
+    const api = createServer((req, res) => {
+      const headers = { ...req.headers, host: target.host };
+      for (const h of strip) delete headers[h];
+      for (const [h, v] of Object.entries(set))
+        headers[h.toLowerCase()] = v.replaceAll('{value}', value);
+      for (const [h, v] of Object.entries(append)) {
+        const k = h.toLowerCase();
+        const list = String(headers[k] ?? '')
+          .split(',')
+          .map((b) => b.trim())
+          .filter(Boolean);
+        if (!list.includes(v)) list.push(v);
+        headers[k] = list.join(',');
+      }
+      const up = send(
+        {
+          protocol: target.protocol,
+          hostname: target.hostname,
+          port: target.port,
+          method: req.method,
+          path: req.url,
+          headers,
+        },
+        (r) => {
+          res.writeHead(r.statusCode ?? 502, r.headers);
+          r.pipe(res);
+        },
+      );
+      up.on('error', () =>
+        res.headersSent ? res.destroy() : res.writeHead(502).end(),
+      );
+      req.pipe(up);
+    });
+    servers.push(api);
+    ports.api = await listen(api, o.ports?.api ?? 0, bind);
+  }
+
+  if (o.tools) {
+    const { host, port } = splitHostPort(o.tools);
+    const relay = createTcpServer((socket) => {
+      const up = connect(port, host);
+      socket.pipe(up).pipe(socket);
+      up.on('error', () => socket.destroy());
+      socket.on('error', () => up.destroy());
+    });
+    servers.push(relay);
+    ports.tools = await listen(relay, o.ports?.tools ?? 0, bind);
+  }
+
+  return {
+    ports,
+    close: () =>
+      Promise.all(
+        servers.map((s) => new Promise((r) => s.close(() => r()))),
+      ).then(() => {}),
+  };
+}
+
+// Run as the sidecar: configuration comes from the environment.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const p = await startProxy({
+    allow: (process.env.BB_ALLOW ?? '').split(',').filter(Boolean),
+    apiTarget: process.env.BB_API_TARGET,
+    auth: JSON.parse(process.env.BB_API_AUTH ?? '{}'),
+    secrets: process.env,
+    ...(process.env.BB_TOOLS ? { tools: process.env.BB_TOOLS } : {}),
+    ports: { egress: 3128, api: 8081, tools: 8082 },
+  });
+  console.log(`bb-runtime proxy listening ${JSON.stringify(p.ports)}`);
+}

package/options.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bakers.build/schema/addon-runtime-docker/options.schema.json",
+  "title": "@bakers-build/addon-runtime-docker options",
+  "description": "The runtime-docker entry's with.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "docker": {
+      "type": "string",
+      "minLength": 1,
+      "default": "docker",
+      "description": "The container CLI; podman also works."
+    },
+    "image": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Your image, used for every agent and never built. Default: the shipped image, built on first use."
+    },
+    "mounts": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^/" },
+      "default": [],
+      "description": "Extra absolute host paths, mounted read-only at the same path."
+    },
+    "network": {
+      "enum": ["host", "allowlist"],
+      "default": "host",
+      "description": "host shares the host network; allowlist routes the run through the conductor's proxy."
+    },
+    "allow": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "default": [],
+      "description": "Allowlist mode: hosts the run may reach, exact or *.suffix."
+    }
+  }
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@bakers-build/addon-runtime-docker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.1-next.6",
+  "description": "Start each agent run in its own Docker or Podman container.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./preset": "./dist/src/preset.js",
+    "./options.schema.json": "./options.schema.json"
+  },
+  "files": [
+    "dist/src",
+    "image",
+    "options.schema.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bakers-build/bakers-build.git",
+    "directory": "bakers-cli/addons/runtime-docker"
+  },
+  "peerDependencies": {
+    "@bakers-build/conductor": "^0.9.1-next.6",
+    "@bakers-build/core": "^0.9.1-next.6"
+  },
+  "bakersBuild": {
+    "commit": "e7d9921d51d5c045f29ca7e35d1e6a348e6ddf08",
+    "channel": "next"
+  }
+}