mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-25 17:45:53 +01:00
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:
2 files changed
+38
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user