diff --git a/docker/agent-runtime/README.md b/docker/agent-runtime/README.md index b2d35a26b22..518414b44ee 100644 --- a/docker/agent-runtime/README.md +++ b/docker/agent-runtime/README.md @@ -2,6 +2,8 @@ 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. diff --git a/docker/agent-runtime/SANDBOX-REQUIREMENTS.md b/docker/agent-runtime/SANDBOX-REQUIREMENTS.md new file mode 100644 index 00000000000..34102b33147 --- /dev/null +++ b/docker/agent-runtime/SANDBOX-REQUIREMENTS.md @@ -0,0 +1,36 @@ +# Sandbox Runtime Requirements + +This document states the sandbox environment as a contract. The sandbox owner +must meet this contract. The Paperclip runtime does not build the environment at +exec time. The environment is a requirement, not a build step. + +This document states requirements. It does not state build steps. + +## Required on PATH + +- `node` must be installed and on the PATH. +- Each agent CLI that the run uses must be installed and on the PATH. The set of + agent CLIs includes `claude`, `codex`, `gemini`, and similar CLIs. +- The owner installs only the CLIs that the run uses. The owner does not need to + install a CLI that no run uses. + +## Detection contract + +Paperclip probes each CLI before launch. Paperclip uses the same detection +pattern that the runtime Dockerfiles use: + +```bash +command -v || exit 1 +``` + +Paperclip probes each CLI with `command -v `. Paperclip fails loudly when +the CLI is absent. Paperclip does not install the CLI. Paperclip does not repair +the PATH. + +## Firm rule + +- The Paperclip runtime never modifies the login profile. The runtime never + writes a profile file. The runtime never writes an rc file. +- The Paperclip runtime never sources `nvm` on the exec path. +- The sandbox owner supplies a ready PATH. The PATH must resolve `node` and each + used agent CLI without any action from the runtime.