mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-11 13:24:55 +01:00
Nicky LeachandPaperclip
c4f62644b0
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Daytona sandbox provider now uses an advisory bwrap wrapper > - Operators need clear host and image setup for bubblewrap, sudo, and user namespaces > - The repo should document that setup, but it should not own provisioning > - This pull request adds the operator guidance to the shared sandbox requirements and the Daytona README > - The benefit is that operators can enable the wrapper with the same steps the code expects ## Linked Issues or Issue Description Refs #10554 and #10541. ## What Changed - Added an advisory bwrap prerequisites section to `packages/plugins/sandbox-providers/SANDBOX-REQUIREMENTS.md`. - Added an operator enablement section to `packages/plugins/sandbox-providers/daytona/README.md`. - Documented the install commands, the sudoers rule, the user namespace setting, and the verification command. - Kept provisioning out of the repo and left it to the image or snapshot layer. ## Verification - `git diff --check origin/master...HEAD` - `gh pr checks 10560` ## Risks - Low risk. This change updates documentation only. - The docs can drift if the host setup changes later. - Provisioning still lives outside the repo. ## Model Used - OpenAI Codex, GPT-5, tool use 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 linked existing issues with `Fixes: #` / `Closes: #` / `Refs #` OR described the issue in-PR following the relevant issue template - [x] I have not referenced internal or instance-local Paperclip issues or links - [x] My branch name describes the change 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>
97 lines
4.3 KiB
Markdown
97 lines
4.3 KiB
Markdown
# 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.
|
|
|
|
## bwrap prerequisites (advisory, optional)
|
|
|
|
A sandbox provider can wrap a command with an advisory bubblewrap (`bwrap`)
|
|
wrapper. The wrapper is advisory, best-effort, and automatic. It adds no
|
|
security. The ephemeral sandbox model stays the only security posture. A missing
|
|
prerequisite degrades to the plain command. It never fails the lease. Daytona is
|
|
the current provider with bwrap support.
|
|
|
|
The wrapper needs three run-time prerequisites. Each prerequisite is a fact of
|
|
the image or snapshot, not a fact of the runtime code. The runtime does not
|
|
build the image or snapshot. The runtime only probes for the capability and
|
|
degrades when the capability is absent. So each prerequisite is an owner
|
|
responsibility under the requirement-not-build contract above:
|
|
|
|
- The `bubblewrap` package is installed, and the `bwrap` binary is on the PATH
|
|
(normally `/usr/bin/bwrap`).
|
|
- A passwordless `sudo` rule lets the sandbox user run `bwrap` as root.
|
|
- The host and kernel allow an unprivileged user namespace.
|
|
|
|
The owner supplies these prerequisites through the image or snapshot. The
|
|
provider README states the distro-specific install commands, the exact sudoers
|
|
rule, the user-namespace setting, and the verification command. The install and
|
|
the sudoers change are environment provisioning at the image or snapshot layer.
|
|
Route them to DevOps through the board. Do not add a provisioning script to the
|
|
repository.
|
|
|
|
## 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.
|
|
|
|
## Runtime dependencies
|
|
|
|
The sandbox execution and synchronization paths need more than `node` and the
|
|
agent CLIs. The owner must also supply these:
|
|
|
|
- A POSIX shell as `sh`, normally `/bin/sh`. The runtime runs each command with
|
|
`sh -c <script>`. The runtime uses `bash` only when the adapter sets the shell
|
|
to `bash`.
|
|
- `tar`. The synchronization path extracts and creates archives with `tar`. A
|
|
sandbox without `tar` cannot receive or return workspace files.
|
|
- A writable workspace directory. The runtime extracts the workspace archive
|
|
into this directory.
|
|
- A writable home directory. The agent CLIs write state and credentials under
|
|
the home directory.
|
|
- A writable cache directory and a writable temporary directory. The runtime and
|
|
the agent CLIs write intermediate files to these locations.
|
|
|
|
## 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 and no install command is configured for the CLI.
|
|
|
|
## Optional CLI installation
|
|
|
|
An adapter can configure an install command for a CLI. When an install command
|
|
is configured, the runtime obeys this flow:
|
|
|
|
1. The runtime probes the CLI with `command -v <cmd>`.
|
|
2. If the CLI is already on the PATH, the runtime skips the install.
|
|
3. If the CLI is absent, the runtime runs the configured install command one
|
|
time.
|
|
4. A failed install is not fatal. The runtime writes a log line and continues.
|
|
The launch-time probe still reports a missing CLI and fails loudly.
|
|
|
|
An owner who relies on a configured install command must also supply the network
|
|
access, the filesystem write access, and the package tooling that the install
|
|
command needs. When no install command is configured, the runtime does not
|
|
install the CLI. The owner must supply the CLI on 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, except for a configured
|
|
install command.
|