Copy page

JavaScript SDK

Client

The UnikraftCloud class is the entry point of the SDK. One client holds one token, one metro scope, and one transport, and every resource belongs to it.

Create a client

The constructor takes one configuration object. Every field is optional.

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

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

Options

Option	Default	Description
token	UKC_TOKEN	The bearer token.
metro	UKC_METRO	One metro code, such as fra, or a full http(s):// address. Operations that need one metro use this one.
metros	"all"	The metros that operations cover: "all", one metro code, or a list of codes.
baseUrl		The platform API address. It overrides metro.
controlPlaneUrl		The control plane API address.
fetch	The global fetch	A custom fetch implementation.
headers		Extra headers that the client sends with every request.
userAgent	@unikraft/cloud	The User-Agent header.
proxyFromEnv	true	Read the proxy environment variables on Node.js.

metros sets the scope of reads and bulk operations. metro sets the target of operations that need exactly one metro, such as create. When you set both, metros wins for the scope, and metro stays the target. When you set neither, the scope is every metro that the account can reach, and the target is fra. Metros explains the scope in detail.

Endpoints

A metro code expands to https://api.<metro>.unikraft.cloud. The client asks the control plane for the metros of the account, and it uses the endpoint that the control plane reports. As a result, a new metro works without an SDK upgrade.

Self-hosted and staging deployments

metro and UKC_METRO also accept a full http(s):// address. The client uses the address as given. It drops a trailing /v1, because every operation path already carries it.

Code
export UKC_METRO=https://api.staging.example.internal

A named address is the only endpoint that the client uses. It does no metro discovery, and it invents no hostnames, whatever the scope says. Point the control plane at the same deployment with controlPlaneUrl:

Code
const ukc = new UnikraftCloud({
  token,
  metro: "https://api.staging.example.internal",
  controlPlaneUrl: "https://controlplane.staging.example.internal",
});

Runtime

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.

The client uses the global fetch, which Node.js supplies. To use another runtime, or to control the transport, pass your own:

Code
const ukc = new UnikraftCloud({ token, fetch: myFetch });

Proxy support

On Node.js, the client reads the standard proxy environment variables. This lets you route its traffic through a proxy such as mitmproxy, Charles, or Proxyman without a code change.

Code
npm install undici
export HTTPS_PROXY=http://127.0.0.1:8080
export NODE_EXTRA_CA_CERTS=~/.mitmproxy/mitmproxy-ca-cert.pem
node your-script.js

The client recognises HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY, in either letter case. The global fetch of Node.js ignores these variables, so the SDK applies them through the EnvHttpProxyAgent of undici. undici is an optional peer dependency, and the SDK imports it only when you set a proxy variable. If undici isn't installed, the SDK sends the requests without a proxy, and it logs one warning.

To turn this off for one client, set proxyFromEnv: false. Browsers and Deno ignore these variables.