> ## 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 Go

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

For documentation, see:

* [Nebius AI Cloud repository for the Go SDK](https://github.com/nebius/gosdk)
* [Go SDK reference](https://pkg.go.dev/github.com/nebius/gosdk)

## Supported Go versions

The SDK supports Go 1.24 and later. New SDK versions include breaking changes in the underlying libraries.

If your project uses an earlier SDK version, pin the dependency to `~v0.1,<v0.2` in your `go.mod` file.

## Installation and update

Install the SDK package:

```bash theme={null}
go get github.com/nebius/gosdk
```

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

```bash theme={null}
go get -u github.com/nebius/gosdk
```

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

   ```go theme={null}
   import (
      "fmt"

      "github.com/nebius/gosdk"
      "github.com/nebius/gosdk/auth"
   )

   sdk, err := gosdk.New(
      ctx,
      gosdk.WithUserAgentPrefix("<application_name>/<application_version_or_comment>"),
      gosdk.WithCredentials(
         gosdk.ServiceAccountReader(
            auth.NewServiceAccountCredentialsFileParser(
               nil,
               "<credentials_file_path>",
            ),
         ),
      ),
   )
   if err != nil {
      return fmt.Errorf("create gosdk: %w", err)
   }
   defer sdk.Close()
   ```

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

   The `WithUserAgentPrefix` method 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 `WithUserAgentPrefix` 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. For more information, see the [Go SDK repository](https://github.com/nebius/gosdk#using-an-iam-token).
</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/).

1. Create a Go file with the following code.

   This script already includes SDK initialization and authentication.

   ```go theme={null}
   package main

   import (
      "context"
      "fmt"

      "github.com/nebius/gosdk"
      "github.com/nebius/gosdk/auth"
      common "github.com/nebius/gosdk/proto/nebius/common/v1"
      compute "github.com/nebius/gosdk/proto/nebius/compute/v1"
   )

   // Run the resource creation workflow.
   func main() {
      if err := CreateInstance(context.Background()); err != nil {
         panic(err)
      }
   }

   // CreateInstance creates a boot disk and a VM that uses it.
   func CreateInstance(ctx context.Context) error {
      // Initialize the SDK with service account credentials.
      sdk, err := gosdk.New(
         ctx,
         gosdk.WithUserAgentPrefix("<application_name>/<application_version_or_comment>"),
         gosdk.WithCredentials(
            gosdk.ServiceAccountReader(
               auth.NewServiceAccountCredentialsFileParser(
                  nil,
                  "<credentials_file_path>",
               ),
            ),
         ),
      )
      if err != nil {
         return fmt.Errorf("create gosdk: %w", err)
      }
      defer sdk.Close()

      // Create the boot disk.
      diskOperation, err := sdk.Services().Compute().V1().Disk().Create(ctx, &compute.CreateDiskRequest{
         Metadata: &common.ResourceMetadata{
            ParentId: "<project_ID>",
            Name:     "my-boot-disk",
         },
         Spec: &compute.DiskSpec{
            Size: &compute.DiskSpec_SizeGibibytes{
               SizeGibibytes: 93,
            },
            Type: compute.DiskSpec_NETWORK_SSD,
            Source: &compute.DiskSpec_SourceImageFamily{
               SourceImageFamily: &compute.SourceImageFamily{
                  ParentId:    "<project_ID>",
                  ImageFamily: "<image_family_name>",
               },
            },
         },
      })
      if err != nil {
         return fmt.Errorf("create disk: %w", err)
      }

      diskOperation, err = diskOperation.Wait(ctx)
      if err != nil {
         return fmt.Errorf("wait for disk create: %w", err)
      }

      // Create the VM that uses the boot disk.
      instanceOperation, err := sdk.Services().Compute().V1().Instance().Create(ctx, &compute.CreateInstanceRequest{
         Metadata: &common.ResourceMetadata{
            ParentId: "<project_ID>",
            Name:     "my-vm",
         },
         Spec: &compute.InstanceSpec{
            Resources: &compute.ResourcesSpec{
               Platform: "<platform_name>",
               Size: &compute.ResourcesSpec_Preset{
                  Preset: "<preset_name>",
               },
            },
            NetworkInterfaces: []*compute.NetworkInterfaceSpec{
               {
                  Name:      "eth0",
                  SubnetId:  "<subnet_ID>",
                  IpAddress: &compute.IPAddress{},
               },
            },
            BootDisk: &compute.AttachedDiskSpec{
               AttachMode: compute.AttachedDiskSpec_READ_WRITE,
               Type: &compute.AttachedDiskSpec_ExistingDisk{
                  ExistingDisk: &compute.ExistingDisk{
                     Id: diskOperation.ResourceID(),
                  },
               },
               DeviceId: "boot-disk",
            },
         },
      })
      if err != nil {
         return fmt.Errorf("create VM: %w", err)
      }

      _, err = instanceOperation.Wait(ctx)
      if err != nil {
         return fmt.Errorf("wait for VM creation: %w", err)
      }

      return nil
   }
   ```

   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}
   go run <file_name>.go
   ```

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.