Devin FoleyandPaperclip
0b62c736a0
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Apps connections give agents controlled access to external services. > - Daytona provides sandbox, file, command, Git, and account APIs. > - Operators need to assign this access without exposing a server credential. > - A small task-specific tool list cannot serve general Daytona work. > - This pull request adds the published HTTP actions through the existing connection gateway. > - Operators keep control of identity, agent access, and each action. ## Linked Issues or Issue Description **Problem or motivation** Paperclip has a Daytona sandbox provider for its own execution infrastructure. It lacks a normal Apps connection for agents to manage an operator's Daytona account. Reusing the server's provider credential would bypass normal connection ownership and action permissions. **Proposed solution** Add a Daytona connection with personal or shared vault credentials. Generate its action catalog from the official platform and Toolbox API specifications. Use the existing run-bound gateway, grants, action policies, approvals, revocation, and audit paths. Sandbox IDs come from Daytona; tools need no Paperclip task or lease ID. **Alternatives considered** A four-action diagnostic subset cannot support general provider work. Launching the provider CLI would expose host filesystem behavior. Native OAuth is not included because a supported third-party registration path was not verified. The native method uses an organization API key. Existing Composio setup is a separate possible OAuth route and is not qualified by this change. **Roadmap alignment** This extends the existing Apps and Connections provider coverage in `ROADMAP.md`. It uses that system's credential and permission model. GitHub searches found no existing Daytona Apps connector PR or issue. ## What Changed - Add the Daytona catalog entry, provider source override, official theme logos, permission review, and setup documentation. - Generate 274 HTTP actions: 169 platform and 105 Toolbox operations. Record two WebSocket upgrades separately; do not advertise them as HTTP tools. Record source URLs and hashes. - Add provider-focused execution for sandboxes, snapshots, volumes, files, Git, commands, computer use, and account resources. Provider authority still limits which endpoints accept an organization key. - Validate action arguments. Resolve Toolbox targets through the fixed platform API. Check sandbox identity and organization before using an approved Daytona proxy. Keep normal guarded network requests and vault resolution. - Transfer file bytes without reading or writing host files. Share one caller deadline across prerequisite reads, dispatch, and response reading. Bound requests and responses. Do not automatically retry writes with unknown outcomes. Redact the selected credential from results and errors. - Classify credential access, access changes, interactive input, command execution, file permissions, and deletion (including TTL and auto-delete) as destructive actions. Keep new and changed actions under catalog review. - Upgrade saved catalogs and retire the earlier diagnostic names. Hide retired actions from the UI and agent discovery even when provider refresh fails. Preserve existing action choices and historical records. Reject stale same-name contracts during agent discovery and dispatch before a board refresh. - Add database-backed gateway and catalog-upgrade regressions, schema generator tests, a browser setup check, and both capability map updates. ## Verification - Passed on the review-fix head: 57 focused Vitest cases (18 Daytona database/client cases, five HTTP boundary cases, and 34 shared catalog cases), four generator tests, `pnpm -r typecheck`, and `pnpm build`. The five HTTP cases use a real local server through the pinned production transport. The normal browser setup check and 17 generator/artwork cases passed on the initial PR head; those UI and artwork paths are unchanged. - Passed on this branch: brand asset validation, token gates, map structure checks, and `git diff --check`. All latest-head GitHub checks pass on `ea979ccb3a64dc9508807823540f935c4316ea35`. Apex is 5/5, with all five findings addressed and zero unresolved threads. The branch has no merge conflicts. - The initial catalog-generation command could not find the external research corpus. The supported `--definitions-only` mode regenerated the definitions successfully. Unrelated generated drift was excluded. - An earlier full local Vitest attempt on the preview branch failed when bundled PostgreSQL could not start on macOS. After replay onto current master, all three unchanged event-sequencing cases pass with bundled PostgreSQL; the earlier startup cause remains uncertain. - The first full-suite command on this branch used my external test database override. Chat fixtures require a current migrated schema and failed because `agents.lifecycle_state` was absent in that disposable database. A focused comparison reproduces failure with the override and passes with normal setup. That attempt was stopped, and the full suite restarted without the override. Focused Daytona cases use their own migrated PostgreSQL 16 databases. - The clean local full-suite attempt recorded embedded PostgreSQL startup failures in two unchanged native-runtime cases and two failures in unchanged Git fixtures. It was stopped after these failures were isolated; no full local suite pass is claimed. The 15 matching native-runtime cases pass separately. The Git cases fail with the local `init.defaultBranch=main` setting and pass with `GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=init.defaultBranch GIT_CONFIG_VALUE_0=master` limited to the test command. No global Git setting was changed. Full Linux CI is green. - Fixtures use real database persistence and run-bound gateway sessions with provider responses replaced by fixtures. They cover personal/shared vault ownership, reads and writes, file bytes, Off policies, revocation, organization mismatch, untrusted proxy rejection, output bounds, saved catalog upgrades, failed refresh, and permission preservation. - The first Apex review found five valid issues: multipart transport compatibility, destructive classification, caller deadlines, audit filters, and stale saved contracts. All five were fixed with regressions before the second review. A typecheck then found the nullable saved schema hash; admission now accepts that stored type and rejects null as stale. - The browser check covers setup controls without submitting a provider key. No real Daytona account, provider write, native OAuth flow, or agent model run is qualified. Live provider read/write proof remains pending a test account. ## Risks - Daytona keys have broad Toolbox authority, including keys with no selected resource scopes. Only assign this connection to trusted agents and review its action permissions. - Remote writes or commands can continue after a timeout. Calls do not automatically retry an uncertain outcome. - The bridge targets Daytona Cloud. Proxy hosts are restricted; an unrecognized future regional host fails closed. - Files and responses have an 8 MiB bound. Each action has one caller deadline, capped at 30 seconds across all provider requests and response reading. Interactive WebSocket sessions are not exposed as HTTP actions. - The generated JSON snapshot exceeds 1,000 lines because it holds the provider input contracts. Generator logic and execution code remain in separate small modules. Updates require explicit regeneration and catalog review. - No database migration or lockfile change is required. ## Model Used OpenAI Codex, GPT-6. The runtime identifies the model family but does not expose the exact backend model ID or context window. Used reasoning, repository inspection, code editing, shell tools, database verification, and browser tests. ## 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: Paperclip <noreply@paperclip.ing>
7.9 KiB
Daytona connection
Daytona uses the normal Apps connection, selected personal/company credential, agent installation, action policy, gateway, revocation and audit paths. The API key stays in the instance vault. The connector does not borrow sandbox-provider environment credentials or another connection's credential.
Sign-in tokens are never reused as resource tokens; id.paperclip.ing never stores resource tokens; no connections hub on the ID service.
Connect and test
Choose Connectors → Daytona → Add key, select access, and enter a Daytona
organization API key. Give that key the read, write, and delete permissions for
the resources you intend to manage. An optional organization ID under Advanced
pins the credential to its organization. Setup verifies GET /api-keys/current.
Use the saved connection's ordinary Permissions screen to choose agents and set
actions to Allowed, Ask first, or Off.
This is a provider-focused connector. Sandbox IDs and names come from Daytona; no Paperclip task, run, or environment lease is required. Granting access to this connection grants access to the provider resources its credential can reach. Some user/account and administrator operations require extra provider authority or user authentication and will reject an API key. Paperclip does not fall back to another identity when Daytona denies access.
Complete published HTTP action catalog
The catalog contains 274 actions from Daytona's published specifications: 169 platform API operations and 105 Toolbox operations. It includes sandbox creation, start/stop/recovery/deletion, snapshots, volumes, files and transfers, Git, commands and sessions, computer use, organization/account administration, and provider telemetry queries. These provider telemetry tools do not emit Paperclip first-party telemetry.
Actions have provider names such as daytona_api_list_sandboxes,
daytona_api_create_sandbox, daytona_toolbox_execute_command, and
daytona_toolbox_download_file. The generated schemas retain the provider's
path/query/body arguments and required fields. Toolbox actions also take a
sandboxId. Returned provider objects are not reduced to Paperclip task data.
The selected connection credential is redacted from results and errors.
| Action group | Permission classification |
|---|---|
| Ordinary reads, file downloads, and read-only lookups | Read |
| Resource creation, file/Git changes, lifecycle and configuration changes | Write |
| Deletion (including TTL/auto-delete), command/code/interactive input, reset/restore, secret/credential access, signed access links and file/account access changes | Destructive |
The source inventory also records two WebSocket upgrade endpoints: interactive interpreter execution and PTY connection. These are streaming protocol connections, not ordinary HTTP/MCP request-response tools. They are not advertised as nonfunctional actions. The command/code and session tools provide the corresponding request-response execution paths.
The API and Toolbox specification sources and SHA-256 hashes are recorded in
server/src/services/daytona/operations.generated.json. Regenerate with:
node scripts/generate-daytona-tools.mjs
node --test scripts/generate-daytona-tools.test.mjs
The large generated JSON file is one provider contract snapshot. Its generator and invocation implementation stay separate from it; no runtime network discovery or unbounded schema copying occurs on the server's startup path.
Credential and transport boundary
The platform API endpoint is fixed to https://app.daytona.io/api. Toolbox
calls resolve the sandbox through that API, verify its exact ID/name and
organization, and accept only reviewed Daytona cloud proxy hostnames and the
/toolbox path. Every request still uses the normal DNS-pinned egress guard.
Redirects are rejected. Action arguments cannot replace Authorization or the
organization header. Generic credential export rejects Daytona.
File uploads take base64 bytes; downloads return bytes with content type and length. The connector never reads a local host file path, writes host files, launches the Daytona CLI, or executes commands on the Paperclip server. Provider commands execute inside the selected Daytona sandbox. Reads and transfers have an 8 MiB bound. An action shares one deadline across identity, target lookup, dispatch, and response reading: the caller's budget, capped at 30 seconds. Expiry blocks later dispatches and cancels active requests. Mutations are never retried automatically. A timed-out command or write can still be running at the provider; inspect it before retrying.
Daytona does not provide a diagnostic-only runtime key: every valid organization key can access running sandboxes through the Toolbox, even with no selected resource scopes. Treat this as broad provider access. Agent assignment and action permissions enforce the capability boundary; a read grant is not permission to run a command or delete a sandbox.
OAuth research
The native connection currently uses an API key. Daytona's CLI supports browser sign-in, but its published configuration uses Daytona's own first-party AuthKit clients. The public issuer metadata does not advertise client registration, and a supported third-party OAuth app registration path was not verified. The connector does not borrow those client IDs, copy CLI sign-in tokens, or invent a native OAuth consent flow.
Composio advertises managed OAuth for its Daytona toolkit. That is a separate existing provider route: connect Composio through its ordinary connection flow, then configure its Daytona app. Its auth configuration and account entitlements must be verified through that provider's live setup. This native connector does not require Composio or forward its credential to Composio. A marketing listing is not proof that this instance completed Daytona OAuth.
Validation and limits
Database-backed tests exercise company and personal vault ownership, real run-scoped gateway reads and writes, file bytes, action denial, revocation, foreign-account rejection, untrusted proxy rejection, all generated argument schemas, and bounded/sanitized errors. Generator tests account for HTTP operations and protocol upgrades and preserve recursive input definitions.
These fixtures do not qualify a real Daytona account. Live provider proof is pending an operator connecting a key and trying an allowed read and write. No platform key or live provider credential is installed by this change. Existing saved connections must review the expanded catalog through normal Permissions; new actions do not inherit approval from the previous four diagnostic actions. Opening a saved Daytona connection upgrades an outdated catalog. The earlier Paperclip-specific actions are retired and hidden from both Permissions and agent discovery, even if a provider outage prevents refresh. Historical rows remain for audit, and newly discovered actions require review. Agent discovery and dispatch also check same-name saved contracts against the deployed schema and risk classification. An outdated action cannot execute while it waits for a human to open Permissions and review the change.
The HTTP boundary tests use a real local server and the pinned transport to check multipart uploads, audit filter encoding, response cancellation, and unrelated request responsiveness. The provider network/TLS leg is simulated; these checks do not replace live account proof.
Provider research verified 2026-10-15:
- https://www.daytona.io/docs/en/api-keys/
- https://www.daytona.io/docs/en/tools/api/
- https://www.daytona.io/docs/openapi.json
- https://www.daytona.io/docs/toolbox-openapi.json
- https://github.com/daytona/clients/tree/main/cli/mcp
- https://composio.dev/toolkits/daytona
- https://www.daytona.io/brand
Official square logo assets are copied unchanged from
https://framerusercontent.com/images/k2z1jCEWqymEd7reVoRseEVMFHU.svg and
https://framerusercontent.com/images/JjrFl7J2k84ANwYg3pD9Hwilc.svg.