> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nebius AI Cloud SDK for JavaScript

The Nebius AI Cloud SDK for JavaScript is a client library for working with Nebius AI Cloud resources from JavaScript applications.

For documentation, see:

* [Nebius AI Cloud repository for the JavaScript SDK](https://github.com/nebius/js-sdk)
* [JavaScript SDK reference](https://nebius.github.io/js-sdk/)

## Supported Node.js versions

The SDK supports Node.js 22, 24 and 25.

## Installation and update

Install the SDK package:

```bash theme={null}
npm install @nebius/js-sdk
```

If you installed the SDK earlier, update it to the latest version:

```bash theme={null}
npm install @nebius/js-sdk@latest
```

## Initialization and authentication

For server-to-server communication, use a [service account](/iam/overview#accounts-and-members) to authenticate SDK requests. The SDK uses the service account credentials to generate a JSON Web Token, exchange it for an IAM token and refresh the IAM token in the background.

1. [Create a service account](/iam/service-accounts/manage#creating-a-service-account).

2. Generate an authorized key and create a service account credentials file:

   ```bash theme={null}
   nebius iam auth-public-key generate \
     --service-account-id <service_account_ID> \
     --output <credentials_file_path>
   ```

   In the command, set the following parameters:

   * `--service-account-id`: ID of your service account.
   * `--output`: Path to the service account credentials file, for example, `credentials.json`.

3. Initialize the SDK with the service account credentials file:

   ```javascript theme={null}
   import { SDK } from '@nebius/js-sdk';
   import { CredentialsFileReader } from '@nebius/js-sdk/runtime/service_account/credentials_file';

   const sdk = new SDK({
     userAgentPrefix: '<application_name>/<application_version_or_comment>',
     credentials: new CredentialsFileReader('<credentials_file_path>'),
   });

   await sdk.close();
   ```

   The `SDK` constructor initializes the SDK and uses the service account credentials file to authenticate requests.

   The `userAgentPrefix` argument adds a prefix to the [User-Agent header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/User-Agent) sent with each request. Use `userAgentPrefix` to identify your application in the list of requests.

   In the script, set the following parameters:

   * `<application_name>/<application_version_or_comment>`: Application or library that calls the SDK. The version or comment is optional.
   * `<credentials_file_path>`: Path to the service account credentials file.

<Note>
  For local usage, authenticate SDK requests by using an IAM token, CLI configuration or service account credentials. For more information, see the [JavaScript SDK repository](https://github.com/nebius/js-sdk#initialize-the-sdk).
</Note>

## Sending a request

The SDK provides service clients grouped by Nebius AI Cloud services and API versions.

For mutating operations, such as creating, updating and deleting resources, the SDK returns an operation object. If an operation is asynchronous, call `wait` to wait until it is completed.

The following example creates a [Compute virtual machine (VM)](/compute/virtual-machines/manage).

1. Create a JavaScript file with the following code.

   This script already includes SDK initialization and authentication.

   ```javascript theme={null}
   import { SDK } from '@nebius/js-sdk';
   import {
     AttachedDiskSpec_AttachMode,
     CreateDiskRequest,
     CreateInstanceRequest,
     DiskService as DiskServiceClient,
     DiskSpec_DiskType,
     InstanceService as InstanceServiceClient,
   } from '@nebius/js-sdk/api/nebius/compute/v1/index';
   import { CredentialsFileReader } from '@nebius/js-sdk/runtime/service_account/credentials_file';

   async function createInstance() {
     const sdk = new SDK({
       userAgentPrefix: '<application_name>/<application_version_or_comment>',
       credentials: new CredentialsFileReader('<credentials_file_path>'),
     });

     try {
       const diskService = new DiskServiceClient(sdk);
       const instanceService = new InstanceServiceClient(sdk);

       // Create the boot disk.
       const diskOperation = await diskService.create(
         CreateDiskRequest.create({
           metadata: {
             parentId: '<project_ID>',
             name: 'my-boot-disk',
           },
           spec: {
             size: {
               $case: 'sizeGibibytes',
               sizeGibibytes: 93,
             },
             type: DiskSpec_DiskType.NETWORK_SSD,
             source: {
               $case: 'sourceImageFamily',
               sourceImageFamily: {
                 imageFamily: '<image_family_name>',
               },
             },
           },
         }),
       ).result;

       await diskOperation.wait();
       console.log('Boot disk ID:', diskOperation.resourceId());

       // Create the VM that uses the boot disk.
       const instanceOperation = await instanceService.create(
         CreateInstanceRequest.create({
           metadata: {
             parentId: '<project_ID>',
             name: 'my-vm',
           },
           spec: {
             resources: {
               platform: '<platform_name>',
               size: {
                 $case: 'preset',
                 preset: '<preset_name>',
               },
             },
             networkInterfaces: [
               {
                 name: 'eth0',
                 subnetId: '<subnet_ID>',
                 ipAddress: {},
               },
             ],
             bootDisk: {
               attachMode: AttachedDiskSpec_AttachMode.READ_WRITE,
               type: {
                 $case: 'existingDisk',
                 existingDisk: {
                   id: diskOperation.resourceId(),
                 },
               },
               deviceId: 'boot-disk',
             },
           },
         }),
       ).result;

       await instanceOperation.wait();
       console.log('VM ID:', instanceOperation.resourceId());
     } finally {
       await sdk.close();
     }
   }

   await createInstance();
   ```

   In the script, set the following parameters:

   * `<application_name>/<application_version_or_comment>`: Application or library that calls the SDK. For more information, see [Initialization and authentication](#initialization-and-authentication).
   * `<credentials_file_path>`: Path to the service account credentials file.
   * `<project_ID>`: ID of the project where you create the resources.
   * `<image_family_name>`: Name of the [boot disk image family](/compute/storage/boot-disk-images), for example, `ubuntu24.04-driverless`.
   * `<platform_name>`: Name of the [Compute platform](/compute/virtual-machines/types), for example, `cpu-e2`.
   * `<preset_name>`: Name of the resource preset. Available presets depend on the selected platform, for example, `2vcpu-8gb` for `cpu-e2`.
   * `<subnet_ID>`: ID of the [subnet](/vpc/networking/resources#how-to-get-a-subnet-id) for the VM.

2. Execute the file:

   ```bash theme={null}
   node <file_name>.mjs
   ```

After you run the example, delete the VM and its boot disk if you no longer need them. Otherwise, Compute continues [charging](/compute/resources/pricing) for these resources.