mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-26 02:00:52 +01:00
Harold KimandPaperclip
b6ad07938e
State the sandbox environment as a contract that the sandbox owner must meet. Document the PATH contract, the CLI detection contract, and the firm rule. The firm rule states that the Paperclip runtime never modifies the login profile and never sources nvm on the exec path. Link the new document from the agent-runtime README. Co-authored-by: Paperclip <noreply@paperclip.ing>
88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# 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.
|
|
|
|
For the sandbox environment contract that the owner must meet, see [SANDBOX-REQUIREMENTS.md](SANDBOX-REQUIREMENTS.md).
|
|
|
|
## 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-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)
|
|
|
|
**Paperclip Binaries:**
|
|
- `/usr/local/bin/paperclip-agent-shim`: Go binary compiled from `tools/agent-shim/`. Reads `/run/paperclip/runtime-command.json` and `syscall.Exec`s 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.
|
|
|
|
```bash
|
|
docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --load
|
|
```
|
|
|
|
### Custom tag or registry
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.Exec`s it, replacing itself
|
|
4. SIGTERM from the kubelet propagates directly to the harness (no zombie processes)
|
|
|
|
**runtime-command.json Contract:**
|
|
```json
|
|
{
|
|
"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.
|