How to connect to a tunnel

To connect a service to a tunnel, configure and run a tunnel agent. You’ll need the tunnel ID in the agent configuration.

​

Prerequisites

​

Connecting a service

To connect to a tunnel, first set up access for the tunnel agent and then launch this agent.

​

Setting up access for the tunnel agent

1. Create a service account and save its ID:
   • CLI
   • Go SDK
   • Python SDK
   • JavaScript SDK

   export SA_ID=$(nebius iam service-account create \
     --name "tunnel-agent" \
     --parent-id "$PROJECT_ID" \
     --format jsonpath='{.metadata.id}')
   

   createSaService := sdk.Services().IAM().V1().
       ServiceAccount()
   createSaOperation, err := createSaService.Create(
       ctx,
       &iam.CreateServiceAccountRequest{
           Metadata: &common.ResourceMetadata{
               Name: "tunnel-agent",
               ParentId: "<project_ID>",
           },
           Spec: &iam.ServiceAccountSpec{},
       },
   )
   if err != nil {
       return fmt.Errorf("create service account: %w", err)
   }
   createSaOperation, err = createSaOperation.Wait(ctx)
   if err != nil {
       return fmt.Errorf("wait for create service account: %w", err)
   }
   saID := createSaOperation.ResourceID()
   fmt.Println(saID)
   

   In the code, set ParentId in ResourceMetadata to the project ID. The code prints the ID of the service account.

   create_sa_service = ServiceAccountServiceClient(sdk)
   create_sa_operation = await create_sa_service.create(
       CreateServiceAccountRequest(
           metadata=ResourceMetadata(
               name="tunnel-agent",
               parent_id="<project_ID>",
           ),
           spec=ServiceAccountSpec(),
       ),
   )
   await create_sa_operation.wait()
   sa_id = create_sa_operation.resource_id
   print(sa_id)
   

   In the code, set parent_id in ResourceMetadata to the project ID. The code prints the ID of the service account.

   const createSaService = new ServiceAccountService(sdk);
   const createSaOperation = await createSaService.create(
     CreateServiceAccountRequest.create({
       metadata: ResourceMetadata.create({
         name: "tunnel-agent",
         parentId: "<project_ID>",
       }),
       spec: ServiceAccountSpec.create({}),
     }),
   ).result;
   await createSaOperation.wait();
   const saId = createSaOperation.resourceId();
   console.log(saId);
   

   In the code, set parentId in ResourceMetadata to the project ID. The code prints the ID of the service account.
   To grant wider access instead of creating a dedicated group with the applicationtunnel.agent role, you can add the service account to the editors group.
2. Create a group for Nebius Tunnels service accounts and save its ID:
   • CLI
   • Go SDK
   • Python SDK
   • JavaScript SDK

   export GROUP_ID=$(nebius iam group create \
     --name "tunnel-agents" \
     --parent-id "$TENANT_ID" \
     --format jsonpath='{.metadata.id}')
   

   createGroupService := sdk.Services().IAM().V1().
       Group()
   createGroupOperation, err := createGroupService.Create(
       ctx,
       &iam.CreateGroupRequest{
           Metadata: &common.ResourceMetadata{
               Name: "tunnel-agents",
               ParentId: "<tenant_ID>",
           },
       },
   )
   if err != nil {
       return fmt.Errorf("create group: %w", err)
   }
   createGroupOperation, err = createGroupOperation.Wait(ctx)
   if err != nil {
       return fmt.Errorf("wait for create group: %w", err)
   }
   groupID := createGroupOperation.ResourceID()
   fmt.Println(groupID)
   

   In the code, set ParentId in ResourceMetadata to the tenant ID. The code prints the ID of the group.

   create_group_service = GroupServiceClient(sdk)
   create_group_operation = await create_group_service.create(
       CreateGroupRequest(
           metadata=ResourceMetadata(
               name="tunnel-agents",
               parent_id="<tenant_ID>",
           ),
       ),
   )
   await create_group_operation.wait()
   group_id = create_group_operation.resource_id
   print(group_id)
   

   In the code, set parent_id in ResourceMetadata to the tenant ID. The code prints the ID of the group.

   const createGroupService = new GroupService(sdk);
   const createGroupOperation = await createGroupService.create(
     CreateGroupRequest.create({
       metadata: ResourceMetadata.create({
         name: "tunnel-agents",
         parentId: "<tenant_ID>",
       }),
     }),
   ).result;
   await createGroupOperation.wait();
   const groupId = createGroupOperation.resourceId();
   console.log(groupId);
   

   In the code, set parentId in ResourceMetadata to the tenant ID. The code prints the ID of the group.
3. Grant the group the applicationtunnel.agent role for the tunnel:
   • CLI
   • Go SDK
   • Python SDK
   • JavaScript SDK

   nebius iam access-permit create \
     --parent-id "$GROUP_ID" \
     --resource-id "$TUNNEL_ID" \
     --role applicationtunnel.agent
   

   accessPermitService := sdk.Services().IAM().V1().
       AccessPermit()
   accessPermitOperation, err := accessPermitService.Create(
       ctx,
       &iam.CreateAccessPermitRequest{
           Metadata: &common.ResourceMetadata{
               ParentId: "<group_ID>",
           },
           Spec: &iam.AccessPermitSpec{
               ResourceId: "<tunnel_ID>",
               Role: "applicationtunnel.agent",
           },
       },
   )
   if err != nil {
       return fmt.Errorf("create access permit: %w", err)
   }
   accessPermitOperation, err = accessPermitOperation.Wait(ctx)
   if err != nil {
       return fmt.Errorf("wait for create access permit: %w", err)
   }
   

   In the code, set ParentId in ResourceMetadata to the group ID and ResourceId in AccessPermitSpec to the tunnel ID.

   access_permit_service = AccessPermitServiceClient(sdk)
   access_permit_operation = await access_permit_service.create(
       CreateAccessPermitRequest(
           metadata=ResourceMetadata(
               parent_id="<group_ID>",
           ),
           spec=AccessPermitSpec(
               resource_id="<tunnel_ID>",
               role="applicationtunnel.agent",
           ),
       ),
   )
   await access_permit_operation.wait()
   

   In the code, set parent_id in ResourceMetadata to the group ID and resource_id in AccessPermitSpec to the tunnel ID.

   const accessPermitService = new AccessPermitService(sdk);
   const accessPermitOperation = await accessPermitService.create(
     CreateAccessPermitRequest.create({
       metadata: ResourceMetadata.create({
         parentId: "<group_ID>",
       }),
       spec: AccessPermitSpec.create({
         resourceId: "<tunnel_ID>",
         role: "applicationtunnel.agent",
       }),
     }),
   ).result;
   await accessPermitOperation.wait();
   

   In the code, set parentId in ResourceMetadata to the group ID and resourceId in AccessPermitSpec to the tunnel ID.
   To grant access to more tunnels, create the permit on a broader resource: a project or a tenant. A permit on a project applies to all tunnels in that project. A permit on a tenant applies to all tunnels in all projects in the tenant.
4. Add the service account to the group:
   • CLI
   • Go SDK
   • Python SDK
   • JavaScript SDK

   nebius iam group-membership create \
     --parent-id "$GROUP_ID" \
     --member-id "$SA_ID"
   

   membershipService := sdk.Services().IAM().V1().
       GroupMembership()
   membershipOperation, err := membershipService.Create(
       ctx,
       &iam.CreateGroupMembershipRequest{
           Metadata: &common.ResourceMetadata{
               ParentId: "<group_ID>",
           },
           Spec: &iam.GroupMembershipSpec{
               MemberId: "<service_account_ID>",
           },
       },
   )
   if err != nil {
       return fmt.Errorf("create group membership: %w", err)
   }
   membershipOperation, err = membershipOperation.Wait(ctx)
   if err != nil {
       return fmt.Errorf("wait for create group membership: %w", err)
   }
   

   In the code, set ParentId in ResourceMetadata to the group ID and MemberId in GroupMembershipSpec to the service account ID.

   membership_service = GroupMembershipServiceClient(sdk)
   membership_operation = await membership_service.create(
       CreateGroupMembershipRequest(
           metadata=ResourceMetadata(
               parent_id="<group_ID>",
           ),
           spec=GroupMembershipSpec(
               member_id="<service_account_ID>",
           ),
       ),
   )
   await membership_operation.wait()
   

   In the code, set parent_id in ResourceMetadata to the group ID and member_id in GroupMembershipSpec to the service account ID.

   const membershipService = new GroupMembershipService(sdk);
   const membershipOperation = await membershipService.create(
     CreateGroupMembershipRequest.create({
       metadata: ResourceMetadata.create({
         parentId: "<group_ID>",
       }),
       spec: GroupMembershipSpec.create({
         memberId: "<service_account_ID>",
       }),
     }),
   ).result;
   await membershipOperation.wait();
   

   In the code, set parentId in ResourceMetadata to the group ID and memberId in GroupMembershipSpec to the service account ID.

​

Installing and running the agent

You can run the tunnel agent in Docker, in a Kubernetes cluster by using Helm or on a Nebius VM.

​

Creating an authorized key for Docker and Helm

In Docker and Kubernetes, the agent authenticates as the service account by using an authorized key. On a Nebius VM, the agent doesn’t need a key, so go to Running the agent on a VM.

1. Create a key pair:
   openssl genrsa -out ./private_key.pem 4096
   openssl rsa -in ./private_key.pem -pubout -out ./public_key.pem
   
   The command creates the private_key.pem and public_key.pem files in the current directory.
2. Upload the public key and save its ID:
   • CLI
   • Go SDK
   • Python SDK
   • JavaScript SDK

   export PUBLIC_KEY_ID=$(nebius iam auth-public-key create \
     --account-service-account-id "$SA_ID" \
     --data "$(cat ./public_key.pem)" \
     --format jsonpath='{.metadata.id}')
   

   publicKeyData, err := os.ReadFile("./public_key.pem")
   if err != nil {
       return fmt.Errorf("read public key: %w", err)
   }
   keyAccount := &iam.Account{
       Type: &iam.Account_ServiceAccount_{
           ServiceAccount: &iam.Account_ServiceAccount{
               Id: "<service_account_ID>",
           },
       },
   }
   publicKeyService := sdk.Services().IAM().V1().
       AuthPublicKey()
   publicKeyOperation, err := publicKeyService.Create(
       ctx,
       &iam.CreateAuthPublicKeyRequest{
           Spec: &iam.AuthPublicKeySpec{
               Account: keyAccount,
               Data: string(publicKeyData),
           },
       },
   )
   if err != nil {
       return fmt.Errorf("create auth public key: %w", err)
   }
   publicKeyOperation, err = publicKeyOperation.Wait(ctx)
   if err != nil {
       return fmt.Errorf("wait for create auth public key: %w", err)
   }
   publicKeyID := publicKeyOperation.ResourceID()
   fmt.Println(publicKeyID)
   

   In the code, set Id in Account_ServiceAccount to the service account ID. The code reads the public key from the public_key.pem file and prints the ID of the authorized key.

   public_key_data = Path("./public_key.pem").read_text()
   key_account = Account(
       service_account=Account__ServiceAccount(
           id="<service_account_ID>",
       ),
   )
   public_key_service = AuthPublicKeyServiceClient(sdk)
   public_key_operation = await public_key_service.create(
       CreateAuthPublicKeyRequest(
           spec=AuthPublicKeySpec(
               account=key_account,
               data=public_key_data,
           ),
       ),
   )
   await public_key_operation.wait()
   public_key_id = public_key_operation.resource_id
   print(public_key_id)
   

   In the code, set id in Account__ServiceAccount to the service account ID. The code reads the public key from the public_key.pem file and prints the ID of the authorized key.

   const publicKeyData =
     await readFile("./public_key.pem", "utf8");
   const keyAccount = Account.create({
     type: {
       $case: "serviceAccount",
       serviceAccount: Account_ServiceAccount.create({
         id: "<service_account_ID>",
       }),
     },
   });
   const publicKeyService = new AuthPublicKeyService(sdk);
   const publicKeyOperation = await publicKeyService.create(
     CreateAuthPublicKeyRequest.create({
       metadata: ResourceMetadata.create({}),
       spec: AuthPublicKeySpec.create({
         account: keyAccount,
         data: publicKeyData,
       }),
     }),
   ).result;
   await publicKeyOperation.wait();
   const publicKeyId = publicKeyOperation.resourceId();
   console.log(publicKeyId);
   

   In the code, set id in Account_ServiceAccount to the service account ID. The code reads the public key from the public_key.pem file and prints the ID of the authorized key.

​

Running the agent in Docker

1. Install Docker Engine.
2. In the directory with the private_key.pem file, create config.yaml for the agent:
   tunnel_id: <tunnel_ID>
   
   iam:
     service_account:
       service_account_id: <service_account_ID>
       public_key_id: <authorized_key_ID>
       private_key_path: "./private_key.pem"
   
   services:
     - name: web
       target: localhost:8080
       type: http
   
   In the file, replace:
   • <tunnel_ID> with the tunnel ID. If you use the CLI, it’s the value of $TUNNEL_ID.
   • <service_account_ID> with the service account ID. If you use the CLI, it’s the value of $SA_ID.
   • <authorized_key_ID> with the ID of the authorized key. If you use the CLI, it’s the value of $PUBLIC_KEY_ID.
   In the agent configuration, services.name can contain up to 20 characters and must use only lowercase Latin letters and digits ([a-z0-9]). Don’t use dashes or dots. For multiple services, configure the services section like this:
   services:
     - name: api
       target: localhost:8080
       type: http
     - name: grpc
       target: localhost:9090
       type: http
       protocol: h2
     - name: db
       target: localhost:5432
       type: tcp
   
3. Run the agent using a cross-platform Docker image:
   docker run -v $PWD:/home/nonroot \
     cr.eu-north1.nebius.cloud/marketplace/docker/nebius-tunnel-agent:latest \
     -config ./config.yaml
   
   When the agent connects, it returns the public endpoint for each service. The endpoint format is:
   <service_name>-<tunnel_masked_ID>.tunnel.applications.<region>.nebius.cloud:443
   
   Where:
   • service_name is the services.name value from the agent configuration.
   • tunnel_masked_ID is the mask of the tunnel ID without the applicationtunnel- prefix and regional routing code. For example, for applicationtunnel-e00abcdef123456789, the tunnel ID mask is abcdef123456789.
   • region is the region of the project where the tunnel was created, for example eu-north1.

​

Running the agent by using Helm

1. Install Helm.
2. Create custom.values.yaml with the service account credentials and agent config:
   secret:
     data:
       private_key.pem: |
         # Your private key
     items:
       - key: private_key.pem
         path: sa/private_key.pem
   
   config:
     tunnel_id: <tunnel_ID>
     iam:
       service_account:
         service_account_id: <service_account_ID>
         public_key_id: <authorized_key_ID>
         private_key_path: sa/private_key.pem
     services:
       - name: web
         target: localhost:8080
         type: http
   
   In the file, replace:
   • <tunnel_ID> with the tunnel ID. If you use the CLI, it’s the value of $TUNNEL_ID.
   • <service_account_ID> with the service account ID. If you use the CLI, it’s the value of $SA_ID.
   • <authorized_key_ID> with the ID of the authorized key. If you use the CLI, it’s the value of $PUBLIC_KEY_ID.
   • The private key placeholder with the contents of private_key.pem.
   In the agent configuration, services.name can contain up to 20 characters and must use only lowercase Latin letters and digits ([a-z0-9]). Don’t use dashes or dots. For multiple services, add them to the config.services section:
   config:
     services:
       - name: api
         target: localhost:8080
         type: http
       - name: grpc
         target: localhost:9090
         type: http
         protocol: h2
       - name: db
         target: localhost:5432
         type: tcp
   
3. Install the agent in your Kubernetes cluster:
   helm install nebius-tunnel-agent \
     oci://cr.eu-north1.nebius.cloud/marketplace/chart/nebius-tunnel-agent \
     -f custom.values.yaml
   
   When the agent connects, it returns the public endpoint for each service. The endpoint format is:
   <service_name>-<tunnel_masked_ID>.tunnel.applications.<region>.nebius.cloud:443
   
   Where:
   • service_name is the services.name value from the agent configuration.
   • tunnel_masked_ID is the mask of the tunnel ID without the applicationtunnel- prefix and regional routing code. For example, for applicationtunnel-e00abcdef123456789, the tunnel ID mask is abcdef123456789.
   • region is the region of the project where the tunnel was created, for example eu-north1.

​

Running the agent on a VM

On a Nebius VM, the agent authenticates through the instance metadata service. This requires attaching a service account to the VM when you create it, as described in Prerequisites.

1. Prepare the cloud-init configuration file. You’ll attach it to the VM when you create it. Save the following configuration to a file named cloud-init.yaml in your working directory. Before saving, replace:
   • <username> with the username you’ll use to connect.
   • <public_SSH_key> with your SSH public key.
   • <tunnel_ID> with the tunnel ID. If you use the CLI, it’s the value of $TUNNEL_ID.
   cloud-init.yaml

   users:
     - name: <username>
       sudo: "ALL=(ALL) NOPASSWD:ALL"
       shell: /bin/bash
       ssh_authorized_keys:
         - <public_SSH_key>
   
   write_files:
     - path: /etc/nebius-tunnel-agent/config.yaml
       permissions: "0640"
       content: |
         tunnel_id: <tunnel_ID>
   
         iam:
           metadata:
             enabled: true
   
         services:
           - name: web
             target: 127.0.0.1:8080
             type: http
   
     - path: /etc/systemd/system/nebius-tunnel-agent.service
       permissions: "0644"
       content: |
         [Unit]
         Description=Nebius tunnel agent
         Documentation=https://docs.nebius.com/tunnels
         After=network-online.target
         Wants=network-online.target
   
         [Service]
         Type=simple
         User=tunna
         Group=tunna
         ExecStart=/usr/local/bin/nebius-tunnel-agent --config /etc/nebius-tunnel-agent/config.yaml
         Restart=always
         RestartSec=5
         NoNewPrivileges=true
         ProtectSystem=strict
         ProtectHome=true
         PrivateTmp=true
         ReadOnlyPaths=/etc/nebius-tunnel-agent
   
         [Install]
         WantedBy=multi-user.target
   
     - path: /usr/local/sbin/install-nebius-tunnel-agent
       permissions: "0755"
       content: |
         #!/bin/bash
         set -euo pipefail
   
         VERSION="${AGENT_VERSION:-latest}"
         BASE="https://storage.eu-north1.nebius.cloud/products/releases/nebius-tunnel-agent"
         CONF_DIR=/etc/nebius-tunnel-agent
   
         # Select the agent archive for the VM architecture
         case "$(uname -m)" in
           x86_64)        PLATFORM=linux-x86_64 ;;
           aarch64|arm64) PLATFORM=linux-aarch64 ;;
           *) echo "unsupported architecture: $(uname -m)" >&2; exit 1 ;;
         esac
         ASSET="nebius-tunnel-agent-${PLATFORM}.tar.gz"
   
         TMP="$(mktemp -d)"
         trap 'rm -rf "$TMP"' EXIT
   
         # Download a file with retry handling
         fetch() {
           curl -fsSL --retry 5 --retry-delay 3 --retry-connrefused -o "$2" "$1"
         }
   
         # Download and verify the agent archive
         fetch "$BASE/$VERSION/$ASSET" "$TMP/$ASSET"
         fetch "$BASE/$VERSION/checksums-sha256.txt" "$TMP/checksums-sha256.txt"
         (cd "$TMP" && sha256sum --ignore-missing -c checksums-sha256.txt)
   
         # Install the agent binary
         tar -xzf "$TMP/$ASSET" -C "$TMP"
         install -m0755 "$TMP/nebius-tunnel-agent" /usr/local/bin/nebius-tunnel-agent
   
         # Create the dedicated system user and start the service
         getent group tunna >/dev/null || groupadd --system tunna
         id -u tunna >/dev/null 2>&1 || useradd --system --gid tunna \
           --no-create-home --shell /usr/sbin/nologin tunna
         chown -R tunna:tunna "$CONF_DIR"
         chmod 0750 "$CONF_DIR"
         chmod 0640 "$CONF_DIR/config.yaml"
   
         systemctl daemon-reload
         systemctl enable nebius-tunnel-agent.service
         systemctl restart nebius-tunnel-agent.service
   
   runcmd:
     - [/usr/local/sbin/install-nebius-tunnel-agent]
   

   This configuration enables the following actions:

   • Add a username and a public SSH key to the VM.
   • Download the tunnel agent, verify its checksum and install it as a systemd service running under a dedicated tunna system user.
   • Authenticate by using the service account attached to the VM, through the instance metadata service. No key files are involved.
   • Create the web Nebius Tunnels service that exposes 127.0.0.1:8080 on the VM.
   In the agent configuration, services.name can contain up to 20 characters and must use only lowercase Latin letters and digits ([a-z0-9]). Don’t use dashes or dots. For multiple services, add them to the services section of config.yaml in the cloud-init file:
   services:
     - name: api
       target: 127.0.0.1:8080
       type: http
     - name: grpc
       target: 127.0.0.1:9090
       type: http
       protocol: h2
     - name: db
       target: 127.0.0.1:5432
       type: tcp
   
2. Create the VM:
   • CLI
   • Go SDK
   • Python SDK
   • JavaScript SDK

   nebius compute instance create \
     --name tunnel-agent-vm \
     --resources-platform cpu-d3 \
     --resources-preset 4vcpu-16gb \
     --boot-disk-attach-mode READ_WRITE \
     --boot-disk-managed-disk-name tunnel-agent-vm-boot \
     --boot-disk-managed-disk-type network_ssd \
     --boot-disk-managed-disk-size-gibibytes 20 \
     --boot-disk-managed-disk-source-image-family-image-family ubuntu24.04-driverless \
     --network-interfaces "[{\"name\": \"eth0\", \"ip_address\": {}, \"public_ip_address\": {}, \"subnet_id\": \"<subnet_ID>\"}]" \
     --service-account-id <service_account_ID> \
     --cloud-init-user-data "$(cat cloud-init.yaml)"
   

   In the command, specify the subnet ID from Prerequisites and the ID of the service account you created earlier.

   cloudInit, err := os.ReadFile("cloud-init.yaml")
   if err != nil {
       return fmt.Errorf("read cloud init: %w", err)
   }
   resources := &compute.ResourcesSpec{
       Platform: "cpu-d3",
       Size: &compute.ResourcesSpec_Preset{
           Preset: "4vcpu-16gb",
       },
   }
   bootDiskSpec := &compute.DiskSpec{
       Type: compute.DiskSpec_NETWORK_SSD,
       Size: &compute.DiskSpec_SizeGibibytes{
           SizeGibibytes: 20,
       },
       Source: &compute.DiskSpec_SourceImageFamily{
           SourceImageFamily: &compute.SourceImageFamily{
               ImageFamily: "ubuntu24.04-driverless",
           },
       },
   }
   bootDisk := &compute.AttachedDiskSpec{
       AttachMode: compute.AttachedDiskSpec_READ_WRITE,
       Type: &compute.AttachedDiskSpec_ManagedDisk{
           ManagedDisk: &compute.ManagedDisk{
               Name: "tunnel-agent-vm-boot",
               Spec: bootDiskSpec,
           },
       },
   }
   networkInterface := &compute.NetworkInterfaceSpec{
       Name: "eth0",
       SubnetId: "<subnet_ID>",
       IpAddress: &compute.IPAddress{},
       PublicIpAddress: &compute.PublicIPAddress{},
   }
   createInstanceService := sdk.Services().Compute().V1().
       Instance()
   createInstanceOperation, err := createInstanceService.Create(
       ctx,
       &compute.CreateInstanceRequest{
           Metadata: &common.ResourceMetadata{
               Name: "tunnel-agent-vm",
           },
           Spec: &compute.InstanceSpec{
               Resources: resources,
               BootDisk: bootDisk,
               NetworkInterfaces: []*compute.NetworkInterfaceSpec{
                   networkInterface,
               },
               ServiceAccountId: "<service_account_ID>",
               CloudInitUserData: string(cloudInit),
           },
       },
   )
   if err != nil {
       return fmt.Errorf("create instance: %w", err)
   }
   createInstanceOperation, err = createInstanceOperation.Wait(ctx)
   if err != nil {
       return fmt.Errorf("wait for create instance: %w", err)
   }
   

   In the code, set SubnetId in NetworkInterfaceSpec to the subnet ID from Prerequisites and ServiceAccountId in InstanceSpec to the ID of the service account you created earlier. The code reads the cloud-init configuration from the cloud-init.yaml file in the working directory.

   cloud_init = Path("cloud-init.yaml").read_text()
   boot_disk_spec = DiskSpec(
       type=DiskSpec.DiskType.NETWORK_SSD,
       size_gibibytes=20,
       source_image_family=SourceImageFamily(
           image_family="ubuntu24.04-driverless",
       ),
   )
   boot_disk = AttachedDiskSpec(
       attach_mode=AttachedDiskSpec.AttachMode.READ_WRITE,
       managed_disk=ManagedDisk(
           name="tunnel-agent-vm-boot",
           spec=boot_disk_spec,
       ),
   )
   network_interface = NetworkInterfaceSpec(
       name="eth0",
       subnet_id="<subnet_ID>",
       ip_address=IPAddress(),
       public_ip_address=PublicIPAddress(),
   )
   create_instance_service = InstanceServiceClient(sdk)
   create_instance_operation = await create_instance_service.create(
       CreateInstanceRequest(
           metadata=ResourceMetadata(
               name="tunnel-agent-vm",
           ),
           spec=InstanceSpec(
               resources=ResourcesSpec(
                   platform="cpu-d3",
                   preset="4vcpu-16gb",
               ),
               boot_disk=boot_disk,
               network_interfaces=[network_interface],
               service_account_id="<service_account_ID>",
               cloud_init_user_data=cloud_init,
           ),
       ),
   )
   await create_instance_operation.wait()
   

   In the code, set subnet_id in NetworkInterfaceSpec to the subnet ID from Prerequisites and service_account_id in InstanceSpec to the ID of the service account you created earlier. The code reads the cloud-init configuration from the cloud-init.yaml file in the working directory.

   const cloudInit = await readFile("cloud-init.yaml", "utf8");
   const sourceImage = SourceImageFamily.create({
     imageFamily: "ubuntu24.04-driverless",
   });
   const bootDiskSpec = DiskSpec.create({
     type: DiskSpec_DiskType.NETWORK_SSD,
     size: {
       $case: "sizeGibibytes",
       sizeGibibytes: 20,
     },
     source: {
       $case: "sourceImageFamily",
       sourceImageFamily: sourceImage,
     },
   });
   const managedDisk = ManagedDisk.create({
     name: "tunnel-agent-vm-boot",
     spec: bootDiskSpec,
   });
   const bootDisk = AttachedDiskSpec.create({
     attachMode: AttachedDiskSpec_AttachMode.READ_WRITE,
     type: {
       $case: "managedDisk",
       managedDisk,
     },
   });
   const networkInterface = NetworkInterfaceSpec.create({
     name: "eth0",
     subnetId: "<subnet_ID>",
     ipAddress: IPAddress.create({}),
     publicIpAddress: PublicIPAddress.create({}),
   });
   const createInstanceService = new InstanceService(sdk);
   const createInstanceOperation =
     await createInstanceService.create(
       CreateInstanceRequest.create({
         metadata: ResourceMetadata.create({
           name: "tunnel-agent-vm",
         }),
         spec: InstanceSpec.create({
           resources: ResourcesSpec.create({
             platform: "cpu-d3",
             size: {
               $case: "preset",
               preset: "4vcpu-16gb",
             },
           }),
           bootDisk: bootDisk,
           networkInterfaces: [networkInterface],
           serviceAccountId: "<service_account_ID>",
           cloudInitUserData: cloudInit,
         }),
       }),
     ).result;
   await createInstanceOperation.wait();
   

   In the code, set subnetId in NetworkInterfaceSpec to the subnet ID from Prerequisites and serviceAccountId in InstanceSpec to the ID of the service account you created earlier. The code reads the cloud-init configuration from the cloud-init.yaml file in the working directory.
3. Get the public IP address of the VM:
   • CLI
   • Go SDK
   • Python SDK
   • JavaScript SDK

   export PUBLIC_IP_ADDRESS=$(nebius compute instance get-by-name \
     --name <VM_name> \
     --format json \
     | jq -r '.status.network_interfaces[0].public_ip_address.address | split("/")[0]')
   

   In the command, specify the name of the VM you created.

   publicInstance, err := sdk.Services().Compute().V1().
       Instance().GetByName(
           ctx,
           &common.GetByNameRequest{
               Name: "<VM_name>",
           },
       )
   if err != nil {
       return err
   }
   publicAddress := publicInstance.GetStatus().
       GetNetworkInterfaces()[0].GetPublicIpAddress().GetAddress()
   publicIPAddress := strings.Split(publicAddress, "/")[0]
   if publicIPAddress == "" {
       return fmt.Errorf("public IP address is missing")
   }
   

   In the code, set Name in GetByNameRequest to the name of the VM you created. The code saves the public IP address to publicIPAddress.

   public_ip_service = InstanceServiceClient(sdk)
   public_instance = await public_ip_service.get_by_name(
       GetByNameRequest(name="<VM_name>"),
   )
   public_address = (
       public_instance.status.network_interfaces[0]
       .public_ip_address.address
   )
   public_ip_address = public_address.split("/")[0]
   

   In the code, set name in GetByNameRequest to the name of the VM you created. The code saves the public IP address to public_ip_address.

   const publicIpInstanceService = new InstanceService(sdk);
   const publicIpInstance = await publicIpInstanceService.getByName(
     GetByNameRequest.create({
       name: "<VM_name>",
     }),
   );
   const publicAddress = publicIpInstance.status
     ?.networkInterfaces[0]?.publicIpAddress?.address;
   let publicIpAddress = publicAddress?.split("/")[0];
   

   In the code, set name in GetByNameRequest to the name of the VM you created. The code saves the public IP address to publicIpAddress.
   To connect from another VM in the same network, get the private IP address or FQDN instead.
4. Connect to the VM:
   ssh <username>@<VM_address_or_FQDN>
   
5. Verify that the agent registered with the tunnel: To confirm that the agent registered with the tunnel, check the status of the service:
   sudo systemctl status nebius-tunnel-agent
   
   For live logs, run:
   sudo journalctl -u nebius-tunnel-agent -f
   
   If the agent doesn’t register, check the logs for these common causes:
   • The VM has no service account attached. systemctl status still shows active (running), but the agent retries indefinitely, showing IMDS token request failed: 404 Not Found followed by connection closed before registering. You can’t attach a service account to an existing VM. Create a new one with --service-account-id instead.
   • The attached service account doesn’t have the applicationtunnel.agent role. The agent authenticates, but the tunnel rejects the connection. Grant the role to the service account as described earlier in this guide.
   In the log output, the agent reports the public endpoint for each service. The endpoint format is:
   <service_name>-<tunnel_masked_ID>.tunnel.applications.<region>.nebius.cloud
   
   Where:
   • service_name is the services.name value from the agent configuration.
   • tunnel_masked_ID is the mask of the tunnel ID without the applicationtunnel- prefix and regional routing code. For example, for applicationtunnel-e00abcdef123456789, the tunnel ID mask is abcdef123456789.
   • region is the region of the project where the tunnel was created, for example eu-north1.