mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-11 13:24:55 +01:00
Devin FoleyandPaperclip
1f3ff75d33
Daytona can retain a sandbox API record after its container disappears. Confirm the exact missing-container response with a bounded fresh read, then let the host apply its existing replacement and backup policy. Preserve unknown failures, recoverable errors, and identity mismatches. Verified 251 provider tests, 93 host lifecycle tests, plugin typecheck and build. Added 15 regressions. Read-only inspection confirmed the provider response and an existing verified backup without changing live state. Co-Authored-By: Paperclip <noreply@paperclip.ing>
50 lines
2.6 KiB
Markdown
50 lines
2.6 KiB
Markdown
# `@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:
|
|
|
|
```text
|
|
@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. A provider-resolved `target` does not change the identity of an existing sandbox. Release closes the same scoped lease that a later sentinel-verified resume reopens.
|
|
- A sandbox record can survive the loss of its underlying container. Resume treats it as expired only when a fresh provider read confirms the exact missing-container error for that sandbox and marks it unrecoverable. Unknown errors and failed confirmation reads preserve the lease. The host still requires a verified native-runner backup before replacement.
|
|
|
|
## Local development
|
|
|
|
```bash
|
|
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/`
|