Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-03 01:27:09 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
4e97daafa06a54f02027335437c4f48e50b84236
PaperClipAI/doc/connections/UNIKRAFT.md
T
Devin Foley 059ae49cab feat(connections): add Unikraft Cloud connection (#17139) 
## 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
2026-10-22 15:14:26 -07:00

187 lines
8.9 KiB
Markdown
Raw Blame History

# Unikraft connection
Unikraft Cloud runs unikernel micro-VMs ("instances") across regional metros.
Its connection uses the normal Apps connection, selected personal/company
credential, agent installation, action policy, gateway, revocation and audit
paths. The API token stays in the instance vault. The connector does not borrow
`unikraft login` state, `UKC_TOKEN` environment variables, 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.
## Vendor
| Item | Value |
| --- | --- |
| Product | Unikraft Cloud (formerly KraftCloud) |
| API reference | https://unikraft.com/docs/api/platform/v1 |
| Specification | https://github.com/unikraft-cloud/openapi (`platform.json`, `plugins/sandbox.json`) |
| Metros | https://unikraft.com/docs/platform/metros |
| Tokens | https://unikraft.com/docs/sdks/overview#authentication |
| Console | https://console.unikraft.com |
| Hosted MCP server | None. Unikraft's MCP guides describe hosting your own MCP server on Unikraft. |
## Transport and auth
| Axis | Value |
| --- | --- |
| Transport | `rest_api`, executed by Paperclip's native provider bridge |
| Authentication | `api_key`, sent as `Authorization: Bearer <token>` |
| OAuth client ownership | Not applicable; Unikraft offers no third-party OAuth |
| Credential source | Paperclip vault |
| Grant identity | `organization` or `user` |
Unikraft Cloud has no global platform endpoint. Each metro serves its own API at
`https://api.<metro>.unikraft.cloud/v1/...`. The reviewed specification
publishes five metros: `dal`, `fra`, `sfo`, `sin` and `was`. Every action accepts
an optional `metro` argument limited to that list; actions that omit it use the
connection's default metro (Frankfurt unless changed under **Advanced**). The
token is never sent to any other host. Legacy `*.kraft.cloud` hosts, which
Unikraft documents as nearing end of life, are not reachable through this
connection.
The saved connection URL, `https://controlplane.unikraft.cloud/v1`, identifies
the connection only. Actions use the metro hosts above.
## Connection flow (mandatory)
```mermaid
sequenceDiagram
actor Operator
participant UI as Paperclip UI
participant Server as Paperclip server
participant Vault as Instance vault
participant Metro as Unikraft metro API
actor Agent
Operator->>UI: Connectors, Unikraft, Add key
UI->>Server: POST /api/companies/{companyId}/tools/apps/connect (galleryKey unikraft, token, optional default metro)
Server->>Vault: Store the token as a company or user secret
Server->>Metro: GET /v1/users/quotas with the stored token
Metro-->>Server: status success
Server-->>UI: Generated catalog of 105 actions
Operator->>UI: Choose agents and action permissions
Agent->>Server: Gateway tool call, for example unikraft_get_instances
Server->>Server: Check grant, revocation, policy and saved contract
Server->>Metro: Request to api.{metro}.unikraft.cloud with the vaulted token
Metro-->>Server: JSON result
Server-->>Agent: Result with the token redacted
```
Paperclip endpoints used: `GET /api/companies/{companyId}/tools/apps/unikraft/preflight`,
`POST /api/companies/{companyId}/tools/apps/connect`,
`POST /api/companies/{companyId}/tools/apps/{connectionId}/finish`,
`GET /api/tool-connections/{connectionId}/catalog`, and the run-bound tool gateway.
There is no OAuth handoff, so `GET /api/tools/oauth/callback` is not used.
## Administrator setup (mandatory)
1. Sign in to the [Unikraft Cloud console](https://console.unikraft.com) and
create an API token for the organization agents should manage.
2. In Paperclip choose **Connectors → Unikraft → Add key**, choose who can use
the credential, and paste the token.
3. Optional: under **Advanced**, change the default metro.
4. On the saved connection's **Permissions** screen, choose agents and set
actions to Allowed, Ask first, or Off.
A token acts for its whole organization in every metro. Unikraft does not offer
narrower token permissions, so agent assignment and action permissions enforce
the capability boundary. Revoke a token in the Unikraft console, then remove or
reconnect the Paperclip connection.
## Resource filters
There are no provider-enforced resource filters. `requiredResourceFilters`
(`organization`, `metro`, `instance`) is reviewed metadata. The bridge enforces
only that requests go to a published metro and that path arguments cannot
traverse to another route.
## Actions
The catalog contains **105 actions** generated from Unikraft's published
specifications at commit `5dd107ea1cd8716b83cb86a83ed2a6ee46f99b5b`:
89 platform API operations and 16 sandbox plugin operations.
| Group | Examples | Classification |
| --- | --- | --- |
| Reads, logs, metrics, history and waits | `unikraft_get_instances`, `unikraft_get_instance_logs_by_uuid`, `unikraft_wait_instances`, `unikraft_sandbox_read_file` | Read |
| Creation, updates, start, attach, clone and pinning | `unikraft_create_instance`, `unikraft_update_service_group_by_uuid`, `unikraft_start_instances`, `unikraft_sandbox_write_file` | Write |
| Deletion, stop, suspend, detach, unpin, and sandbox command execution, signals and stdin | `unikraft_delete_volume_by_uuid`, `unikraft_stop_instances`, `unikraft_sandbox_run_command` | Destructive |
Platform actions keep Unikraft's operation names (`unikraft_<operation>`).
Sandbox plugin actions are `unikraft_sandbox_<operation>` and take an
`instance` (name or UUID); they call
`https://api.<metro>.unikraft.cloud/v1/instances/<instance>/plugins/sandbox`.
Many Unikraft operations select batch targets with a JSON body, including on
GET and DELETE; the bridge sends those bodies as published.
`unikraft_sandbox_wait_for_command_with_timeout` returns
`{ "status": "running", "timedOut": true }` when Unikraft reports that the
command is still running at the timeout (HTTP 408), so an agent can wait again.
The bridge lives in `server/src/services/connectors/unikraft/`.
The audit event stream (`GET /v1/audit`) is server-sent events, not a
request/response action. It is recorded in the generated inventory and not
advertised as a tool.
The specification sources and SHA-256 hashes are recorded in
`server/src/services/connectors/unikraft/operations.generated.json`. Regenerate with:
```sh
node scripts/generate-unikraft-tools.mjs
node --test scripts/generate-unikraft-tools.test.mjs
```
The generator pins a reviewed commit because the specification repository has
no tags or releases. Updating it requires explicit regeneration and catalog
review: saved connections quarantine new and changed actions until reviewed.
## Wizard path
The ordinary key wizard: **Access → Connect**. Setup asks only for the token.
The default metro is an optional select under **Advanced**. Setup completes when
`GET /v1/users/quotas` on the default metro confirms the token.
## Governance defaults
- Risk tier S4: the normal catalog includes deletion and arbitrary command
execution inside sandboxes.
- Every discovered action is enabled when setup finishes, under the shared
connection access rules; operators restrict actions on Permissions.
- New and changed actions after a catalog update are quarantined until reviewed.
- Agents cannot export the token; generic credential export rejects Unikraft.
- Responses and request bodies are bounded at 8 MiB. Each action has one caller
deadline, capped at 30 seconds. Mutations are never retried automatically; a
timed-out write can still complete at the provider.
## Manifest
Defined in `scripts/app-definition-overrides/unikraft.json` and generated into
`packages/shared/src/app-definitions/unikraft.json`: slug `unikraft`, category
`developer`, one method `api-token` (`rest_api`, `api_key`, `customer`), and a
`metro` select tenant field.
## Validation hook
Database-backed tests exercise company and personal vault ownership, real
run-scoped gateway reads, writes, deletions and sandbox commands, default and
per-call metros, rejection of unpublished metros and path traversal, Off
policies, revocation, stale-contract blocking, credential export denial, all
generated argument schemas, and bounded/sanitized errors. HTTP boundary tests
send GET and DELETE JSON bodies through the real pinned transport to a local
server. Generator tests cover streaming endpoints, shared parameter references,
unsigned integer formats and risk classification.
These fixtures do not qualify a real Unikraft account. Live provider proof is
pending an operator connecting a token and trying an allowed read and write
(`liveProof: not-run`).
## Brand
`ui/public/brands/apps/unikraft.svg` is Unikraft's gradient mark from the
official documentation site, copied from
`https://raw.githubusercontent.com/unikraft-cloud/docs/d8acfcefe8186badac84d5308d641a1c1b5b239e/public/unikraft.svg`
with editor metadata removed. One asset serves both themes. Unikraft publishes
no brand kit.
Provider research verified 2026-10-15.
Reference in new issue View Git Blame Copy Permalink