@ebowwa/nebius

Nebius AI Cloud API client for TypeScript. Provides access to Nebius cloud services including compute instances, disks, networks, and GPU clusters.

Installation

bun add @ebowwa/nebius
# or
npm install @ebowwa/nebius

Quick Start

import { NebiusClient } from "@ebowwa/nebius";

const client = new NebiusClient({
  serviceAccountId: "service-account-id",
  authorizedKey: {
    id: "key-id",
    serviceAccountId: "service-account-id",
    privateKey: "-----BEGIN PRIVATE KEY-----\n...",
  },
  folderId: "folder-id",
  zone: "fi-he1",
});

// List instances
const { instances } = await client.instances.list();
console.log(instances);

// Create an instance
const operation = await client.instances.create({
  name: "my-instance",
  folderId: "folder-id",
  zoneId: "fi-he1",
  platformId: "standard-v3",
  resourcesSpec: {
    cores: 4,
    memory: 8 * 1024 * 1024 * 1024, // 8GB in bytes
  },
  bootDiskSpec: {
    diskSpec: {
      imageId: "ubuntu-22-04-lts",
    },
  },
  networkInterfaceSpecs: [
    {
      subnetId: "subnet-id",
      primaryV4AddressSpec: {
        oneToOneNatSpec: {
          ipVersion: "IPV4",
        },
      },
    },
  ],
});

// Wait for operation to complete
const completed = await client.pollOperation(operation.id);
console.log("Instance created:", completed.response);

Authentication

Nebius uses JWT-based authentication with service account authorized keys. The client handles token exchange automatically.

Getting Authorized Keys

1. Go to Nebius Console → Service Accounts
2. Create or select a service account
3. Create an authorized key (JSON format)
4. Store the key securely

Environment Variables

import { createClientFromEnv } from "@ebowwa/nebius";

// Set environment variables:
// NEBIUS_SERVICE_ACCOUNT_ID=your-service-account-id
// NEBIUS_AUTHORIZED_KEY={"id":"...","serviceAccountId":"...","privateKey":"..."}
// NEBIUS_FOLDER_ID=your-folder-id (optional)
// NEBIUS_ZONE=fi-he1 (optional)

const client = createClientFromEnv();

API Reference

Client

const client = new NebiusClient({
  serviceAccountId: string;       // Service account ID
  authorizedKey: NebiusAuthorizedKey;  // Key object with privateKey
  folderId?: string;              // Default folder ID
  zone?: string;                  // Default availability zone
  endpoint?: string;              // API endpoint override
  timeout?: number;               // Request timeout (default: 30000ms)
  fetch?: typeof fetch;           // Custom fetch function
});

Instances

// List instances
const { instances, nextPageToken } = await client.instances.list({
  folderId: "folder-id",
  pageSize: 100,
  filter: 'name="my-instance"',
});

// Get instance
const instance = await client.instances.get("instance-id");

// Create instance (returns operation)
const operation = await client.instances.create({
  name: "my-instance",
  folderId: "folder-id",
  zoneId: "fi-he1",
  platformId: "standard-v3",
  resourcesSpec: { cores: 4, memory: 8589934592 },
  bootDiskSpec: { diskSpec: { imageId: "ubuntu-22-04-lts" } },
  networkInterfaceSpecs: [{ subnetId: "subnet-id" }],
});

// Create and wait for ready
const instance = await client.instances.createAndWait(options);

// Update instance
await client.instances.update("instance-id", {
  name: "new-name",
  labels: { env: "production" },
});

// Start/Stop/Restart
await client.instances.start("instance-id");
await client.instances.stop("instance-id");
await client.instances.restart("instance-id");

// Delete instance
await client.instances.delete("instance-id");
await client.instances.deleteAndWait("instance-id");

Disks

// List disks
const { disks } = await client.disks.list({ folderId: "folder-id" });

// Create disk
const disk = await client.disks.createAndWait({
  name: "my-disk",
  folderId: "folder-id",
  zoneId: "fi-he1",
  size: 100 * 1024 * 1024 * 1024, // 100GB
  typeId: "NETWORK_SSD",
});

// Resize disk
await client.disks.resize("disk-id", 200 * 1024 * 1024 * 1024);

// Create snapshot
await client.disks.createSnapshot("disk-id", {
  name: "my-snapshot",
  folderId: "folder-id",
});

Networks (VPC)

// Create network
const network = await client.networks.createNetworkAndWait({
  name: "my-network",
  folderId: "folder-id",
});

// Create subnet
const subnet = await client.networks.createSubnetAndWait({
  name: "my-subnet",
  folderId: "folder-id",
  networkId: network.id,
  zoneId: "fi-he1",
  v4CidrBlocks: ["10.0.0.0/24"],
});

// List subnets
const { subnets } = await client.networks.listSubnets({
  networkId: network.id,
});

Operations

All create/update/delete operations return an NebiusOperation object. Use pollOperation to wait for completion:

const operation = await client.instances.create(options);

// Poll with progress callback
const completed = await client.pollOperation(operation.id, {
  pollInterval: 2000,  // 2 seconds
  timeout: 300000,     // 5 minutes
  onProgress: (op) => console.log(`Progress: ${op.progress}%`),
});

if (completed.error) {
  console.error("Operation failed:", completed.error.message);
} else {
  console.log("Success:", completed.response);
}

GPU Instances

Nebius provides high-performance GPU instances:

// GPU instance with H100
const gpuInstance = await client.instances.createAndWait({
  name: "gpu-instance",
  folderId: "folder-id",
  zoneId: "fi-he1",
  platformId: "gpu-standard-v3",
  resourcesSpec: {
    cores: 8,
    memory: 32 * 1024 * 1024 * 1024, // 32GB
    gpus: 8,
    gpuType: "H100",
  },
  bootDiskSpec: {
    diskSpec: {
      imageId: "ubuntu-22-04-lts-gpu",
    },
  },
  networkInterfaceSpecs: [{ subnetId: "subnet-id" }],
});

Availability Zones

import { NEBIUS_ZONES } from "@ebowwa/nebius";

// Available zones:
// - fi-he1: Finland, Helsinki 1
// - fi-he2: Finland, Helsinki 2

Error Handling

import {
  NebiusAPIError,
  NebiusNotFoundError,
  NebiusValidationError,
  NebiusRateLimitError,
  isRetryableError,
} from "@ebowwa/nebius";

try {
  const instance = await client.instances.get("instance-id");
} catch (error) {
  if (error instanceof NebiusNotFoundError) {
    console.log("Instance not found");
  } else if (error instanceof NebiusValidationError) {
    console.log("Validation error:", error.details);
  } else if (error instanceof NebiusRateLimitError) {
    console.log("Rate limited, retry after:", error.retryAfter);
  } else if (isRetryableError(error)) {
    console.log("Retryable error, consider retrying");
  } else {
    throw error;
  }
}

License

MIT