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.
|