RomanNum3ral
/
paperclip
mirror of https://github.com/paperclipai/paperclip.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
paperclip/packages/plugins/sandbox-providers/daytona
History
Nicky Leach bd7a13eb9c
fix(daytona): replace bwrap user-namespace with su privilege drop (#10805) 
## Thinking Path

> - Paperclip runs AI agents inside Daytona sandbox environments
> - The Daytona plugin wraps agent commands in bwrap to prevent
accidental writes outside the workspace
> - bwrap previously used `--unshare-user --uid <uid> --gid <gid>` to
run commands as the sandbox user inside the container
> - This creates a uid_map of `<uid> 0 1` — inside-uid maps to
outside-uid 0 (root)
> - Files owned by the sandbox user (outside-uid 1001) appear as
overflow uid 65534 (nobody) from inside the namespace
> - So all writes to the workspace fail with Permission denied, and the
agent cannot run
> - This PR replaces the user-namespace approach with `su -s /bin/sh
<user>`, which gives the correct uid mapping
> - The benefit is that bwrap works correctly on Daytona: writes succeed
and the advisory isolation is preserved

## Linked Issues or Issue Description

No existing issue. Describing the bug inline per the bug report
template.

**What happened?**

Running a Codex agent in a Daytona sandbox failed immediately. The agent
could not create directories inside the workspace:

```
mkdir /home/daytona/paperclip-workspace/.paperclip-runtime/codex/paperclip-bridge/queue ... failed with exit code 1:
bwrap: Can't find source path /home/daytona/paperclip-workspace: Permission denied
```

Root cause: bwrap used `--unshare-user --uid 1001 --gid 1001` (via
sudo/root). This writes uid_map `1001 0 1` — inside-uid 1001 maps to
outside-uid 0. Files owned by outside-uid 1001 (the workspace) appear as
overflow uid 65534 (nobody) from inside the namespace. `--bind-try`
suppresses ENOENT but not EACCES, so the bind exits 0 and the wrapper
proceeds — but every write inside then fails with Permission denied.

The bwrap capability probe (`sudo -n bwrap --unshare-user --uid 0 --gid
0 --ro-bind / / -- true`) did not test the workspace bind or the su
invocation, so it incorrectly reported bwrap as available.

**Expected behavior**

The agent should start and run normally inside the Daytona sandbox.
Directory creation and file writes in the workspace should succeed.

**Steps to reproduce**

1. Configure Paperclip with a Daytona sandbox provider
2. Start a Codex agent task targeting a Daytona sandbox
3. Observe the `adapter_failed` error: `mkdir ... failed with exit code
1: bwrap: Can't find source path /home/daytona/paperclip-workspace:
Permission denied`

**Paperclip version or commit**

master (reproducible on current HEAD before this fix)

**Deployment mode**

Self-hosted server

**Agent adapter(s) involved**

- [x] Codex

**Relevant logs or output**

```
mkdir /home/daytona/paperclip-workspace/.paperclip-runtime/codex/paperclip-bridge/queue \
  /home/daytona/paperclip-workspace/.paperclip-runtime/codex/paperclip-bridge/queue/requests \
  /home/daytona/paperclip-workspace/.paperclip-runtime/codex/paperclip-bridge/queue/responses \
  /home/daytona/paperclip-workspace/.paperclip-runtime/codex/paperclip-bridge/queue/logs \
  failed with exit code 1: bwrap: Can't find source path /home/daytona/paperclip-workspace: Permission denied
(adapter_failed)
```

## What Changed

- Replaced `--unshare-user --uid <uid> --gid <gid>` with `su -s /bin/sh
<username>` in `buildBwrapCommand`. bwrap runs as real root (for
bind-mount capability), then `su` drops into the sandbox user. Inside
uid=1001 maps to outside uid=1001, so workspace files are writable.
- Removed `detectSandboxUidGid` (ran `id -u` + `id -g`). Added
`detectSandboxUsername` (runs `id -un`) — the username is what `su`
needs.
- Updated `detectBwrapAvailable` probe to test the actual invocation:
`sudo -n bwrap --ro-bind / / [--bind-try <workspace> <workspace>] -- su
-s /bin/sh '<user>' -c true`. This catches both the su failure mode and
the EACCES-on-workspace-bind case.
- Updated `detectBwrapCapability` to run sequentially (username first,
then probe with that username and remoteCwd).
- Replaced `sandboxUid`/`sandboxGid` in lease metadata with
`sandboxUsername`.
- All three `detectBwrapCapability` call sites now pass `remoteCwd`.
- Updated `BwrapExecPlan` type and `resolveBwrapExecPlan` to use
`username: string` instead of `identity: { uid, gid }`.
- Updated tests TDD-style: rewrote tests to describe the new behavior
first, then implemented to pass them.

## Verification

**SSH verification** (run against a live Daytona sandbox before writing
the fix):

```bash
# Old approach — fails
sudo -n bwrap --unshare-user --uid 1001 --gid 1001 \
  --ro-bind / / --bind-try /home/daytona/paperclip-workspace /home/daytona/paperclip-workspace \
  -- sh -c "mkdir -p /home/daytona/paperclip-workspace/test"
# → mkdir: cannot create directory: Permission denied

# New approach — works
sudo -n bwrap --ro-bind / / \
  --bind-try /home/daytona/paperclip-workspace /home/daytona/paperclip-workspace \
  -- su -s /bin/sh daytona -c "mkdir -p /home/daytona/paperclip-workspace/test && echo ok"
# → ok (files owned by uid 1001)
```

**Unit tests:**

```
cd packages/plugins/sandbox-providers/daytona && npx vitest run
# 114 passed, 2 pre-existing failures (macOS tar compatibility in file-sync.ts, unrelated)
```

## Risks

- `su` must be available in the Daytona sandbox image. It is a standard
POSIX tool present in every image tested. If absent,
`detectBwrapAvailable` returns false and execution falls back to the
unwrapped path (same behavior as before).
- The advisory bwrap wrapper was never a security boundary — it is
best-effort. The behavioral change (root → sandbox user inside the
container) is strictly better: files created by the agent now have the
correct ownership.
- `sandboxUid` and `sandboxGid` are removed from lease metadata. Any
external code reading those fields will get `undefined`. They were only
used internally by `resolveBwrapExecPlan`, which now reads
`sandboxUsername`.

## Model Used

Claude Sonnet 4.6 (`claude-sonnet-4-6`) via Claude Code CLI — tool use
enabled, extended context. The model diagnosed the bug via SSH
inspection, designed the fix, and implemented it TDD-style (tests first,
then implementation).

## 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 (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
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: Claude Sonnet 4.6 <noreply@anthropic.com>
 		2026-08-03 21:17:17 -07:00
..
src fix(daytona): replace bwrap user-namespace with su privilege drop (#10805) 2026-08-03 21:17:17 -07:00
README.md fix(daytona): replace bwrap user-namespace with su privilege drop (#10805) 2026-08-03 21:17:17 -07:00
package.json fix(plugins): move dev SDK linking out of plugin postinstall scripts (#8255) 2026-06-18 07:45:53 -07:00
tsconfig.json Add reusable sandbox custom images (#8794) 2026-06-30 09:57:49 -07:00
vitest.config.ts Add reusable sandbox custom images (#8794) 2026-06-30 09:57:49 -07:00

README.md

@paperclipai/plugin-daytona

Published Daytona sandbox provider plugin for Paperclip.

This package lives in the Paperclip monorepo, but it is intentionally excluded from the root pnpm workspace and shaped to publish and install like a standalone npm package. That lets operators install it from the Plugins page by package name without introducing root lockfile churn for Daytona's SDK dependencies.

Install

From a Paperclip instance, install:

@paperclipai/plugin-daytona

The host plugin installer runs npm install into the managed plugin directory, so transitive dependencies such as @daytonaio/sdk are pulled in during installation.

Configuration

Configure Daytona from Instance Settings -> Environments, not from the plugin's plugin page.

  • Put the Daytona API key on the sandbox environment itself.
  • When you save an environment, Paperclip stores pasted API keys as company secrets.
  • DAYTONA_API_KEY remains an optional host-level fallback when an environment omits the key.
  • Optional apiUrl and target settings map directly to the Daytona SDK/client configuration. If apiUrl is omitted, the Daytona SDK uses its default endpoint.

Notes:

  • The current published Daytona SDK package is @daytonaio/sdk.
  • The driver supports both snapshot-based and image-based sandbox creation. If both are set, validation rejects the config as ambiguous.
  • Reusable leases map to Daytona stop/start semantics. Non-reusable leases are deleted on release.

Advisory bwrap wrapper

The driver wraps a sandbox command with an advisory bubblewrap (bwrap) wrapper. The wrapper is advisory, best-effort, and automatic. At lease time the driver probes the sandbox for the wrapper capability and records the result on the lease metadata. At execute time the driver wraps the command when the capability is present. The command builder is a pure function.

  • The wrapper adds no security. The ephemeral sandbox stays the only security posture. The wrapper only gives an agent real-time feedback when the agent tries to change a file that the ephemeral sandbox will not keep.
  • The read-only root is a feedback signal. The wrapper binds the root as read-only (--ro-bind / /) and re-binds only the writable directories. A write to a path outside the writable set fails at once, so the agent learns the change is not durable.
  • A capability probe records the wrapper capability. No configuration field turns it on. At lease time the driver reads the sandbox username with id -un, then probes the end-to-end bwrap capability by running sudo -n bwrap with a workspace bind and an su user switch. It stores bwrapAvailable and sandboxUsername on the lease metadata.
  • The probe is best-effort. A missing bwrap binary, a missing passwordless sudo -n rule, a missing su binary, or an inaccessible workspace bind records bwrapAvailable: false and never fails the lease.
  • The writable set is the workspace plus the read-write sync destinations. The wrapper binds the workspace directory read-write as the baseline; the workspace is always durable. It adds the read-write sync destinations that a sync-in recorded for the same lease. The set deduplicates the directories. The baseline keeps a safe result even when the collected set is empty.
  • The wrapper runs at execute time when the capability is present. The driver wraps the command only when the lease reports bwrapAvailable: true and a username is known. It binds the workspace and the read-write sync destinations, keeps the root read-only for feedback, and re-binds the stdin file after the fresh /tmp. It runs the plain command when the capability or the username is missing. A wrap without a username would run as root and give the agent's files root ownership, so the driver keeps the plain command in that case.

Operator enablement (advisory bwrap)

The advisory bwrap wrapper needs three run-time prerequisites on the image or snapshot. The repository does not build the Daytona image or snapshot. It references an external image or snapshot. So the three prerequisites are image facts, not code facts. The runtime only probes for the capability and degrades when the capability is absent.

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. So the enablement below is optional. It gives the agent real-time feedback on a non-durable write. It does not change the security posture.

The install and the sudoers change are environment provisioning at the image or snapshot layer. Route them to DevOps through the board. Do not run the steps from the runtime and do not commit a provisioning script to the repository.

1. Install the bubblewrap package

The repository does not state the Daytona base distribution. Confirm the distribution on the referenced image or snapshot first, then run the matching command:

# Debian/Ubuntu
apt-get install -y bubblewrap
# Alpine
apk add bubblewrap
# Fedora/RHEL
dnf install -y bubblewrap

Confirm the binary path is /usr/bin/bwrap after the install.

2. Add the passwordless sudoers rule

The wrapper runs bwrap as root with sudo -n. Add this exact sudoers line. Use the real sandbox user name and the real bwrap path:

<sandbox-user> ALL=(root) NOPASSWD: /usr/bin/bwrap

The <sandbox-user> is the account name that id -un returns inside the sandbox. Use the account name, not a numeric id, in the sudoers line. The probe reads the username with id -un. The driver resolves the sandbox work directory first, then the user home directory. It uses /home/daytona only as a fallback default when both are empty. Confirm the real home directory for your image or snapshot. Install the sudo and util-linux (for su) packages in the image or snapshot if they are absent.

3. Verify the prerequisites

Run this exact command as the sandbox user, replacing <sandbox-user> and <workspace> with real values:

sudo -n bwrap --ro-bind / / --bind-try <workspace> <workspace> -- su -s /bin/sh <sandbox-user> -c true

A zero exit code means all prerequisites are met. A non-zero exit code means one prerequisite is missing. The wrapper then stays off and runs the plain command.

The probe binds the workspace directory and switches to the sandbox user with su. This matches the exact invocation the live wrapper uses, so a passing probe guarantees that execution commands will also succeed.

Local development

cd packages/plugins/sandbox-providers/daytona
pnpm install --ignore-workspace --no-lockfile
pnpm build
pnpm test
pnpm typecheck

These commands assume the repo root has already been installed once so the local @paperclipai/plugin-sdk workspace package is available to the compiler during development.

Package layout

  • src/manifest.ts declares the sandbox-provider driver metadata
  • src/plugin.ts implements the environment lifecycle hooks
  • paperclipPlugin.manifest and paperclipPlugin.worker point the host at the built plugin entrypoints in dist/