7083c275c8
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The sandbox exec path starts agent commands and passes runtime options to the server and plugin layers > - This path kept a noProfile flag after the exec wrappers stopped sourcing a login profile > - The flag no longer changed behavior, so it left dead API surface in the protocol and runtime helpers > - This pull request removes that dead flag from the plugin protocol, the server drivers, and the managed-runtime helpers > - It also updates the tests and points the agent runtime README at the sandbox requirements file > - The benefit is a smaller and clearer exec-path contract with no behavior change ## Linked Issues or Issue Description - No public GitHub issue exists. ### What happened? The sandbox exec path kept a `noProfile` field after the exec wrappers stopped sourcing a login profile. ### Expected behavior The plugin protocol, server drivers, and managed-runtime helpers should not expose or forward a dead field. ### Steps to reproduce 1. Run a managed-runtime command through the sandbox exec path. 2. Inspect the protocol payload and runtime helper inputs. 3. Observe that `noProfile` is present even though it no longer changes behavior. ### Paperclip version or commit `60c7da86fc7a6c1dbf37bbcd86e25ecaaff01607` ### Deployment mode Built from source (pnpm dev / pnpm build) ### Additional context This pull request removes the dead field, updates the affected tests, and updates the README note for the sandbox profile path. ## What Changed - Removed noProfile from the plugin protocol and the server exec-path call sites. - Updated the managed-runtime helpers to use the narrower exec-path contract. - Updated the affected tests and added the README pointer to SANDBOX-REQUIREMENTS.md. ## Verification - `git grep -n "noProfile" -- packages/ server/` returns zero matches. - `tsc --noEmit` passed for `@paperclipai/adapter-utils`, `@paperclipai/plugin-sdk`, and `@paperclipai/server`. - `command-managed-runtime.test.ts` passed: 22/22. - `environment-runtime.test.ts` passed: 24/24. ## Risks - Low risk. The flag was already a no-op. - A hidden external caller may still send the removed field. ## Model Used - OpenAI GPT-5, tool-enabled. ## 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|---|---|---|
| .. | ||
| Dockerfile.base | ||
| Dockerfile.claude | ||
| Dockerfile.codex | ||
| Dockerfile.gemini | ||
| Dockerfile.hermes | ||
| Dockerfile.opencode | ||
| Dockerfile.pi | ||
| README.md | ||
| buildx-bake.hcl | ||
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 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 22 (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.