Files
PaperClipAI/doc/runner-image-contract.md
T
Nicky LeachandClaude Fable 5.2 5d3fa712aa feat(docker): build and check the Runner alone as the runner-artifacts target (#21204)
## 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>
2026-11-12 17:30:51 -08:00

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) and buildInputsDigest (the digest in the Runner's build stamp);
  • sourceRevision: the commit given to the build, also in the pack as payload.runnerSourceRevision;
  • publication: true only for a build with the build argument PAPERCLIP_RUNNER_IMAGE_PUBLICATION=1. Only then does the pack carry the identity, as payload.runnerInputsDigest. Another image build that runs the stage inline builds the same Runner but is not this image;
  • platform (linux, amd64 or arm64) and libc: 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;
  • paths and sha256: 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 include pnpm-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/amd64 and linux/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.json has its digest, the dist tree 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-digest fails 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 the a+rX grant 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_REVISION or PAPERCLIP_BUILD_COMMIT has no pack. It is for local use.
  • The build runs the steps of the Runner's build script that write output, not its drift checks; repository CI runs those.
  • A build that vendors /runner-package/ reuses dist only 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.20 is 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.