paperclip/docker/agent-runtime/README.md

Agent Runtime Image Family

Container images for running coding-agent harnesses in sandboxed environments (for example the kubernetes sandbox provider, stage 1 of the k8s contribution). Images are named agent-runtime-{harness}:{version} and published to ghcr.io/paperclipai/ by the agent-runtime-images workflow. The registry is overridable: every reference flows through the REGISTRY bake variable.

Image Lineup

• agent-runtime-base: Foundation. Ubuntu 22.04 + Node 22 + git + tini + non-root user (uid 1000) + the agent shim.
• agent-runtime-opencode: Extends base with opencode-ai globally installed.
• agent-runtime-pi: Extends base with @mariozechner/pi-coding-agent.
• agent-runtime-codex: Extends base with @openai/codex.
• agent-runtime-gemini: Extends base with @google/gemini-cli plus headless auth-mode settings.
• agent-runtime-claude: Extends base with @anthropic-ai/claude-code (symlinked as claude-code).
• agent-runtime-acpx / agent-runtime-hermes: Dockerfiles included in the bake group, not in the default publish scope (hermes is a stub until a CLI package exists).

Base Image Contents

OS & Runtime:

• Ubuntu 22.04
• Node.js 22 (via NodeSource APT repo)
• git
• tini (PID-1 init, ensures signal propagation)
• Non-root user paperclip (uid/gid 1000)

Paperclip Binaries:

• /usr/local/bin/paperclip-agent-shim: Go binary compiled from tools/agent-shim/. Reads /run/paperclip/runtime-command.json and syscall.Execs the harness CLI.

Defaults:

• USER: 1000:1000 (paperclip, non-root)
• WORKDIR: /workspace (mount workspace volumes here)
• ENTRYPOINT: /usr/bin/tini -- (PID-1 reaper, forwards signals)
• CMD: /usr/local/bin/paperclip-agent-shim

Building Locally

All targets build linux/amd64 by default (see buildx-bake.hcl). Derived images chain off the base target through bake contexts, so the literal registry in each FROM line is overridden at build time and the whole family builds in one pass without pushing intermediates.

docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --load

Custom tag or registry

REGISTRY=myregistry VERSION=mytag \
  docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --load

Quickstart Smoke Test

Build and verify the agent-runtime-claude image runs locally:

docker buildx bake -f docker/agent-runtime/buildx-bake.hcl base claude --load
docker run --rm ghcr.io/paperclipai/agent-runtime-claude:dev claude-code --version

Agent Container (paperclip-agent-shim)

The main agent process runs as the shim (PID 1 under tini). The shim:

1. Reads /run/paperclip/runtime-command.json (path overridable via -spec), a JSON file mounted by whatever schedules the run
2. Parses { "command", "args" }: the harness CLI and arguments
3. Resolves the command on PATH and syscall.Execs it, replacing itself
4. SIGTERM from the kubelet propagates directly to the harness (no zombie processes)

runtime-command.json Contract:

{
  "command": "claude-code",
  "args": ["--token", "xyz", "--workspace", "/workspace"]
}

The shim makes no assumptions about command structure; it is harness-agnostic. New harnesses swap the command/args; the base image stays the same.

Security Model

• Non-root execution: user 1000:1000, no capability grants
• PSS Restricted compatible: no privileged containers, no host mounts; works with a read-only root filesystem (writable /workspace + /tmp mounts)
• No secrets baked in: API tokens and credentials come from per-run ephemeral Secrets mounted as env vars or files
• Image signing: cosign keyless OIDC in the publish workflow

Publishing

.github/workflows/agent-runtime-images.yml builds and pushes the default scope (base, opencode, pi, codex, gemini, claude) on workflow_dispatch (with an explicit version tag) or on pushes to master touching these paths, then signs each digest with cosign keyless OIDC.