V48 (impl-only): Pipeline VCR appliance image and host image mode

Add @bitcode/pipeline-image (materialize runners, Dockerfile, VCR CI workflow)
and teach buildAssetPackSandboxHostPlan to use Sandbox.create({ image }) when
BITCODE_PIPELINE_SANDBOX_IMAGE is set: slim writeFiles (manifest only), image
entry command, no in-box monorepo install. Deposit/read synthesize share the
same path. Verified pipeline-hosts/generic-hosts tests, uapi tsc/lint, materialize.

Author: geraldarthurdavis

.github/workflows/pipeline-image.yml

@@ -0,0 +1,88 @@
+name: Pipeline Image
+
+# Build (and optionally push) the VCR pipeline appliance used by sandbox deposit/read.
+on:
+  push:
+    branches:
+      - version/**
+      - main
+    paths:
+      - 'packages/pipeline-image/**'
+      - 'packages/pipeline-hosts/**'
+      - 'packages/host-generics/**'
+      - 'packages/asset-packs-pipelines/**'
+      - 'packages/pipelines-generics/**'
+      - 'packages/btd/**'
+      - 'pnpm-lock.yaml'
+      - '.github/workflows/pipeline-image.yml'
+  workflow_dispatch:
+    inputs:
+      push_to_vcr:
+        description: 'Push image to VCR (requires secrets)'
+        required: false
+        default: 'false'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  materialize-and-build:
+    name: Materialize runners + Docker build
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Materialize pipeline-image runners
+        run: pnpm --filter @bitcode/pipeline-image run materialize
+
+      - name: Pipeline-image unit test
+        run: pnpm --filter @bitcode/pipeline-image test
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build pipeline image (local tag)
+        run: |
+          docker build \
+            -f packages/pipeline-image/Dockerfile \
+            -t "bitcode-pipeline:ci-${GITHUB_SHA}" \
+            .
+
+      - name: Log in to VCR and push
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.push_to_vcr == 'true' }}
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          VERCEL_TEAM_ID: ${{ secrets.VERCEL_TEAM_ID }}
+          VCR_IMAGE: ${{ vars.BITCODE_PIPELINE_VCR_IMAGE }}
+        run: |
+          if [ -z "$VERCEL_TOKEN" ] || [ -z "$VERCEL_TEAM_ID" ] || [ -z "$VCR_IMAGE" ]; then
+            echo "Missing VERCEL_TOKEN, VERCEL_TEAM_ID, or BITCODE_PIPELINE_VCR_IMAGE" >&2
+            exit 1
+          fi
+          printf '%s' "$VERCEL_TOKEN" | docker login vcr.vercel.com \
+            --username "$VERCEL_TEAM_ID" \
+            --password-stdin
+          SHORT_SHA="$(echo "$GITHUB_SHA" | cut -c1-7)"
+          TAG="${VCR_IMAGE}:v48-${SHORT_SHA}"
+          docker tag "bitcode-pipeline:ci-${GITHUB_SHA}" "$TAG"
+          docker push "$TAG"
+          echo "Pushed $TAG"
+          echo "Set Production BITCODE_PIPELINE_SANDBOX_IMAGE=$TAG"

packages/generic-hosts/VercelSandbox/src/vercel-sandbox-host.ts

@@ -448,10 +448,17 @@ export function normalizeCreateOptions(
   const name =
     (typeof createOptions.name === 'string' && createOptions.name.trim()) ||
     `bitcode-host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const image =
+    typeof createOptions.image === 'string' && createOptions.image.trim()
+      ? createOptions.image.trim()
+      : undefined;
+  // Vercel SDK: runtime and image are mutually exclusive.
+  const { runtime: _runtime, ...rest } = createOptions;
   return {
-    ...createOptions,
+    ...rest,
     persistent,
     name,
+    ...(image ? { image } : { runtime: createOptions.runtime }),
   };
 }
 

packages/host-generics/src/types.ts

@@ -157,7 +157,17 @@ export type PipelineSandboxSource =
   | PipelineSandboxSourceSnapshot;
 
 export interface SandboxCreateOptions {
+  /**
+   * Stock Sandbox runtime (node24 / node22 / …). Mutually exclusive with `image`
+   * per Vercel Sandbox SDK — do not set both.
+   */
   runtime?: VercelSandboxRuntime;
+  /**
+   * VCR custom image reference (e.g. `bitcode-pipeline:v48-abc` or full
+   * `vcr.vercel.com/<team>/<project>/bitcode-pipeline:<tag>`). When set, the
+   * host plan uses the pipeline appliance image instead of a stock runtime.
+   */
+  image?: string;
   timeout?: number;
   ports?: number[];
   resources?: {

packages/pipeline-hosts/README.md

@@ -10,3 +10,10 @@ Prefer host primitives/bases:
 This package keeps AssetPack-specific host plan/runners (`asset-pack-host-*`)
 and thin re-exports of local/vercel sandbox hosts for pipeline callers.
 New host implementations belong under `generic-hosts/*`, not here.
+
+## Pipeline appliance image (Production)
+
+Set `BITCODE_PIPELINE_SANDBOX_IMAGE` (and `BITCODE_PIPELINE_HOST=sandbox`) so
+`buildAssetPackSandboxHostPlan` uses `Sandbox.create({ image })` with the VCR
+pipeline appliance from `@bitcode/pipeline-image` instead of stock `node24` +
+in-box monorepo install. See `packages/pipeline-image/README.md`.

packages/pipeline-hosts/package.json

@@ -20,6 +20,7 @@
     "test": "pnpm exec jest --config jest.config.cjs --passWithNoTests",
     "typecheck": "node ../../node_modules/typescript/bin/tsc -p tsconfig.typecheck.json --noEmit",
     "qa:asset-pack:sandbox": "ts-node --transpile-only src/dev/run-asset-pack-sandbox-host.ts",
+    "materialize-runners": "ts-node --transpile-only src/dev/materialize-runners.ts",
     "type-check": "pnpm run typecheck"
   },
   "dependencies": {

packages/pipeline-hosts/src/__tests__/asset-pack-host-plan.test.ts

@@ -77,6 +77,34 @@ describe('asset-pack sandbox host plan', () => {
     ).toThrow(/requires a sandbox source/);
   });
 
+  it('uses VCR pipeline image when sandboxImage / env is set (no stock runtime install)', () => {
+    const plan = buildAssetPackSandboxHostPlan({
+      ...baseOptions,
+      mode: 'asset_pack_pipeline',
+      synthesizeMode: 'deposit',
+      sandboxImage: 'bitcode-pipeline:v48-test',
+      source: {
+        type: 'git',
+        url: 'https://github.com/engineeredsoftware/ENGI.git',
+        revision: baseOptions.sourceRevision.commit,
+        depth: 1,
+      },
+    });
+
+    expect(plan.createOptions.image).toBe('bitcode-pipeline:v48-test');
+    expect(plan.createOptions.runtime).toBeUndefined();
+    expect(plan.createOptions.persistent).toBe(false);
+    expect(plan.files.map((file) => file.path)).toEqual([
+      '.bitcode/pipeline-host/manifest.json',
+    ]);
+    expect(plan.commands.map((command) => command.label)).toEqual([
+      'runtime-readiness',
+      'asset-pack-pipeline-run',
+    ]);
+    const run = plan.commands.find((c) => c.label === 'asset-pack-pipeline-run');
+    expect(run?.args?.join(' ')).toContain('/opt/bitcode/pipeline/run-pipeline.mjs');
+  });
+
   it('plans dependency install and live runner commands for real pipeline mode', () => {
     const plan = buildAssetPackSandboxHostPlan({
       ...baseOptions,
@@ -95,6 +123,7 @@ describe('asset-pack sandbox host plan', () => {
       revision: baseOptions.sourceRevision.commit,
       depth: 1,
     });
+    expect(plan.createOptions.image).toBeUndefined();
     expect(plan.commands.map((command) => command.label)).toEqual([
       'runtime-readiness',
       'package-manager-readiness',

packages/pipeline-hosts/src/asset-pack-host-constants.ts

@@ -17,3 +17,11 @@ export const PIPELINE_EXIT_CODE_PATH = `${HOST_RUN_DIRECTORY}/pipeline.exit-code
 export const SANDBOX_WORKING_DIRECTORY = '/vercel/sandbox' as const;
 export const DEFAULT_LONG_TIMEOUT_MS = 45 * 60 * 1000;
 export const SANDBOX_PNPM_VERSION = '10.33.0';
+
+/** In-image dispatcher (VCR pipeline appliance). */
+export const PIPELINE_IMAGE_ENTRY_DEFAULT = '/opt/bitcode/pipeline/run-pipeline.mjs';
+export const PIPELINE_IMAGE_MONOREPO_ROOT_DEFAULT = '/opt/bitcode';
+
+/** Env: when set, host plans use Sandbox.create({ image }) instead of runtime. */
+export const PIPELINE_SANDBOX_IMAGE_ENV = 'BITCODE_PIPELINE_SANDBOX_IMAGE';
+export const PIPELINE_IMAGE_ENTRY_ENV = 'BITCODE_PIPELINE_IMAGE_ENTRY';