@zooid/runtime-docker 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zooid contributors
+
+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/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { ChildProcess } from 'node:child_process';
+import { AcpRuntime, AcpSpawnSpec } from '@zooid/core';
+
+interface DockerAcpRuntimeOptions {
+    /** Default image when the spec doesn't specify one. */
+    defaultImage?: string;
+    /** docker (default) or podman. */
+    engine?: 'docker' | 'podman';
+}
+/**
+ * DockerAcpRuntime spawns the ACP shim inside a container.
+ *
+ * argv shape: `<engine> run --rm -i [-w cwd] [-v ...] [-e ...] --entrypoint cmd image [args...]`
+ *
+ * The image comes from the spec (preferred) or the runtime's defaultImage.
+ * If neither is set, spawn() throws.
+ */
+declare class DockerAcpRuntime implements AcpRuntime {
+    private readonly opts;
+    private readonly engine;
+    constructor(opts?: DockerAcpRuntimeOptions);
+    buildArgv(spec: AcpSpawnSpec): string[];
+    spawn(spec: AcpSpawnSpec): ChildProcess;
+}
+
+export { DockerAcpRuntime, type DockerAcpRuntimeOptions };

package/dist/index.js

@@ -0,0 +1,41 @@
+// src/docker-acp.ts
+import { spawn } from "child_process";
+var DockerAcpRuntime = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+    this.engine = opts.engine ?? "docker";
+  }
+  engine;
+  buildArgv(spec) {
+    const image = spec.image ?? this.opts.defaultImage;
+    if (!image) {
+      throw new Error(
+        "DockerAcpRuntime: no image set (provide DockerAcpRuntimeOptions.defaultImage or AcpSpawnSpec.image)"
+      );
+    }
+    const argv = ["run", "--rm", "-i"];
+    if (spec.cwd) {
+      argv.push("-w", spec.cwd);
+    }
+    for (const m of spec.mounts ?? []) {
+      argv.push("-v", `${m.path}:${m.target}:${m.mode}`);
+    }
+    const envEntries = Object.entries(spec.env ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    for (const [k, v] of envEntries) {
+      argv.push("-e", `${k}=${v}`);
+    }
+    argv.push("--entrypoint", spec.command);
+    argv.push(image);
+    argv.push(...spec.args);
+    return argv;
+  }
+  spawn(spec) {
+    return spawn(this.engine, this.buildArgv(spec), {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  }
+};
+export {
+  DockerAcpRuntime
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/docker-acp.ts"],"sourcesContent":["import { spawn, type ChildProcess } from 'node:child_process'\nimport type { AcpRuntime, AcpSpawnSpec } from '@zooid/core'\n\nexport interface DockerAcpRuntimeOptions {\n  /** Default image when the spec doesn't specify one. */\n  defaultImage?: string\n  /** docker (default) or podman. */\n  engine?: 'docker' | 'podman'\n}\n\n/**\n * DockerAcpRuntime spawns the ACP shim inside a container.\n *\n * argv shape: `<engine> run --rm -i [-w cwd] [-v ...] [-e ...] --entrypoint cmd image [args...]`\n *\n * The image comes from the spec (preferred) or the runtime's defaultImage.\n * If neither is set, spawn() throws.\n */\nexport class DockerAcpRuntime implements AcpRuntime {\n  private readonly engine: 'docker' | 'podman'\n  constructor(private readonly opts: DockerAcpRuntimeOptions = {}) {\n    this.engine = opts.engine ?? 'docker'\n  }\n\n  buildArgv(spec: AcpSpawnSpec): string[] {\n    const image = spec.image ?? this.opts.defaultImage\n    if (!image) {\n      throw new Error(\n        'DockerAcpRuntime: no image set (provide DockerAcpRuntimeOptions.defaultImage or AcpSpawnSpec.image)',\n      )\n    }\n    const argv: string[] = ['run', '--rm', '-i']\n    if (spec.cwd) {\n      argv.push('-w', spec.cwd)\n    }\n    for (const m of spec.mounts ?? []) {\n      argv.push('-v', `${m.path}:${m.target}:${m.mode}`)\n    }\n    const envEntries = Object.entries(spec.env ?? {}).sort(([a], [b]) => a.localeCompare(b))\n    for (const [k, v] of envEntries) {\n      argv.push('-e', `${k}=${v}`)\n    }\n    argv.push('--entrypoint', spec.command)\n    argv.push(image)\n    argv.push(...spec.args)\n    return argv\n  }\n\n  spawn(spec: AcpSpawnSpec): ChildProcess {\n    return spawn(this.engine, this.buildArgv(spec), {\n      stdio: ['pipe', 'pipe', 'pipe'],\n    })\n  }\n}\n"],"mappings":";AAAA,SAAS,aAAgC;AAkBlC,IAAM,mBAAN,MAA6C;AAAA,EAElD,YAA6B,OAAgC,CAAC,GAAG;AAApC;AAC3B,SAAK,SAAS,KAAK,UAAU;AAAA,EAC/B;AAAA,EAHiB;AAAA,EAKjB,UAAU,MAA8B;AACtC,UAAM,QAAQ,KAAK,SAAS,KAAK,KAAK;AACtC,QAAI,CAAC,OAAO;AACV,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,UAAM,OAAiB,CAAC,OAAO,QAAQ,IAAI;AAC3C,QAAI,KAAK,KAAK;AACZ,WAAK,KAAK,MAAM,KAAK,GAAG;AAAA,IAC1B;AACA,eAAW,KAAK,KAAK,UAAU,CAAC,GAAG;AACjC,WAAK,KAAK,MAAM,GAAG,EAAE,IAAI,IAAI,EAAE,MAAM,IAAI,EAAE,IAAI,EAAE;AAAA,IACnD;AACA,UAAM,aAAa,OAAO,QAAQ,KAAK,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACvF,eAAW,CAAC,GAAG,CAAC,KAAK,YAAY;AAC/B,WAAK,KAAK,MAAM,GAAG,CAAC,IAAI,CAAC,EAAE;AAAA,IAC7B;AACA,SAAK,KAAK,gBAAgB,KAAK,OAAO;AACtC,SAAK,KAAK,KAAK;AACf,SAAK,KAAK,GAAG,KAAK,IAAI;AACtB,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,MAAkC;AACtC,WAAO,MAAM,KAAK,QAAQ,KAAK,UAAU,IAAI,GAAG;AAAA,MAC9C,OAAO,CAAC,QAAQ,QAAQ,MAAM;AAAA,IAChC,CAAC;AAAA,EACH;AACF;","names":[]}

package/docker/agent-base/Dockerfile

@@ -0,0 +1,10 @@
+FROM node:22-slim
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends git ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
+
+# No CMD — DockerAcpRuntime always sets the entrypoint to the resolved
+# ACP shim command at run time.

package/docker/agent-base/README.md

@@ -0,0 +1,25 @@
+# agent-base
+
+Container base image for `DockerAcpRuntime`. Contains node 22, git, and
+CA certificates — nothing else. Each agent's ACP shim is invoked via
+`docker run --entrypoint <shim-command>`, so the image itself does not
+hard-code which CLI it hosts.
+
+Build locally:
+
+```sh
+docker build -t ghcr.io/zooid-ai/agent-base:local \
+  -f packages/runtime-docker/docker/agent-base/Dockerfile \
+  packages/runtime-docker/docker/agent-base
+```
+
+Set as the runtime default in `zooid.yaml`:
+
+```yaml
+transport: http
+runtime: docker
+docker:
+  image: ghcr.io/zooid-ai/agent-base:local
+```
+
+Per-agent overrides are still possible via `agents.<name>.docker.image`.

package/docker/agent-claude-code/Dockerfile

@@ -0,0 +1,8 @@
+FROM ghcr.io/zooid-ai/agent-base:latest
+
+RUN npm install -g @agentclientprotocol/claude-agent-acp
+
+# No CMD — DockerAcpRuntime sets the entrypoint to the resolved ACP shim
+# command (e.g. `npx @agentclientprotocol/claude-agent-acp`). The npm install
+# above pre-populates the global cache so the first turn doesn't pay the
+# `npx -y` download tax.

package/docker/agent-codex/Dockerfile

@@ -0,0 +1,3 @@
+FROM ghcr.io/zooid-ai/agent-base:latest
+
+RUN npm install -g @zed-industries/codex-acp

package/docker/agent-opencode/Dockerfile

@@ -0,0 +1,3 @@
+FROM ghcr.io/zooid-ai/agent-base:latest
+
+RUN npm install -g opencode-ai

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@zooid/runtime-docker",
+  "version": "0.7.0",
+  "description": "Docker runtime for zooid. Spawns the agent CLI inside a container with a workspace mount and an env allowlist.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "docker",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@zooid/core": "^0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/docker-acp.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { EventEmitter } from 'node:events'
+import { Readable, Writable } from 'node:stream'
+
+const spawnMock = vi.fn()
+
+vi.mock('node:child_process', () => ({
+  spawn: spawnMock,
+}))
+
+const { DockerAcpRuntime } = await import('./docker-acp.js')
+
+class FakeChild extends EventEmitter {
+  stdout = new Readable({ read() {} })
+  stdin = new Writable({ write(_c, _e, cb) { cb() } })
+  stderr = new Readable({ read() {} })
+  pid = 1
+  kill = vi.fn(() => true)
+}
+
+function argvOf(call: number = 0): string[] {
+  return spawnMock.mock.calls[call][1] as string[]
+}
+
+describe('DockerAcpRuntime', () => {
+  beforeEach(() => {
+    spawnMock.mockReset()
+    spawnMock.mockReturnValue(new FakeChild())
+  })
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('uses docker run --rm -i base flags', () => {
+    const rt = new DockerAcpRuntime({ defaultImage: 'img:latest' })
+    rt.spawn({ command: 'cmd', args: [] })
+    expect(spawnMock.mock.calls[0][0]).toBe('docker')
+    const argv = argvOf()
+    expect(argv.slice(0, 3)).toEqual(['run', '--rm', '-i'])
+  })
+
+  it('engine: podman switches the binary from docker to podman', () => {
+    const rt = new DockerAcpRuntime({ defaultImage: 'img:latest', engine: 'podman' })
+    rt.spawn({ command: 'cmd', args: [] })
+    expect(spawnMock.mock.calls[0][0]).toBe('podman')
+  })
+
+  it('image: spec wins over runtime default', () => {
+    const rt = new DockerAcpRuntime({ defaultImage: 'default:1' })
+    rt.spawn({ command: 'cmd', args: [], image: 'override:2' })
+    const argv = argvOf()
+    expect(argv).toContain('override:2')
+    expect(argv).not.toContain('default:1')
+  })
+
+  it('throws if neither spec.image nor defaultImage set', () => {
+    const rt = new DockerAcpRuntime({})
+    expect(() => rt.spawn({ command: 'cmd', args: [] })).toThrow(/image/i)
+  })
+
+  it('emits -e KEY=value for each env entry', () => {
+    const rt = new DockerAcpRuntime({ defaultImage: 'img' })
+    rt.spawn({
+      command: 'cmd',
+      args: [],
+      env: { ANTHROPIC_API_KEY: 'sk', FOO: 'bar' },
+    })
+    const argv = argvOf()
+    expect(argv).toContain('-e')
+    expect(argv).toContain('ANTHROPIC_API_KEY=sk')
+    expect(argv).toContain('FOO=bar')
+  })
+
+  it('emits -v src:tgt:mode for each mount', () => {
+    const rt = new DockerAcpRuntime({ defaultImage: 'img' })
+    rt.spawn({
+      command: 'cmd',
+      args: [],
+      mounts: [
+        { path: '/host/a', target: '/c/a', mode: 'ro' },
+        { path: '/host/b', target: '/c/b', mode: 'rw' },
+      ],
+    })
+    const argv = argvOf()
+    expect(argv).toContain('/host/a:/c/a:ro')
+    expect(argv).toContain('/host/b:/c/b:rw')
+  })
+
+  it('emits -w <cwd> when cwd is set', () => {
+    const rt = new DockerAcpRuntime({ defaultImage: 'img' })
+    rt.spawn({ command: 'cmd', args: [], cwd: '/workspace' })
+    const argv = argvOf()
+    const wIdx = argv.indexOf('-w')
+    expect(wIdx).toBeGreaterThan(-1)
+    expect(argv[wIdx + 1]).toBe('/workspace')
+  })
+
+  it('args appear after the image (command is set via --entrypoint)', () => {
+    const rt = new DockerAcpRuntime({ defaultImage: 'img' })
+    rt.spawn({ command: 'opencode', args: ['acp', '--flag'] })
+    const argv = argvOf()
+    const imgIdx = argv.indexOf('img')
+    expect(imgIdx).toBeGreaterThan(-1)
+    expect(argv.slice(imgIdx + 1)).toEqual(['acp', '--flag'])
+  })
+
+  it('uses --entrypoint to override image entrypoint with spec command', () => {
+    const rt = new DockerAcpRuntime({ defaultImage: 'img' })
+    rt.spawn({ command: 'opencode', args: ['acp'] })
+    const argv = argvOf()
+    const epIdx = argv.indexOf('--entrypoint')
+    expect(epIdx).toBeGreaterThan(-1)
+    expect(argv[epIdx + 1]).toBe('opencode')
+  })
+
+  it('returns the ChildProcess from spawn', () => {
+    const child = new FakeChild()
+    spawnMock.mockReturnValue(child)
+    const rt = new DockerAcpRuntime({ defaultImage: 'img' })
+    const result = rt.spawn({ command: 'cmd', args: [] })
+    expect(result).toBe(child)
+  })
+})

package/src/docker-acp.ts

@@ -0,0 +1,54 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import type { AcpRuntime, AcpSpawnSpec } from '@zooid/core'
+
+export interface DockerAcpRuntimeOptions {
+  /** Default image when the spec doesn't specify one. */
+  defaultImage?: string
+  /** docker (default) or podman. */
+  engine?: 'docker' | 'podman'
+}
+
+/**
+ * DockerAcpRuntime spawns the ACP shim inside a container.
+ *
+ * argv shape: `<engine> run --rm -i [-w cwd] [-v ...] [-e ...] --entrypoint cmd image [args...]`
+ *
+ * The image comes from the spec (preferred) or the runtime's defaultImage.
+ * If neither is set, spawn() throws.
+ */
+export class DockerAcpRuntime implements AcpRuntime {
+  private readonly engine: 'docker' | 'podman'
+  constructor(private readonly opts: DockerAcpRuntimeOptions = {}) {
+    this.engine = opts.engine ?? 'docker'
+  }
+
+  buildArgv(spec: AcpSpawnSpec): string[] {
+    const image = spec.image ?? this.opts.defaultImage
+    if (!image) {
+      throw new Error(
+        'DockerAcpRuntime: no image set (provide DockerAcpRuntimeOptions.defaultImage or AcpSpawnSpec.image)',
+      )
+    }
+    const argv: string[] = ['run', '--rm', '-i']
+    if (spec.cwd) {
+      argv.push('-w', spec.cwd)
+    }
+    for (const m of spec.mounts ?? []) {
+      argv.push('-v', `${m.path}:${m.target}:${m.mode}`)
+    }
+    const envEntries = Object.entries(spec.env ?? {}).sort(([a], [b]) => a.localeCompare(b))
+    for (const [k, v] of envEntries) {
+      argv.push('-e', `${k}=${v}`)
+    }
+    argv.push('--entrypoint', spec.command)
+    argv.push(image)
+    argv.push(...spec.args)
+    return argv
+  }
+
+  spawn(spec: AcpSpawnSpec): ChildProcess {
+    return spawn(this.engine, this.buildArgv(spec), {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export {
+  DockerAcpRuntime,
+  type DockerAcpRuntimeOptions,
+} from './docker-acp.js'