PaperClipAI/doc/connections/UNIKRAFT.md

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)

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 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:

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.