Copy page

JavaScript SDK

JavaScript SDK

@unikraft/cloud is the official JavaScript and TypeScript SDK for the Unikraft Cloud API. The package is fully typed, and it covers the per-metro platform API and the global control plane API.

Installation

Code
npm install @unikraft/cloud

The SDK needs Node.js 22.12 or later, and it ships as ECMAScript modules (ESM) only. From that version, Node.js can require() an ESM package, so CommonJS code can load it too.

Quickstart

This example creates a client, starts an instance in the fra metro, waits until the instance runs, then deletes it.

Code
import { UnikraftCloud } from "@unikraft/cloud";

const ukc = new UnikraftCloud({ token: process.env.UKC_TOKEN });
const fra = ukc.metro("fra");

const instance = await fra.instances.create({
  image: "nginx:latest",
  memory_mb: 256,
  autostart: true,
  service_group: {
    services: [{ port: 443, handlers: ["tls", "http"], destination_port: 80 }],
  },
});

await fra.instances.get({ uuid: instance.uuid! }).wait({ state: "running" });
console.log(instance.name, instance.uuid);

await fra.instances.delete([{ uuid: instance.uuid! }]);

Three ideas from this example come back on every page of this section:

• ukc.metro("fra") limits the client to one metro. Without a limit, a read covers every metro of the account.
• fra.instances.get(...) returns a handle. A handle sends nothing until you await it, and every operation on it returns a new handle, so .wait(...) chains.
• { uuid } is a ref. A ref is { name } or { uuid }, and it names one resource.

Authentication

Every request carries a bearer token. Create the token in the Unikraft Cloud console, then pass it to the constructor:

Code
const ukc = new UnikraftCloud({ token: "..." });

Or set the UKC_TOKEN environment variable, and create the client with no arguments:

Code
export UKC_TOKEN=...

Code
const ukc = new UnikraftCloud();

Two layers

The SDK has two layers, and you choose the layer per call.

Layer	Import	What you get
Idiomatic	@unikraft/cloud	Short verbs such as ukc.instances.get, results without the response envelope, automatic pagination, metro fan-out, chainable handles
Raw	@unikraft/cloud/api/platform, @unikraft/cloud/api/controlplane	One method per operationId of the OpenAPI specification, the raw response envelope, one metro per call

Use the idiomatic layer by default. The raw layer is one property away, as ukc.api, for every operation that the idiomatic layer doesn't cover yet. See the raw API.

Pages in this section

Page	Content
Client	Constructor options, endpoints, self-hosted deployments, runtime, proxy support
Metros	How one client covers many metros, and how names behave across them
Resources	Refs, handles, updates, the method list, and the raw API
Errors	The error classes, the error kinds, and how waits behave
Sandboxes	Run commands and move files inside a microVM

Source

• Source code: github.com/unikraft-cloud/js-sdk
• Package: npmjs.com/package/@unikraft/cloud
• Complete programs: examples/

Learn more

• Python SDK: the client library for the same platform API in Python.
• Go SDK: the client library for the same platform API in Go.
• REST API reference: the platform API that the raw layer mirrors.