docs(agent-runtime): add sandbox runtime requirements document

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>
This commit is contained in:
Harold KimandPaperclip committed 2026-07-29 15:33:08 +00:00
1 parent ca92f727c5
commit b6ad07938e
2 files changed
+38

No files matched your search

+2
View File
@@ -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.
@@ -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 <cmd> || exit 1
```
Paperclip probes each CLI with `command -v <cmd>`. 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.