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-11-11 13:24:55 +01:00 · 2026-10-22 15:14:26 -07:00
1 parent def4726bea
commit 059ae49cab
@@ -0,0 +1,76 @@
+{
+  "schemaVersion": 1,
+  "slug": "unikraft",
+  "name": "Unikraft",
+  "description": "Manage Unikraft Cloud instances, services, volumes, images, certificates, autoscaling, and sandbox commands and files.",
+  "categories": [
+    "developer"
+  ],
+  "featured": false,
+  "urlPatterns": [
+    "https://console.unikraft.com/*",
+    "https://*.unikraft.cloud/*"
+  ],
+  "methods": [
+    {
+      "key": "api-token",
+      "label": "Connect Unikraft",
+      "transport": "rest_api",
+      "auth": "api_key",
+      "ownershipModes": [
+        "customer"
+      ],
+      "whenToUse": "Manage resources and run sandbox commands in your Unikraft Cloud organization.",
+      "defaults": {
+        "serverUrl": "https://controlplane.unikraft.cloud/v1"
+      },
+      "guidanceMd": "Connect a Unikraft Cloud API token. All published platform API and sandbox plugin actions are available; your action policies control which ones agents can use. Each action can target any Unikraft Cloud metro, and uses the default metro when it does not name one.",
+      "riskTier": "S4",
+      "credentialFields": [
+        {
+          "key": "authorization",
+          "label": "Unikraft API token",
+          "type": "password",
+          "required": true,
+          "placeholder": "Enter Unikraft API token",
+          "secret": true
+        }
+      ],
+      "keyPlacement": {
+        "location": "header",
+        "name": "Authorization",
+        "prefix": "Bearer "
+      },
+      "tenantFields": [
+        {
+          "key": "metro",
+          "label": "Default metro",
+          "type": "select",
+          "advanced": true,
+          "defaultValue": "fra",
+          "helperMd": "Used to verify the token and for actions that do not name a metro.",
+          "options": [
+            { "value": "dal", "label": "Dallas (dal)" },
+            { "value": "fra", "label": "Frankfurt (fra)" },
+            { "value": "sfo", "label": "San Francisco (sfo)" },
+            { "value": "sin", "label": "Singapore (sin)" },
+            { "value": "was", "label": "Washington, DC (was)" }
+          ]
+        }
+      ],
+      "requiredResourceFilters": [
+        "organization",
+        "metro",
+        "instance"
+      ],
+      "consoleLinks": {
+        "keys": "https://console.unikraft.com",
+        "docs": "https://unikraft.com/docs/sdks/overview#authentication"
+      },
+      "warnings": [
+        "This connection can run commands in sandboxes, read and write sandbox files, start and stop instances, and delete instances, volumes, and other resources. Select trusted agents and set action permissions before use. Your Unikraft API token stays in the vault."
+      ]
+    }
+  ],
+  "docsUrl": "https://unikraft.com/docs/api/platform/v1"
+}
@@ -12,7 +12,7 @@ const snake = value => value.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^a

 /** Retain only reachable input definitions, rather than copying the whole API
 * schema into every action. Provider response schemas are not tool inputs. */
-function inputSchema(value, schemas) {
+export function inputSchema(value, schemas) {
  const definitions = {};
  function visit(node) {
    if (Array.isArray(node)) return node.map(visit);
@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { inputSchema } from "./generate-daytona-tools.mjs";
+
+// The official specification repository has no tags or releases. Pin a
+// reviewed commit so a provider update needs explicit regeneration and review.
+const commit = "5dd107ea1cd8716b83cb86a83ed2a6ee46f99b5b";
+const sources = {
+  platform: `https://raw.githubusercontent.com/unikraft-cloud/openapi/${commit}/platform.json`,
+  sandbox: `https://raw.githubusercontent.com/unikraft-cloud/openapi/${commit}/plugins/sandbox.json`,
+};
+const verbs = new Set(["get", "post", "put", "patch", "delete"]);
+const snake = value => value.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+  .replace(/[^a-zA-Z0-9]+/g, "_").toLowerCase();
+// Requests that wait, read, or list without changing provider state.
+const readOnlyPosts = new Set(["ReadFile", "ReadRawFile", "WaitForCommand", "WaitForCommandWithTimeout"]);
+// Reversible but disruptive lifecycle changes, and code execution in a sandbox.
+const destructiveOperations = /^(Stop|Suspend|Detach|Unpin)|^(RunCommand|SignalCommand|WriteCommandStdin)$/;
+
+function parameterDefinition(parameter, spec) {
+  if (!parameter.$ref) return parameter;
+  const prefix = "#/components/parameters/";
+  if (!parameter.$ref.startsWith(prefix)) throw new Error(`Unsupported parameter reference: ${parameter.$ref}`);
+  const resolved = spec.components?.parameters?.[parameter.$ref.slice(prefix.length)];
+  if (!resolved) throw new Error(`Missing parameter: ${parameter.$ref}`);
+  return resolved;
+}
+
+/** Ajv does not define OpenAPI's unsigned integer formats. Keep their sign
+ * constraint instead of an unknown format that would not validate anything.
+ * Some unsigned fields document -1 as a sentinel (for example, the longest
+ * drain time); keep that value valid. */
+function unsignedFormats(node) {
+  if (Array.isArray(node)) return node.forEach(unsignedFormats);
+  if (!node || typeof node !== "object") return;
+  if (/^uint(8|16|32|64)$/.test(node.format ?? "")) {
+    delete node.format;
+    node.minimum ??= /(^|\s)-1\b/.test(node.description ?? "") ? -1 : 0;
+  }
+  Object.values(node).forEach(unsignedFormats);
+}
+
+function streamingOperation(operation) {
+  return Object.values(operation.responses ?? {}).some(response => Object.hasOwn(response.content ?? {}, "text/event-stream"));
+}
+
+export function generateUnikraftCatalog(specs) {
+  const metros = (specs.platform?.servers ?? []).map(server => new URL(server.url).hostname.match(/^api\.([a-z0-9]+)\.unikraft\.cloud$/)?.[1])
+    .filter(Boolean).sort();
+  const tools = [];
+  const streaming = [];
+  for (const [kind, spec] of Object.entries(specs)) {
+    for (const [route, item] of Object.entries(spec.paths)) {
+      for (const [method, operation] of Object.entries(item)) {
+        if (!verbs.has(method)) continue;
+        if (!operation.operationId) throw new Error(`Missing operationId: ${kind} ${method} ${route}`);
+        const name = kind === "platform" ? `unikraft_${snake(operation.operationId)}` : `unikraft_${kind}_${snake(operation.operationId)}`;
+        // Server-sent event streams hold a connection open; they are not
+        // request/response actions. Keep them in the inventory so an update
+        // cannot silently lose an operation.
+        if (streamingOperation(operation)) {
+          streaming.push({ name, kind, path: route, method: method.toUpperCase(), transport: "server-sent-events" });
+          continue;
+        }
+        const properties = {}, required = [], parameters = [];
+        const groups = { path: { type: "object", properties: {}, required: [], additionalProperties: false },
+          query: { type: "object", properties: {}, required: [], additionalProperties: false },
+          headers: { type: "object", properties: {}, required: [], additionalProperties: false } };
+        for (const reference of [...(item.parameters ?? []), ...(operation.parameters ?? [])]) {
+          const parameter = parameterDefinition(reference, spec);
+          const group = parameter.in === "header" ? "headers" : parameter.in;
+          if (!groups[group]) throw new Error(`Unsupported parameter: ${name} ${parameter.in}`);
+          // Authorization comes from the selected connection, never an argument.
+          if (group === "headers" && /^(authorization|cookie|host)$/i.test(parameter.name)) continue;
+          groups[group].properties[parameter.name] = { ...(parameter.schema ?? {}),
+            ...(parameter.description ? { description: parameter.description } : {}) };
+          if (parameter.required) groups[group].required.push(parameter.name);
+          parameters.push({ name: parameter.name, group, style: parameter.style ?? "form", explode: parameter.explode ?? true });
+        }
+        for (const [group, schema] of Object.entries(groups)) {
+          if (!Object.keys(schema.properties).length) continue;
+          properties[group] = schema;
+          if (schema.required.length) required.push(group);
+        }
+        properties.metro = { type: "string", enum: metros, description: "Unikraft Cloud metro. Defaults to the connection's default metro." };
+        if (kind === "sandbox") {
+          properties.instance = { type: "string", minLength: 1, maxLength: 200, description: "Name or UUID of the instance running the sandbox plugin." };
+          required.push("instance");
+        }
+        const content = operation.requestBody?.content ?? {};
+        const bodyContentType = Object.hasOwn(content, "application/json") ? "application/json" : Object.keys(content)[0];
+        if (bodyContentType && bodyContentType !== "application/json") throw new Error(`Unsupported request body: ${name} ${bodyContentType}`);
+        if (bodyContentType) {
+          properties.body = content[bodyContentType].schema ?? {};
+          if (operation.requestBody.required) required.push("body");
+        }
+        const readOnly = method === "get" || readOnlyPosts.has(operation.operationId);
+        const destructive = !readOnly && (method === "delete" || destructiveOperations.test(operation.operationId));
+        const schema = inputSchema({ type: "object", additionalProperties: false, properties, required }, spec.components?.schemas ?? {});
+        unsignedFormats(schema);
+        tools.push({ name, kind, path: route, method: method.toUpperCase(), parameters,
+          ...(bodyContentType ? { bodyContentType } : {}),
+          title: operation.summary || operation.operationId,
+          description: operation.description || operation.summary || operation.operationId,
+          inputSchema: schema,
+          annotations: { readOnlyHint: readOnly, destructiveHint: destructive, idempotentHint: readOnly, openWorldHint: true } });
+      }
+    }
+  }
+  if (!metros.length) throw new Error("The platform specification lists no Unikraft Cloud metros");
+  const names = tools.map(tool => tool.name);
+  if (new Set(names).size !== names.length) throw new Error("Duplicate Unikraft action name");
+  return { metros, tools, streaming };
+}
+
+async function main() {
+  const inputIndex = process.argv.indexOf("--input-dir");
+  const inputDir = inputIndex < 0 ? undefined : process.argv[inputIndex + 1];
+  const specs = {}, provenance = {};
+  for (const [kind, url] of Object.entries(sources)) {
+    const raw = inputDir ? await readFile(path.join(inputDir, `unikraft-${kind}-openapi.json`))
+      : Buffer.from(await (await fetch(url)).arrayBuffer());
+    specs[kind] = JSON.parse(raw.toString("utf8"));
+    provenance[kind] = { url, sha256: createHash("sha256").update(raw).digest("hex") };
+  }
+  const output = { schemaVersion: 1, sources: provenance, ...generateUnikraftCatalog(specs) };
+  const target = fileURLToPath(new URL("../server/src/services/connectors/unikraft/operations.generated.json", import.meta.url));
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, JSON.stringify(output, null, 2) + "\n");
+  console.log(`Generated ${output.tools.length} Unikraft actions across ${output.metros.length} metros; recorded ${output.streaming.length} streaming endpoints.`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) await main();
@@ -0,0 +1,61 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateUnikraftCatalog } from "./generate-unikraft-tools.mjs";
+
+const servers = [{ url: "https://api.fra.unikraft.cloud" }, { url: "https://api.dal.unikraft.cloud" }];
+
+test("accounts for every HTTP operation and server-sent event stream without dropping methods", () => {
+  const result = generateUnikraftCatalog({ platform: { servers, paths: {
+    "/v1/instances": { get: { operationId: "GetInstances" }, post: { operationId: "CreateInstance" } },
+    "/v1/audit": { get: { operationId: "SubscribeAuditEvents", responses: { default: { content: { "text/event-stream": {} } } } } },
+  } } });
+  assert.deepEqual(result.metros, ["dal", "fra"]);
+  assert.deepEqual(result.tools.map(t => t.name), ["unikraft_get_instances", "unikraft_create_instance"]);
+  assert.deepEqual(result.streaming.map(s => s.name), ["unikraft_subscribe_audit_events"]);
+  assert.deepEqual(result.tools[0].inputSchema.properties.metro.enum, ["dal", "fra"]);
+});
+
+test("resolves shared parameters, keeps GET bodies and replaces unsigned formats", () => {
+  const result = generateUnikraftCatalog({ platform: { servers, paths: { "/v1/instances/log": { get: {
+    operationId: "GetInstanceLogs",
+    parameters: [{ $ref: "#/components/parameters/Uuid" }, { name: "limit", in: "query", schema: { type: "integer", format: "uint32" } },
+      { name: "Authorization", in: "header", schema: { type: "string" } }],
+    requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/Target" } } } },
+  } } }, components: {
+    parameters: { Uuid: { name: "uuid", in: "query", schema: { type: "array", items: { type: "string" } } } },
+    schemas: { Target: { type: "object", properties: { offset: { type: "integer", format: "uint64" },
+      drain_timeout_ms: { type: "integer", format: "uint64", description: "No draining if 0. Use -1 for the largest possible value." } } } },
+  } } });
+  const [tool] = result.tools;
+  assert.deepEqual(tool.parameters.map(p => p.name), ["uuid", "limit"]);
+  assert.equal(tool.inputSchema.properties.headers, undefined);
+  assert.deepEqual(tool.inputSchema.properties.query.properties.limit, { type: "integer", minimum: 0 });
+  assert.deepEqual(tool.inputSchema.definitions.Target.properties.offset, { type: "integer", minimum: 0 });
+  // A documented -1 sentinel stays valid.
+  assert.equal(tool.inputSchema.definitions.Target.properties.drain_timeout_ms.minimum, -1);
+  assert.equal(tool.bodyContentType, "application/json");
+  assert.ok(tool.inputSchema.required.includes("body"));
+  assert.equal(tool.annotations.readOnlyHint, true);
+});
+
+test("targets a sandbox instance and treats execution, disruption and deletion as destructive", () => {
+  const result = generateUnikraftCatalog({ platform: { servers, paths: {
+    "/v1/instances/stop": { put: { operationId: "StopInstances" } },
+    "/v1/instances/start": { put: { operationId: "StartInstances" } },
+    "/v1/volumes/detach": { put: { operationId: "DetachVolumes" } },
+    "/v1/volumes/{uuid}": { delete: { operationId: "DeleteVolumeByUUID" } },
+  } }, sandbox: { paths: {
+    "/commands": { post: { operationId: "RunCommand" } },
+    "/fs/read": { post: { operationId: "ReadFile" } },
+    "/fs/write": { post: { operationId: "WriteFile" } },
+  } } });
+  const risk = Object.fromEntries(result.tools.map(t => [t.name,
+    t.annotations.destructiveHint ? "destructive" : t.annotations.readOnlyHint ? "read" : "write"]));
+  assert.deepEqual(risk, {
+    unikraft_stop_instances: "destructive", unikraft_start_instances: "write", unikraft_detach_volumes: "destructive",
+    unikraft_delete_volume_by_uuid: "destructive", unikraft_sandbox_run_command: "destructive",
+    unikraft_sandbox_read_file: "read", unikraft_sandbox_write_file: "write",
+  });
+  const sandbox = result.tools.find(t => t.name === "unikraft_sandbox_run_command");
+  assert.ok(sandbox.inputSchema.required.includes("instance"));
+});