Dotta
a70b0f70b6
* origin/master: (57 commits) fix(adapter-utils): extend the duplex fail-closed run disposition to the CLI lane (#11966) fix(recovery): stop automatic stranded-task takeovers (#11961) feat(sandbox): add the duplex bridge broker, gated transport selection, and fixed observability (#11769) Drop the mission step from the wizard arc (#11935) fix(runtime): guard empty Bash 3.2 array expansion (#11891) chore(lockfile): refresh pnpm-lock.yaml (#11915) feat(commitperclip): surface the Co-Authored-By trailers a squash merge needs (#11498) Rebuild the onboarding agent arc on the prototype's step design (#11905) fix(workspaces): read process cwd on macOS so port-owner adoption works (#11763) fix(workspaces): attach PR preparation to existing branches (#11703) fix(grok-local): stop defaulting --permission-mode to dontAsk (#11898) Fix remote-only workspace base refs and pre-adapter retry loops (#11892) feat(environments): refer to the managed default environment by name, not the sandbox driver key (#11838) test(server): cover buffered duplex chunk drain after a late listener bind (#11865) fix(server,ui,claude-local): verify auth on the adapter Test lane and enforce managed-sandbox tenant binding (#11810) chore(lockfile): refresh pnpm-lock.yaml (#11867) fix(kimi): align package with Node 24 policy (#11890) feat(ui): rename "Agent mode" to "Auto mode" and show full work-mode labels (#11866) fix(build): enforce Node 24 across Paperclip (#11792) fix(server): end the duplex route on the pre-bind bounds when frames arrive before the bind (#11860) ... # Conflicts: # Dockerfile # packages/db/src/migrations/meta/0226_snapshot.json # packages/db/src/migrations/meta/_journal.json # pnpm-lock.yaml # server/package.json # server/src/routes/agents.ts # server/src/services/heartbeat.ts # server/src/services/issues.ts # server/src/services/recovery/service.ts # ui/package.json # ui/src/adapters/transcript.test.ts # ui/src/components/TaskChatThread.test.tsx # ui/src/components/TaskChatThread.tsx # ui/src/components/task-chat/TaskChatTurn.tsx # ui/src/index.css # ui/src/pages/Agents.tsx
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 24 + git + tini + non-root user (uid 1000) + the agent shim.agent-runtime-opencode: Extends base withopencode-aiglobally 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-cliplus headless auth-mode settings.agent-runtime-claude: Extends base with@anthropic-ai/claude-code(symlinked asclaude-code).agent-runtime-hermes: Dockerfile included in the bake group, not in the default publish scope (stub until a CLI package exists).
Base Image Contents
OS & Runtime:
- Ubuntu 22.04
- Node.js 24 (via NodeSource APT repo)
- git
- tini (PID-1 init, ensures signal propagation)
- Non-root user
paperclip(uid/gid 1000)
The NodeSource install puts node on the default PATH. The agent shim in this
image runs the harness directly with that PATH. The shim does not source a
login profile, and the runtime never writes a profile or an rc file. Some
sandbox providers instead wrap each command in a login shell. That shell sources
/etc/profile and the user profile files to read an owner-supplied PATH. No
exec path sources nvm. For the full exec-path contract, see
packages/plugins/sandbox-providers/SANDBOX-REQUIREMENTS.md.
Paperclip Binaries:
/usr/local/bin/paperclip-agent-shim: Go binary compiled fromtools/agent-shim/. Reads/run/paperclip/runtime-command.jsonandsyscall.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:
- Reads
/run/paperclip/runtime-command.json(path overridable via-spec), a JSON file mounted by whatever schedules the run - Parses
{ "command", "args" }: the harness CLI and arguments - Resolves the command on PATH and
syscall.Execs it, replacing itself - 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+/tmpmounts) - 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.