Devin Foley
059ae49cab
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Apps connections give agents governed access to external services through vault credentials, grants, action policies, the tool gateway, and audit. > - Unikraft Cloud runs unikernel micro-VMs, services, and volumes across regional metros, and it offers a sandbox plugin for commands and files. > - Unikraft is not in the catalog. It has no hosted MCP server, so the generic "Connect your own MCP server" flow cannot reach it. > - Daytona (#16483) added a native REST pattern for this case: a catalog generated from the provider's published OpenAPI specifications and executed through the gateway. > - This pull request adds Unikraft on that pattern and moves the shared native-provider code into one registry, so the shared connection code does not name each provider. > - The benefit is governed agent access to all published Unikraft actions, with the token kept in the vault and sent only to published Unikraft hosts. ## Linked Issues or Issue Description Refs #16483 **Problem or motivation** Teams that run workloads on Unikraft Cloud want their agents to list instances, read logs, deploy and scale services, and run commands in sandboxes. Unikraft is not in the Apps catalog. Unikraft has no hosted MCP server, so operators cannot connect it through the remote MCP flow. **Proposed solution** Add a native Unikraft connection. Generate its actions from Unikraft's official OpenAPI specifications for the platform API and the sandbox plugin. Pin the specifications to a reviewed commit. The operator connects an API token. The token stays in the vault and goes only to the five published metro hosts. Every action takes an optional metro. Actions without a metro use the connection's default metro, which the operator can change under Advanced. **Alternatives considered** A catalog-only AppDefinition was not possible because no hosted MCP endpoint exists. Wrapping the `unikraft` CLI was rejected because it would expose host filesystem behavior and CLI login state. A second copy of the Daytona bridge was rejected; the shared transport and catalog contract are now one module with a provider registry. **Roadmap alignment** This extends the existing Apps and Connections provider coverage. It uses the existing credential, grant, policy, gateway, and audit model. It does not overlap planned core work. ## What Changed - Added `scripts/generate-unikraft-tools.mjs` and its tests. The generator reads the platform and sandbox plugin specifications at commit `5dd107ea1cd8716b83cb86a83ed2a6ee46f99b5b`, resolves shared parameters, records source SHA-256 hashes, and writes `server/src/services/unikraft/operations.generated.json`. - The catalog has 105 actions: 89 platform operations and 16 sandbox plugin operations. The server-sent audit event stream is recorded in the inventory and is not advertised as an action. - Classification: GET operations and sandbox reads and waits are reads. Delete, stop, suspend, detach, unpin, and sandbox command execution, signals, and stdin are destructive. All other operations are writes. - Added `server/src/services/connectors/unikraft/client.ts` and its generated catalog. It validates arguments against the generated schemas, accepts only published metros, rejects path traversal, sends JSON bodies on GET and DELETE as the specification requires, and verifies the token with `GET /v1/users/quotas`. A sandbox wait that times out (documented HTTP 408) returns a still-running result instead of a failure. - Moved the bounded, credential-redacting HTTP sender and the catalog contract helpers from `daytona.ts` to `native-rest-client.ts`. Added `native-provider-catalogs.ts`. `tool-access.ts`, the `tool-access/catalog` and `token-broker` modules, `connectors/tool-policy.ts`, and `tool-gateway.ts` now use this registry instead of Daytona-specific checks. Daytona behavior does not change. - Added the Unikraft definition source, the generated definition, the brand mark and manifest entry, and the permission review (`liveProof: not-run`). - Added `doc/connections/UNIKRAFT.md` with a sequence diagram, endpoints, setup, actions, and limits. Updated the connections README, the permission audit, and both capability maps. - Tests: definition shape, database-backed gateway reads, writes, deletes, and sandbox commands for personal and shared grants, default and per-call metros, rejection of unpublished metros and traversal, Off policies, revocation, stale-contract blocking, credential export denial, schema validation for all actions, pinned-transport tests for GET and DELETE bodies, and a browser setup check. ## Verification - `pnpm exec vitest run packages/shared/src server/src/__tests__/unikraft-connection.test.ts server/src/__tests__/unikraft-http-boundary.test.ts server/src/__tests__/daytona-connection.test.ts server/src/__tests__/daytona-http-boundary.test.ts server/src/__tests__/tool-access-service.test.ts server/src/__tests__/tool-gateway-service.test.ts server/src/__tests__/tool-gateway.test.ts ui/src/pages/apps/AppsConnect.test.tsx ui/src/pages/apps/Browse.test.tsx ui/src/lib/app-brand-assets.test.ts` plus `connector-tool-policy` and `tool-catalog-publication`: all passed after the rebase onto the split tool-access modules. - `node --test scripts/generate-unikraft-tools.test.mjs scripts/generate-daytona-tools.test.mjs scripts/app-brand-validation.test.mjs`: 20 passed. - `node scripts/check-app-brand-assets.mjs`, `node scripts/check-maps.mjs`, and `git diff --check`: passed. - `pnpm --filter @paperclipai/shared typecheck`, `pnpm --filter @paperclipai/server typecheck`, and `pnpm --filter @paperclipai/ui typecheck`: clean. - `npx playwright test --config tests/e2e/playwright.config.ts tests/e2e/unikraft-connector.spec.ts tests/e2e/daytona-connector.spec.ts`: 2 passed. - `node scripts/generate-unikraft-tools.mjs` regenerates the committed catalog with the recorded hashes. - Manual: on a local instance, open Connectors, search for Unikraft, and select **Add key**. Confirm the icon, the password field, the key guidance, and the default metro select under **Change**. - Not verified: a real Unikraft account. Live provider read and write proof is pending. ## Risks - A Unikraft token acts for the whole organization in every metro. Unikraft offers no narrower token permissions. Assign only trusted agents and review action permissions. - Sandbox actions run arbitrary commands inside the selected instance. They are classified as destructive. - A timed-out write can still complete at the provider. The bridge does not retry writes automatically. - New metros fail closed until the specification is regenerated and reviewed. Legacy `*.kraft.cloud` hosts are not reachable. - The Daytona refactor moves code without behavior changes. All Daytona tests pass without edits. - The generated JSON snapshot is large because it holds the provider input contracts. No migration or lockfile change is required. ## Model Used - Claude Opus 5.5 (Anthropic), model ID `claude-opus-5-5`, 1M context window, used through Claude Code with tool use (shell, file editing, web research, 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 - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
12 KiB
Connection setup — agent access
Product map: Connection setup.
Feature ID: connection-setup.
Review date: 2026-10-12. Source commit: f981fa3cc10cb8663a87dec60345fbff46d54d0a.
This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.
Prompt Injection Prevention reuses shared OpenRouter API-key setup directly from Settings → Connections. It adds no Apps provider or transport. Credential ownership and audience rules are the existing connection rules; saving a connection alone does not activate the service. See service configuration.
catalog
Capability ID: connection-setup/catalog.
Review: baseline.
API: present — representative operation IDs:
POST /runtime-tools/connections/search.
Agent access: available — Native connections_search / run-bound runtime-tools MCP.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
Evidence: source-only —
implementation at the reviewed
commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Runtime tool broker searches available services without granting connection administration.
Notebook is internally gated by enablePaperclipNotebook (default off, no settings toggle). Disabled instances hide setup/discovery and deny curated Notebook dispatch and publishing; local removal and grant revocation remain available.
The connector catalog declares the feature key. Shared availability checks use the saved application identity. Notebook owns publication and file uploads; Paperclip uses its existing MCP tools and OAuth flow.
Notebook source addition: paperclip-notebook is discoverable through
connections_search and requestable through connection_request. Its standard
personal authorization requests read, write, share, and delete scopes. Notebook
page ownership remains enforced by the remote service; a client-supplied agent
label grants no authority. The direct MCP connection requires no Cloud instance
enrollment. Notebook fixture evidence: verified against disposable PostgreSQL 18
with controlled MCP responses — Notebook integration
and generic OAuth fixture.
Ordinary MCP calls retain assignment and Allowed / Ask first / Off policy.
Live deployed publication and hosted/self-hosted OAuth remain release checks.
identity-and-access
Capability ID: connection-setup/identity-and-access.
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/tools/connections.
Agent access: restricted — Board setup API plus agent connection_request.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
Evidence: source-only —
implementation at the reviewed
commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Selecting account ownership/eligible agents is management; an agent can request the intended connection.
credentials
Capability ID: connection-setup/credentials.
Review: baseline.
API: present — representative operation IDs:
POST /api/agents/me/connections/{connectionId}/start-authorization.
Agent access: partial — Scoped start-authorization/request flow; human provider login.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
Evidence: source-only —
implementation at the reviewed
commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: An initiation endpoint exists; it is not authorization to complete the person's credential flow.
Braintrust uses the existing setup/request path for US and EU OAuth and API-key
methods. OAuth requests only mcp; provider authorization follows the selected
account's permissions. Personal invocation credentials must belong to their
user, while shared identities use company credentials. Region and explicit
method survive resume and reconnect. Agents use assigned tools through the
run-scoped gateway and receive no Braintrust token. See
Braintrust for method keys and the
qualification matrix. Separate live US OAuth proof passed browser authorization,
49-tool discovery, bounded read, synthetic dataset insert/readback through actual
process-agent runs and gateway sessions, catalog refresh, OAuth reconnect, local
removal, post-removal denial, and structural API/log redaction. US API-key and
both EU methods remain not-run against real accounts. Live token expiry/refresh,
remote OAuth revocation, and native CLI automatic capability delivery remain
unqualified. Public metadata probes performed no registration or account
authorization; fixtures do not establish live proof for the remaining methods.
Daytona native setup uses an organization API key in the selected personal or company vault grant. It does not borrow sandbox-provider credentials or CLI login tokens. Agents use assigned provider tools through the normal run-bound gateway; they cannot export the key. Database-backed fixtures cover selected vault ownership and gateway reads/writes with provider responses replaced by fixtures. Real provider authentication remains unqualified.
Unikraft native setup uses an organization API token in the selected personal or
company vault grant. It does not borrow unikraft login state or UKC_TOKEN.
Agents use assigned provider tools through the run-bound gateway, limited to the
published metro hosts, and cannot export the token. Database-backed fixtures
cover vault ownership and gateway reads, writes and sandbox commands with
fixture provider responses. Real provider authentication remains unqualified.
handoff
Capability ID: connection-setup/handoff.
Review: baseline.
API: present — representative operation IDs:
POST /api/connection-intents/{interactionId}/complete.
Agent access: restricted — Addressed-user completion; server wakes the agent with
updated access.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
Evidence: source-only —
implementation at the reviewed
commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: OAuth/callback and addressed-user checks are deliberate separate boundaries.
draft-recovery
Capability ID: connection-setup/draft-recovery.
Review: baseline.
API: present — representative operation IDs:
POST /api/connection-intents/{interactionId}/phase.POST /api/tool-connections/{connectionId}/reconnect.
Agent access: restricted — Human setup/resume APIs; agent request state and
continuation.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
Evidence: source-only —
implementation at the reviewed
commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Board setup recovery exists. Browser-only navigation state is not automatically an agent API gap.
task-request
Capability ID: connection-setup/task-request.
Review: baseline.
API: present — representative operation IDs:
POST /runtime-tools/connections/request.
Agent access: available — Native connection_request / run-bound runtime-tools MCP.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
Evidence: source-only —
implementation at the reviewed
commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: This is the existing agent bridge for human-required setup; do not invent a second approval system.
channel-setup
Capability ID: connection-setup/channel-setup.
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/chat-endpoints.
Agent access: restricted — Board channel management; agent requests required setup.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
Evidence: source-only —
implementation at the reviewed
commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Provider endpoint, represented agent and linked sender are operator choices today.
Internal recovery: Telegram discovery walks bounded pages at startup. Configuration commits only queue the changed connection; durable maintenance rows supply retry deadlines. Inactive subscription repair is parked until an endpoint or connection change. This creates no agent management permission or new API. Local database-backed provider-fixture tests in channel integration cover recovery, rollback, retries and idle query silence; they do not establish live provider or agent access.
failure
Capability ID: connection-setup/failure.
Review: baseline.
API: present — representative operation IDs:
POST /api/tool-connections/{connectionId}/health-check.
Agent access: partial — Agent observes connection tool errors; board repair APIs.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
Evidence: source-only —
implementation at the reviewed
commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Error reporting and human repair exist; no generic agent permission to reconnect accounts.