@vellumai/cli 0.7.1 → 0.7.2

package/src/lib/docker-statefulset.ts

@@ -0,0 +1,381 @@
+/**
+ * Declarative StatefulSet spec for the Docker service group.
+ *
+ * Mirrors the schema of the platform's `stateful_template.yaml` (vembda).
+ * Container names, volume names, and env var names are kept in sync with
+ * the K8s template so the two topologies are auditable side-by-side.
+ *
+ * This file is self-contained — it does not import from `docker.ts` to
+ * avoid a circular dependency. Constants are inlined from their definitions
+ * in `docker.ts` and must be kept in sync if those change.
+ */
+
+import { existsSync } from "fs";
+
+import { PROVIDER_ENV_VAR_NAMES } from "../shared/provider-env-vars.js";
+
+// ---------------------------------------------------------------------------
+// Constants (mirrored from docker.ts — keep in sync)
+// ---------------------------------------------------------------------------
+
+const GATEWAY_INTERNAL_PORT = 7830;
+const ASSISTANT_INTERNAL_PORT = 7821;
+const AVATAR_DEVICE_ENV_VAR = "VELLUM_AVATAR_DEVICE";
+
+/** Logical service name used throughout the CLI. */
+export type ServiceName = "assistant" | "gateway" | "credential-executor";
+
+/**
+ /**
+  * The four fields from `dockerResourceNames()` that the builder actually uses.
+  * Container/network names come from here; volume names are generated by the
+  * `volumeClaimTemplates` in the spec. `ReturnType<typeof dockerResourceNames>`
+  * structurally satisfies this interface (it has all these fields plus more).
+  */
+ export interface DockerResourceNames {
+   assistantContainer: string;
+   cesContainer: string;
+   gatewayContainer: string;
+   network: string;
+ }
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A static env var whose value is known at spec-definition time. */
+interface StaticEnv {
+  kind: "static";
+  name: string;
+  value: string;
+}
+
+/**
+ * An env var whose value comes from the opts object passed to
+ * `buildServiceRunArgs` at container-start time.
+ */
+interface SecretEnv {
+  kind: "secret";
+  name: string;
+  /** Key in `DockerRunSecrets`. */
+  secret: keyof DockerRunSecrets;
+}
+
+/**
+ * An env var conditionally forwarded from the host process environment.
+ * Only emitted when `process.env[hostVar]` is set.
+ * Defaults to `name` for `hostVar` when omitted.
+ */
+interface HostEnv {
+  kind: "host";
+  name: string;
+  hostVar?: string;
+}
+
+type EnvEntry = StaticEnv | SecretEnv | HostEnv;
+
+interface VolumeMount {
+  /** Logical volume name — maps to a Docker volume via `DockerVolumeClaimTemplate`. */
+  volumeName: string;
+  mountPath: string;
+  readOnly?: boolean;
+}
+
+interface PortSpec {
+  containerPort: number;
+  /**
+   * Host-side port. Literal string = use as-is. `"{{ gatewayPort }}"` is
+   * a sentinel replaced with the instance-specific gateway port at build time.
+   */
+  hostPort?: string;
+  description?: string;
+}
+
+export interface DockerContainerSpec {
+  /** K8s-style container name (matches `stateful_template.yaml`). */
+  name: string;
+  /** Internal CLI `ServiceName` key used by `SERVICE_START_ORDER`. */
+  internalName: ServiceName;
+  /**
+   * Network mode:
+   * - "bridge": owns the network (assistant only — gateway port published here).
+   * - "container": share the assistant container's network namespace.
+   */
+  network: "bridge" | "container";
+  ports?: PortSpec[];
+  env: EnvEntry[];
+  volumeMounts: VolumeMount[];
+}
+
+export interface DockerVolumeClaimTemplate {
+  name: string;
+  dockerVolume: (instanceName: string) => string;
+}
+
+export interface DockerStatefulSetSpec {
+  containers: DockerContainerSpec[];
+  startOrder: ServiceName[];
+  volumeClaimTemplates: DockerVolumeClaimTemplate[];
+  readiness: {
+    endpoint: string;
+    timeoutMs: number;
+    intervalMs: number;
+  };
+}
+
+/** Secrets injected at container-start time (from hatch / upgrade opts). */
+export interface DockerRunSecrets {
+  signingKey?: string;
+  bootstrapSecret?: string;
+  cesServiceToken?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Spec
+// ---------------------------------------------------------------------------
+
+export const DOCKER_STATEFUL_SET_SPEC: DockerStatefulSetSpec = {
+  startOrder: ["assistant", "gateway", "credential-executor"],
+
+  readiness: {
+    endpoint: "/readyz",
+    timeoutMs: 180_000,
+    intervalMs: 1_000,
+  },
+
+  volumeClaimTemplates: [
+    { name: "assistant-workspace",  dockerVolume: (n) => `${n}-workspace` },
+    { name: "ces-bootstrap-socket", dockerVolume: (n) => `${n}-socket` },
+    { name: "assistant-ipc-socket", dockerVolume: (n) => `${n}-assistant-ipc` },
+    { name: "gateway-ipc-socket",   dockerVolume: (n) => `${n}-gateway-ipc` },
+    { name: "gateway-security",     dockerVolume: (n) => `${n}-gateway-sec` },
+    { name: "ces-security",         dockerVolume: (n) => `${n}-ces-sec` },
+  ],
+
+  containers: [
+    {
+      name: "assistant-container",
+      internalName: "assistant",
+      network: "bridge",
+      ports: [
+        {
+          containerPort: GATEWAY_INTERNAL_PORT,
+          hostPort: "{{ gatewayPort }}",
+          description: "Gateway reverse-proxy (published to host)",
+        },
+        {
+          containerPort: ASSISTANT_INTERNAL_PORT,
+          hostPort: `${ASSISTANT_INTERNAL_PORT}`,
+          description: "Assistant HTTP API",
+        },
+      ],
+      env: [
+        { kind: "static", name: "IS_CONTAINERIZED",         value: "true" },
+        { kind: "static", name: "DEBUG_STDOUT_LOGS",         value: "1" },
+        { kind: "static", name: "VELLUM_CLOUD",              value: "docker" },
+        { kind: "static", name: "RUNTIME_HTTP_HOST",         value: "0.0.0.0" },
+        { kind: "static", name: "VELLUM_WORKSPACE_DIR",      value: "/workspace" },
+        { kind: "static", name: "VELLUM_BACKUP_DIR",         value: "/workspace/.backups" },
+        { kind: "static", name: "VELLUM_BACKUP_KEY_PATH",    value: "/workspace/.backup.key" },
+        { kind: "static", name: "CES_CREDENTIAL_URL",        value: "http://localhost:8090" },
+        { kind: "static", name: "GATEWAY_IPC_SOCKET_DIR",    value: "/run/gateway-ipc" },
+        { kind: "static", name: "ASSISTANT_IPC_SOCKET_DIR",  value: "/run/assistant-ipc" },
+        { kind: "secret", name: "CES_SERVICE_TOKEN",         secret: "cesServiceToken" },
+        { kind: "secret", name: "ACTOR_TOKEN_SIGNING_KEY",   secret: "signingKey" },
+        { kind: "secret", name: "GUARDIAN_BOOTSTRAP_SECRET", secret: "bootstrapSecret" },
+        // Provider API keys — forwarded from host if set
+        ...Object.values(PROVIDER_ENV_VAR_NAMES).map(
+          (v): HostEnv => ({ kind: "host", name: v }),
+        ),
+        { kind: "host", name: "VELLUM_ENVIRONMENT" },
+        { kind: "host", name: "VELLUM_PLATFORM_URL" },
+      ],
+      volumeMounts: [
+        { volumeName: "assistant-workspace",  mountPath: "/workspace" },
+        { volumeName: "ces-bootstrap-socket", mountPath: "/run/ces-bootstrap" },
+        { volumeName: "assistant-ipc-socket", mountPath: "/run/assistant-ipc" },
+        { volumeName: "gateway-ipc-socket",   mountPath: "/run/gateway-ipc" },
+      ],
+    },
+
+    {
+      name: "gateway-sidecar",
+      internalName: "gateway",
+      network: "container",
+      env: [
+        { kind: "static", name: "VELLUM_WORKSPACE_DIR",      value: "/workspace" },
+        { kind: "static", name: "GATEWAY_SECURITY_DIR",      value: "/gateway-security" },
+        { kind: "static", name: "ASSISTANT_HOST",            value: "localhost" },
+        { kind: "static", name: "CES_CREDENTIAL_URL",        value: "http://localhost:8090" },
+        { kind: "static", name: "GATEWAY_IPC_SOCKET_DIR",    value: "/run/gateway-ipc" },
+        { kind: "static", name: "ASSISTANT_IPC_SOCKET_DIR",  value: "/run/assistant-ipc" },
+        { kind: "static", name: "GATEWAY_PORT",              value: `${GATEWAY_INTERNAL_PORT}` },
+        { kind: "static", name: "RUNTIME_HTTP_PORT",         value: `${ASSISTANT_INTERNAL_PORT}` },
+        { kind: "secret", name: "CES_SERVICE_TOKEN",         secret: "cesServiceToken" },
+        { kind: "secret", name: "ACTOR_TOKEN_SIGNING_KEY",   secret: "signingKey" },
+        { kind: "secret", name: "GUARDIAN_BOOTSTRAP_SECRET", secret: "bootstrapSecret" },
+        { kind: "host",   name: "VELLUM_ENVIRONMENT" },
+        { kind: "host",   name: "VELLUM_PLATFORM_URL" },
+        { kind: "host",   name: "VELAY_BASE_URL" },
+      ],
+      volumeMounts: [
+        { volumeName: "assistant-workspace",  mountPath: "/workspace" },
+        { volumeName: "gateway-security",     mountPath: "/gateway-security" },
+        { volumeName: "assistant-ipc-socket", mountPath: "/run/assistant-ipc" },
+        { volumeName: "gateway-ipc-socket",   mountPath: "/run/gateway-ipc" },
+      ],
+    },
+
+    {
+      name: "credential-executor-sidecar",
+      internalName: "credential-executor",
+      network: "container",
+      env: [
+        { kind: "static", name: "CES_MODE",                  value: "managed" },
+        { kind: "static", name: "VELLUM_WORKSPACE_DIR",      value: "/workspace" },
+        { kind: "static", name: "CES_BOOTSTRAP_SOCKET_DIR",  value: "/run/ces-bootstrap" },
+        { kind: "static", name: "CREDENTIAL_SECURITY_DIR",   value: "/ces-security" },
+        { kind: "secret", name: "CES_SERVICE_TOKEN",         secret: "cesServiceToken" },
+      ],
+      volumeMounts: [
+        { volumeName: "assistant-workspace",  mountPath: "/workspace", readOnly: true },
+        { volumeName: "ces-bootstrap-socket", mountPath: "/run/ces-bootstrap" },
+        { volumeName: "ces-security",         mountPath: "/ces-security" },
+      ],
+    },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+export interface BuildServiceRunArgsOpts extends DockerRunSecrets {
+  gatewayPort: number;
+  imageTags: Record<ServiceName, string>;
+  instanceName: string;
+  res: DockerResourceNames;
+  extraAssistantEnv?: Record<string, string>;
+  defaultWorkspaceConfigPath?: string;
+  /** Avatar device path, if available. Injected by `docker.ts` after resolving. */
+  avatarDevicePath?: string;
+}
+
+function resolveVolume(
+  spec: DockerStatefulSetSpec,
+  instanceName: string,
+  volumeName: string,
+): string {
+  const claim = spec.volumeClaimTemplates.find((v) => v.name === volumeName);
+  if (!claim) throw new Error(`docker-statefulset: unknown volume "${volumeName}"`);
+  return claim.dockerVolume(instanceName);
+}
+
+/**
+ * Build `docker run` argument arrays for each container in the StatefulSet.
+ * Returns `Record<ServiceName, () => string[]>` — callers evaluate lazily.
+ */
+export function buildServiceRunArgs(
+  opts: BuildServiceRunArgsOpts,
+  spec = DOCKER_STATEFUL_SET_SPEC,
+): Record<ServiceName, () => string[]> {
+  const {
+    gatewayPort,
+    imageTags,
+    instanceName,
+    res,
+    extraAssistantEnv,
+    defaultWorkspaceConfigPath,
+    avatarDevicePath,
+  } = opts;
+
+  const result = {} as Record<ServiceName, () => string[]>;
+
+  for (const container of spec.containers) {
+    const svc = container.internalName;
+
+    result[svc] = () => {
+      const args: string[] = ["run", "--init", "-d"];
+
+      // Container name
+      const containerName =
+        svc === "assistant"
+          ? res.assistantContainer
+          : svc === "gateway"
+            ? res.gatewayContainer
+            : res.cesContainer;
+      args.push("--name", containerName);
+
+      // Network
+      if (container.network === "bridge") {
+        args.push(`--network=${res.network}`);
+        for (const port of container.ports ?? []) {
+          const hostSide =
+            port.hostPort === "{{ gatewayPort }}"
+              ? `${gatewayPort}`
+              : port.hostPort;
+          if (hostSide !== undefined) {
+            args.push("-p", `${hostSide}:${port.containerPort}`);
+          }
+        }
+      } else {
+        args.push(`--network=container:${res.assistantContainer}`);
+      }
+
+      // Volume mounts
+      for (const mount of container.volumeMounts) {
+        const vol = resolveVolume(spec, instanceName, mount.volumeName);
+        args.push("-v", mount.readOnly ? `${vol}:${mount.mountPath}:ro` : `${vol}:${mount.mountPath}`);
+      }
+
+      // Env vars from spec
+      for (const entry of container.env) {
+        if (entry.kind === "static") {
+          args.push("-e", `${entry.name}=${entry.value}`);
+        } else if (entry.kind === "secret") {
+          const val = opts[entry.secret];
+          if (val) args.push("-e", `${entry.name}=${val}`);
+        } else {
+          const hostVar = entry.hostVar ?? entry.name;
+          const val = process.env[hostVar];
+          if (val) args.push("-e", `${entry.name}=${val}`);
+        }
+      }
+
+      // Assistant-only computed / optional additions
+      if (svc === "assistant") {
+        args.push(
+          "-e", `VELLUM_ASSISTANT_NAME=${instanceName}`,
+          "-e", `GATEWAY_INTERNAL_URL=http://localhost:${GATEWAY_INTERNAL_PORT}`,
+        );
+
+        if (defaultWorkspaceConfigPath) {
+          const cPath = `/tmp/vellum-default-workspace-config-${Date.now()}.json`;
+          args.push(
+            "-v", `${defaultWorkspaceConfigPath}:${cPath}:ro`,
+            "-e", `VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH=${cPath}`,
+          );
+        }
+
+        if (extraAssistantEnv) {
+          for (const [k, v] of Object.entries(extraAssistantEnv)) {
+            args.push("-e", `${k}=${v}`);
+          }
+        }
+
+        if (avatarDevicePath && existsSync(avatarDevicePath)) {
+          args.push(
+            "--device", `${avatarDevicePath}:${avatarDevicePath}`,
+            "-e", `${AVATAR_DEVICE_ENV_VAR}=${avatarDevicePath}`,
+          );
+        }
+      }
+
+      // Image is always last
+      args.push(imageTags[svc]);
+      return args;
+    };
+  }
+
+  return result;
+}

package/src/lib/docker.ts

@@ -13,7 +13,7 @@ import {
 } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
 import { writeInitialConfig } from "./config-utils";
-import { PROVIDER_ENV_VAR_NAMES } from "../shared/provider-env-vars.js";
+import { buildServiceRunArgs } from "./docker-statefulset.js";
 import type { Species } from "./constants";
 import { getDefaultPorts } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
@@ -363,7 +363,6 @@ export function dockerResourceNames(instanceName: string) {
     assistantIpcVolume: `${instanceName}-assistant-ipc`,
     cesContainer: `${instanceName}-credential-executor`,
     cesSecurityVolume: `${instanceName}-ces-sec`,
-    dockerdDataVolume: `${instanceName}-dockerd-data`,
     gatewayContainer: `${instanceName}-gateway`,
     gatewayIpcVolume: `${instanceName}-gateway-ipc`,
     gatewaySecurityVolume: `${instanceName}-gateway-sec`,
@@ -426,7 +425,6 @@ export async function retireDocker(name: string): Promise<void> {
     res.workspaceVolume,
     res.cesSecurityVolume,
     res.gatewaySecurityVolume,
-    res.dockerdDataVolume,
   ]) {
     try {
       await exec("docker", ["volume", "rm", vol]);
@@ -563,10 +561,11 @@ async function buildAllImages(
 }
 
 /**
- * Returns a function that builds the `docker run` arguments for a given
- * service. All three containers share a network namespace via
- * `--network=container:` so inter-service traffic is over localhost,
- * matching the platform's Kubernetes pod topology.
+ * Build `docker run` argument arrays for each service in the StatefulSet.
+ *
+ * Delegates to `buildServiceRunArgs` from `docker-statefulset.ts`, which owns
+ * the declarative container / volume / env spec. Signature preserved for
+ * backward compatibility with callers throughout this file.
  */
 export function serviceDockerRunArgs(opts: {
   signingKey?: string;
@@ -579,235 +578,8 @@ export function serviceDockerRunArgs(opts: {
   instanceName: string;
   res: ReturnType<typeof dockerResourceNames>;
 }): Record<ServiceName, () => string[]> {
-  const {
-    cesServiceToken,
-    defaultWorkspaceConfigPath,
-    extraAssistantEnv,
-    gatewayPort,
-    imageTags,
-    instanceName,
-    res,
-  } = opts;
-  return {
-    assistant: () => {
-      // Run the assistant container in Docker-in-Docker (DinD) mode: the
-      // container runs its own `dockerd` so the Meet subsystem can spawn
-      // sibling meet-bot containers without needing access to the host's
-      // Docker engine. This requires:
-      //   - `CAP_SYS_ADMIN` + `CAP_NET_ADMIN` so the inner dockerd can
-      //     configure cgroups, overlay mounts, network namespaces, and
-      //     iptables. We deliberately avoid `--privileged` (which grants the
-      //     full host capability set and access to every host device node)
-      //     to shrink the escape surface from any code running inside the
-      //     assistant container. See the "Security tradeoff for Docker mode"
-      //     note in AGENTS.md.
-      //   - `seccomp=unconfined` + `apparmor=unconfined` because Docker's
-      //     default seccomp profile blocks syscalls dockerd needs (e.g.
-      //     certain clone/unshare and pivot_root flags) and the default
-      //     AppArmor profile on Debian/Ubuntu hosts denies the mount
-      //     operations dockerd performs while launching bot containers. On
-      //     hosts where these LSMs are inactive, the options are no-ops.
-      //   - A dedicated named volume mounted at `/var/lib/docker` so the
-      //     inner Docker image cache and container state survive restarts of
-      //     the assistant container.
-      // The host's `/var/run/docker.sock` is intentionally NOT mounted — all
-      // Meet-bot spawning happens against the inner dockerd.
-      const args: string[] = [
-        "run",
-        "--init",
-        "-d",
-        "--cap-add",
-        "SYS_ADMIN",
-        "--cap-add",
-        "NET_ADMIN",
-        "--security-opt",
-        "seccomp=unconfined",
-        "--security-opt",
-        "apparmor=unconfined",
-        "--name",
-        res.assistantContainer,
-        `--network=${res.network}`,
-        "-p",
-        `${gatewayPort}:${GATEWAY_INTERNAL_PORT}`,
-        // Published so the Meet subsystem's sibling bot containers can reach
-        // the daemon's internal HTTP API at host.docker.internal:<port>.
-        //
-        // Published on all host interfaces (no `127.0.0.1:` prefix) because on
-        // vanilla Linux Docker, `host.docker.internal:host-gateway` resolves
-        // to the Docker bridge gateway IP (e.g. 172.17.0.1), not loopback.
-        // Packets from sibling containers arrive at the host's bridge
-        // interface, and an iptables DNAT rule keyed on dest=127.0.0.1 would
-        // not match — causing connection refused. Docker Desktop (macOS/
-        // Windows) still works because its VM proxy forwards to the same
-        // published port regardless of the binding address.
-        //
-        // Security tradeoff: the daemon HTTP API is now reachable from the
-        // host's LAN (any device that can hit the host IP on this port).
-        // This matches the gateway port's existing posture and is acceptable
-        // for single-user self-hosted Docker mode per the Phase 1.8 security
-        // note. Managed/multi-tenant deployments are out of scope and would
-        // require a different design.
-        "-p",
-        `${ASSISTANT_INTERNAL_PORT}:${ASSISTANT_INTERNAL_PORT}`,
-        "-v",
-        `${res.workspaceVolume}:/workspace`,
-        "-v",
-        `${res.socketVolume}:/run/ces-bootstrap`,
-        "-v",
-        `${res.assistantIpcVolume}:/run/assistant-ipc`,
-        "-v",
-        `${res.gatewayIpcVolume}:/run/gateway-ipc`,
-        "-v",
-        `${res.dockerdDataVolume}:/var/lib/docker`,
-        "-e",
-        "IS_CONTAINERIZED=true",
-        "-e",
-        "DEBUG_STDOUT_LOGS=1",
-        "-e",
-        `VELLUM_ASSISTANT_NAME=${instanceName}`,
-        "-e",
-        "VELLUM_CLOUD=docker",
-        "-e",
-        "RUNTIME_HTTP_HOST=0.0.0.0",
-        "-e",
-        "VELLUM_WORKSPACE_DIR=/workspace",
-        "-e",
-        "VELLUM_BACKUP_DIR=/workspace/.backups",
-        "-e",
-        "VELLUM_BACKUP_KEY_PATH=/workspace/.backup.key",
-        "-e",
-        "CES_CREDENTIAL_URL=http://localhost:8090",
-        "-e",
-        `GATEWAY_INTERNAL_URL=http://localhost:${GATEWAY_INTERNAL_PORT}`,
-        "-e",
-        "GATEWAY_IPC_SOCKET_DIR=/run/gateway-ipc",
-        "-e",
-        "ASSISTANT_IPC_SOCKET_DIR=/run/assistant-ipc",
-      ];
-      if (defaultWorkspaceConfigPath) {
-        const containerPath = `/tmp/vellum-default-workspace-config-${Date.now()}.json`;
-        args.push(
-          "-v",
-          `${defaultWorkspaceConfigPath}:${containerPath}:ro`,
-          "-e",
-          `VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH=${containerPath}`,
-        );
-      }
-      if (cesServiceToken) {
-        args.push("-e", `CES_SERVICE_TOKEN=${cesServiceToken}`);
-      }
-      if (opts.signingKey) {
-        args.push("-e", `ACTOR_TOKEN_SIGNING_KEY=${opts.signingKey}`);
-      }
-      if (opts.bootstrapSecret) {
-        // Mirror the secret into the assistant container so the runtime's
-        // guardian-bootstrap handler can validate the x-bootstrap-secret
-        // header forwarded by the gateway. Without this, the published
-        // runtime port would expose an unauthenticated token-minting
-        // endpoint reachable from the host bypassing the gateway's gate.
-        args.push("-e", `GUARDIAN_BOOTSTRAP_SECRET=${opts.bootstrapSecret}`);
-      }
-      for (const envVar of [
-        ...Object.values(PROVIDER_ENV_VAR_NAMES),
-        "VELLUM_ENVIRONMENT",
-        "VELLUM_PLATFORM_URL",
-      ]) {
-        if (process.env[envVar]) {
-          args.push("-e", `${envVar}=${process.env[envVar]}`);
-        }
-      }
-      if (extraAssistantEnv) {
-        for (const [key, value] of Object.entries(extraAssistantEnv)) {
-          args.push("-e", `${key}=${value}`);
-        }
-      }
-      const avatarDevice = resolveAvatarDevicePath();
-      if (existsSync(avatarDevice)) {
-        args.push(
-          "--device",
-          `${avatarDevice}:${avatarDevice}`,
-          "-e",
-          `${AVATAR_DEVICE_ENV_VAR}=${avatarDevice}`,
-        );
-      }
-      args.push(imageTags.assistant);
-      return args;
-    },
-    gateway: () => [
-      "run",
-      "--init",
-      "-d",
-      "--name",
-      res.gatewayContainer,
-      `--network=container:${res.assistantContainer}`,
-      "-v",
-      `${res.workspaceVolume}:/workspace`,
-      "-v",
-      `${res.gatewaySecurityVolume}:/gateway-security`,
-      "-v",
-      `${res.assistantIpcVolume}:/run/assistant-ipc`,
-      "-v",
-      `${res.gatewayIpcVolume}:/run/gateway-ipc`,
-      "-e",
-      "VELLUM_WORKSPACE_DIR=/workspace",
-      "-e",
-      "GATEWAY_SECURITY_DIR=/gateway-security",
-      "-e",
-      `GATEWAY_PORT=${GATEWAY_INTERNAL_PORT}`,
-      "-e",
-      "ASSISTANT_HOST=localhost",
-      "-e",
-      `RUNTIME_HTTP_PORT=${ASSISTANT_INTERNAL_PORT}`,
-      "-e",
-      "CES_CREDENTIAL_URL=http://localhost:8090",
-      "-e",
-      "GATEWAY_IPC_SOCKET_DIR=/run/gateway-ipc",
-      "-e",
-      "ASSISTANT_IPC_SOCKET_DIR=/run/assistant-ipc",
-      ...(cesServiceToken
-        ? ["-e", `CES_SERVICE_TOKEN=${cesServiceToken}`]
-        : []),
-      ...(opts.signingKey
-        ? ["-e", `ACTOR_TOKEN_SIGNING_KEY=${opts.signingKey}`]
-        : []),
-      ...(opts.bootstrapSecret
-        ? ["-e", `GUARDIAN_BOOTSTRAP_SECRET=${opts.bootstrapSecret}`]
-        : []),
-      ...(process.env.VELLUM_ENVIRONMENT
-        ? ["-e", `VELLUM_ENVIRONMENT=${process.env.VELLUM_ENVIRONMENT}`]
-        : []),
-      ...(process.env.VELLUM_PLATFORM_URL
-        ? ["-e", `VELLUM_PLATFORM_URL=${process.env.VELLUM_PLATFORM_URL}`]
-        : []),
-      imageTags.gateway,
-    ],
-    "credential-executor": () => [
-      "run",
-      "--init",
-      "-d",
-      "--name",
-      res.cesContainer,
-      `--network=container:${res.assistantContainer}`,
-      "-v",
-      `${res.socketVolume}:/run/ces-bootstrap`,
-      "-v",
-      `${res.workspaceVolume}:/workspace:ro`,
-      "-v",
-      `${res.cesSecurityVolume}:/ces-security`,
-      "-e",
-      "CES_MODE=managed",
-      "-e",
-      "VELLUM_WORKSPACE_DIR=/workspace",
-      "-e",
-      "CES_BOOTSTRAP_SOCKET_DIR=/run/ces-bootstrap",
-      "-e",
-      "CREDENTIAL_SECURITY_DIR=/ces-security",
-      ...(cesServiceToken
-        ? ["-e", `CES_SERVICE_TOKEN=${cesServiceToken}`]
-        : []),
-      imageTags["credential-executor"],
-    ],
-  };
+  const avatarDevice = resolveAvatarDevicePath();
+  return buildServiceRunArgs({ ...opts, avatarDevicePath: avatarDevice });
 }
 
 /** The order in which services must be started. */
@@ -832,16 +604,6 @@ export async function startContainers(
   },
   log: (msg: string) => void,
 ): Promise<void> {
-  // Ensure the inner dockerd's data volume exists before mounting it.
-  // For instances hatched on Phase 1.10+, this is created in hatchDocker and
-  // is a no-op here. For instances that pre-date Phase 1.10 (DinD) and are
-  // upgrading in place, Docker would otherwise auto-create the volume on
-  // first `-v` mount without our standard ownership/labeling. Creating it
-  // explicitly keeps volume provenance consistent across fresh and upgraded
-  // instances. `docker volume create` is idempotent for an existing volume
-  // of the same name, so this is safe to run on every start.
-  await exec("docker", ["volume", "create", opts.res.dockerdDataVolume]);
-
   const runArgs = serviceDockerRunArgs(opts);
   for (const service of SERVICE_START_ORDER) {
     log(`🚀 Starting ${service} container...`);
@@ -1254,7 +1016,6 @@ export async function hatchDocker(
     await exec("docker", ["volume", "create", res.workspaceVolume]);
     await exec("docker", ["volume", "create", res.cesSecurityVolume]);
     await exec("docker", ["volume", "create", res.gatewaySecurityVolume]);
-    await exec("docker", ["volume", "create", res.dockerdDataVolume]);
 
     // Set volume ownership so non-root containers (UID 1001) can write.
     await exec("docker", [