## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Runner is the part that executes agent work: a daemon (`paperclip-runnerd`) and a provider pack of agent tools > - Today the application image build compiles the Runner. Other images that need the Runner build it again, or pull the whole application image to copy it out > - Each of those builds can produce a slightly different Runner, and each one costs time > - The Runner should be built one time for each change to its inputs, and every image should copy the same bytes > - This pull request adds the build target `runner-artifacts`, a contract for its layout, and a workflow that builds and checks it. It publishes nothing > - Nothing consumes the target in this pull request. The application image build does not change > - The benefit is one checked Runner build that later changes can publish and copy by digest ## Linked Issues or Issue Description Refs #21096 (the merge-queue image build) and #21167 (provider pack layers). Those are earlier work on the same build. No issue exists for this change. **Problem or motivation** The Runner is compiled inside the application image build. The daemon comes from the `runner-build` stage. The provider pack is built on top of the full server and UI build. Downstream sandbox and VM images need the same Runner. They rebuild it from source, or they pull the application image and copy paths out of it. There is no contract for those paths and no single identity for a Runner build. **Proposed solution** Build the Runner alone, from its own inputs, as a plain file tree. Give each build an identity: a digest of its inputs. Document the layout as a contract, and check every built tree against it. Keep every check that proves the Runner is good in this one build. **Alternatives considered** - Keep the current builds and only document the paths in the application image. This does not remove the duplicate builds, and consumers still need the full application image. - Build the Runner in `docker.yml`. That workflow has no pull-request trigger, so a change to the Runner build would have no check before it merges. **Roadmap alignment** This is build infrastructure. It adds no product feature and does not overlap an item in `ROADMAP.md`. This is part 2 of 4. Each part is on top of the one before it: 1. `runner/pack-inputs-digest`: an optional field in the provider pack manifest 2. `runner/runner-image-build` (#21204): build and check the Runner image, with no publication (this pull request) 3. `runner/runner-image-layers`: layers by change rate, and the slim variant 4. `runner/runner-image-publish`: publish both variants from `master` This pull request had one larger form before. Publication, the image layers and the second variant are now parts 3 and 4. ## What Changed - `Dockerfile`: eight new stages that end in the target `runner-artifacts` (`FROM scratch`). They install with a filtered, frozen lockfile from a context that holds only the Runner's inputs. The base is a Node image on Debian bookworm, pinned by digest. No existing stage changed. `cloud` is still the default target. - The tree holds: the stripped daemon, the Runner package's complete `dist` with the build stamp that its own build records, the provider pack with its transport archives, the Grok provisioning inputs, the transport contract source and a bundled transport module, the lockfile, and `runner-image.json`. - `scripts/runner-image-identity.mjs`: computes the image identity. It hashes every file under the paths that the build copies from the build context (path, executable bit, content; symbolic links by target), the whole `Dockerfile`, and the two platforms. The build runs it on the files that the build context supplies after `.dockerignore`. - `scripts/runner-image-layout.mjs`: the layout contract. `write` assembles the tree in the build. `check` verifies a built tree: every documented path, the build stamp, every pack artifact and tree digest in `provider-pack.json`, and every transport archive. It also extracts the transport archives the way a sandbox does and compares the result with the pack. No checked path may resolve outside the tree. - Publication form. The build argument `PAPERCLIP_RUNNER_IMAGE_PUBLICATION=1` is off by default. Only with it does the pack manifest carry `payload.runnerInputsDigest` (part 1), and `runner-image.json` records `publication: true`. Another image build that runs the stage inline builds the same Runner, but its pack names no image. `check` requires the field in a publication build and refuses it in any other. `--expect-inputs-digest` passes only for a publication build. - `docker/runner-image/Dockerfile.smoke`: runs `paperclip-runnerd --build-metadata` on each base image that a consumer uses. Each base is pinned by digest. - `.github/workflows/runner-image.yml`: two jobs, on pull requests that touch an input and on manual dispatch. `identity` resolves the lockfile and computes the digest in the build context. `build` builds each architecture on a native runner, checks the layout, and runs the smoke matrix. The workflow has `contents: read` only. It holds no credential, reads no registry, and publishes nothing. It builds the publication form, so the check can bind the tree to the digest that the identity job resolved. The tree stays on the runner. - `packages/paperclip-runner/scripts/provider-pack-runtime-tree.mjs`: the tree digest function moves here from `build-provider-pack.mjs` without a change in behavior, so the layout check can use it. A test pins its value. - `.github/workflows/pr-merge-review.yml`: lists the new workflow, as `doc/PR-MERGE-REVIEW-WEBHOOK.md` requires. - `doc/runner-image-contract.md` (127 lines): the contract for consumers. `doc/DOCKER.md` links to it. Changes from the earlier form of this pull request: - The identity hashes the whole `Dockerfile`. The script no longer parses stages, and it no longer refuses recipes. `scripts/runner-image-identity.mjs` went from 397 lines to 166. A short test keeps the three rules that make the hash enough: the Runner stages start only from pinned images, only `runner-artifacts-context` reads the build context, and it copies only the paths that the identity hashes. - The contract document went from 384 lines to 127. - The workflow tests keep only the security properties: job permissions, no credential and no registry access, triggers, actions pinned by commit, and no expression inside a shell script. They no longer pin step names, order, or wording. ## Verification Verified on `linux/arm64` only, on a local Docker host: - `docker buildx build --target runner-artifacts --platform linux/arm64 --build-arg PAPERCLIP_RUNNER_SOURCE_REVISION=<sha> --build-arg PAPERCLIP_RUNNER_IMAGE_PUBLICATION=1 --output type=local,dest=<tree> .` builds in 166 seconds without a cache. The image is one layer of 850,121,093 bytes. The tree is 1,755,345,443 bytes in 9,969 files. - `node scripts/runner-image-layout.mjs check <tree> --expect-inputs-digest <digest> --expect-source-revision <sha> --expect-architecture arm64` passes on the exported tree. - `docker buildx build --file docker/runner-image/Dockerfile.smoke --build-context runner-artifacts=<tree> docker/runner-image` passes on all five base images. - The digest from `--target runner-artifacts-identity` equals the digest in the built `runner-image.json`: `d05f51f075cb8fec687a1d27f574ba7cb41cd8ebbe9927c5cbb2cfc13b147880`. - The same target with `PAPERCLIP_BUILD_COMMIT=<sha>` and no publication argument builds. Its pack has `runnerSourceRevision` and no `runnerInputsDigest`. `check` passes on it, and `check --expect-inputs-digest` fails with "this is not a publication build". - An edit to `ui/package.json` and to `server/src` leaves the digest unchanged. A comment added to an application stage of the `Dockerfile` changes it. - The two points above ran one commit state earlier. The only difference to this commit is one type annotation in a comment of `scripts/runner-image-layout.mjs`. - A named build context replaces the `runner-artifacts` stage, and no Runner stage runs. A build with the application build's view of the context accepts the tree's `dist` and build stamp as current (`assessRunnerBuild`). - The daemon has the same bytes in the five cold builds of this stack that were compared. - Tests: `cd server && node node_modules/vitest/vitest.mjs run` on `runner-image-identity.test.ts`, `runner-image-layout.test.ts` and `runner-image-workflow.test.ts` (132 tests), with `remote-provider-pack-verification.test.ts` and the existing Dockerfile tests: 186 tests pass. `tests/runner-e2e` workflow tests: 39 pass. `node --test .github/scripts/tests/*.test.mjs`: 799 pass. `node --test` on the image contract scripts and `provider-pack-runtime-tree.test.mjs`: 33 pass. `check-docker-deps-stage.mjs`, `check-node-version-policy.mjs` and `docker buildx build --check` report nothing. Never run: - The `linux/amd64` build. It is the leg that downloads the Cursor and Copilot assets for the pack. - The workflow. No job has run on GitHub. - The transport archive round trip with GNU tar outside the build. The build runs it with GNU tar. The local host ran it with bsdtar. - `actionlint` and `hadolint`. They are not installed on the local host. - The full test suite and the full typecheck. CI must supply them. ## Risks - Low risk to the application image. The change adds stages and files. No existing target reaches the new stages. - The first run of the workflow is the first test of the amd64 build. This pull request triggers it. - The `Dockerfile` is one file for all images. Any edit to it, also to an application stage, changes the Runner image identity. That is the price of not parsing it. - The Dockerfile frontend (`# syntax=docker/dockerfile:1.20`) is a tag, not a digest. A new frontend release under that tag does not change the identity. - The image does not run the drift checks of the Runner's `build` script. They need files outside the Runner's inputs, and repository CI runs them. A test fails when the `build` script gains a step. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Fable 5.2 (`claude-fable-5-2`), Anthropic, used through Claude Code with tool use (shell, file edits, local Docker builds). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
6.2 KiB
Runner image contract
The Runner image is the Runner built alone, as a plain file tree with no
entrypoint and no operating system: the runner-artifacts target of the
Dockerfile. An image build copies paths out of it instead of compiling the
Runner again. Its name is ghcr.io/paperclipai/paperclip-runner. Nothing in
this repository consumes it yet.
Nothing publishes it yet: .github/workflows/runner-image.yml builds and
checks it.
Layout
Every path a consumer may copy (RUNNER_IMAGE_PATHS in
scripts/runner-image-layout.mjs). Every file is readable by every user.
| Path | Content |
|---|---|
/runner-image.json |
Identity and description of this image. |
/paperclip-runnerd |
The daemon. A stripped release binary, mode 0755. |
/provider-pack/ |
The remote provider pack, with provider-pack.json. |
/provider-pack.archive.json |
Receipt of the pack's transport archives. |
/provider-pack.archives/ |
The transport archives the receipt lists. |
/runner-package/package.json |
The Runner package manifest. |
/runner-package/dist/ |
The Runner's complete build output. dist/bin/paperclip-runnerd is the same file as /paperclip-runnerd. |
/runner-package/node_modules/.cache/paperclip-runner-build-inputs.json |
The build stamp the Runner's build recorded for that output. |
/runner-package/scripts/provision-grok.mjs |
Provisions the native Grok executable. Reads platforms.json by relative path. |
/runner-package/src/providers/grok/platforms.json |
The Grok release pins. |
/runner-package/src/live/runnerd-codex-transport.ts |
The transport source, as a contract file. It defines RUNNER_CLIENT_VERSION. |
/bundles/runnerd-codex-transport.mjs |
The pack's dist/live/runnerd-codex-transport.js as one module. It imports without node_modules. |
/pnpm-lock.yaml |
The lockfile the image was installed from. |
Paths under /runner-package/ keep their place inside
packages/paperclip-runner. runner-image.json describes one platform:
inputsDigest(the identity below) andbuildInputsDigest(the digest in the Runner's build stamp);sourceRevision: the commit given to the build, also in the pack aspayload.runnerSourceRevision;publication:trueonly for a build with the build argumentPAPERCLIP_RUNNER_IMAGE_PUBLICATION=1. Only then does the pack carry the identity, aspayload.runnerInputsDigest. Another image build that runs the stage inline builds the same Runner but is not this image;platform(linux,amd64orarm64) andlibc: the glibc the daemon was compiled on (Debian bookworm, the oldest a consumer runs) and the newest glibc version it needs;providerPack: the pack's digest and target;pathsandsha256: the table above, and the digest of every single file.
Identity
An image is named inputs-<digest>. scripts/runner-image-identity.mjs
computes the digest from:
- every file under the paths the build copies from the build context
(
RUNNER_IMAGE_CONTEXT_INPUTS, which includepnpm-lock.yaml): path, executable bit and content, and each symbolic link by its target; - the whole
Dockerfile: the recipe, the base image pinned by digest and the toolchain pins. Any edit to it makes a new image; - the two platforms,
linux/amd64andlinux/arm64.
The source revision is not part of it, and neither is the text of
.dockerignore: a rule changes the digest only when it changes which of
those files the build receives. The build computes the digest for itself:
docker buildx build --target runner-artifacts-identity --output type=local,dest=/tmp/identity .
jq -r .digest /tmp/identity/runner-image-identity.json
The install is frozen. It fails when the lockfile is behind the manifests the
build reads (the root one, packages/paperclip-runner and
packages/paperclip-eval-kernel). A contributor cannot edit the lockfile, so
pull-request runs resolve it first. For a local build, run
pnpm install --resolution-only --ignore-scripts --no-frozen-lockfile.
Checks
node scripts/runner-image-layout.mjs check <tree> runs in the build and
again on the exported tree. It fails unless:
- every documented path exists, matches its digest in
runner-image.json, and resolves inside the tree; - the build stamp names the inputs the identity names;
- every artifact in
provider-pack.jsonhas its digest, thedisttree and each provider asset tree match their tree digests, and the pack names this image's revision and platform; - the pack names the inputs digest in a publication build and in no other.
--expect-inputs-digestfails on any other build; - every transport archive matches its receipt, and the archives
extract to the pack. The check extracts them as a sandbox does (GNU tar
with the options in
provider-pack-layers.ts) and compares paths, content, link targets and all twelve permission bits, after thea+rXgrant the build makes once the archives are written.
The build also runs paperclip-runnerd --build-metadata on every base image
in docker/runner-image/Dockerfile.smoke. Add a base there before a consumer
uses it.
Consuming the image
Read the image only with COPY --from, and pin it by digest:
FROM ghcr.io/paperclipai/paperclip-runner@sha256:<digest> AS runner-artifacts
FROM debian:trixie-slim
COPY --from=runner-artifacts /paperclip-runnerd /usr/local/bin/paperclip-runnerd
A Dockerfile with a runner-artifacts stage of its own, as in this
repository, can take a built image or tree in its place with
--build-context runner-artifacts=<image or directory>. The stage is then
not built.
Known limits
- A build without
PAPERCLIP_RUNNER_SOURCE_REVISIONorPAPERCLIP_BUILD_COMMIThas no pack. It is for local use. - The build runs the steps of the Runner's
buildscript that write output, not its drift checks; repository CI runs those. - A build that vendors
/runner-package/reusesdistonly when its own Runner build-inputs digest equals the stamp's. The image computes that digest in the.dockerignore-filtered context; a checkout gives another. # syntax=docker/dockerfile:1.20is a tag. A new frontend release under it does not change the identity.- The archive check does not tell a directory with its own archive member from one created only as a file's parent.