Getting started with Nebius Tunnels: Connect a VM service to the internet

The Nebius Tunnels service exposes a service to the internet without configuring firewall ports. Your service could be running anywhere: on a VM, your local machine, or another cloud provider. In this guide, you’ll create a tunnel, prepare access for a tunnel agent, create a Compute virtual machine (VM) with the agent preinstalled, deploy a demo service on it, and access the service through a public tunnel URL.

Costs

Nebius Tunnels is provided free of charge during preview. If you create a VM for this guide, Nebius AI Cloud charges you for Compute resources.

Prerequisites

Make sure you are in a group that has the admin role within your tenant or project; for example, the default admins group. You can check this in the Administration → IAM section of the web console. You need this role to create a group and grant it a role for the tunnel. You also need the admin role to create a VM with a service account attached. Create the service account in the same project as the VM. The tunnel agent authenticates as this service account, so it only needs the applicationtunnel.agent role for the tunnel. It doesn’t need any Compute permissions.
A VM’s service account is set only at creation and can’t be changed afterwards. To attach a different service account, create a new VM.
Install and configure the Nebius AI Cloud CLI.
Check that your project ID is saved in the Nebius AI Cloud CLI profile configuration:
cat ~/.nebius/config.yaml
Get the subnet ID for the VM you create.
Get the project ID and save it to an environment variable:
export PROJECT_ID=<project_ID>
Get the tenant ID and save it to an environment variable:
export TENANT_ID=<tenant_ID>
You need the tenant ID when granting the service account access to Nebius Tunnels.

Steps

Create a tunnel

Create a tunnel and save its ID:

export TUNNEL_ID=$(nebius tunnel create \
  --title "quickstart-tunnel" \
  --format jsonpath='{.metadata.id}')

Prepare agent access

On the VM, the tunnel agent authenticates through the instance metadata service — no need to generate or copy keys.

Create a service account for the tunnel agent and save its ID:

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

Create a group for Nebius Tunnels service accounts and save its ID:

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

Grant the group the applicationtunnel.agent role for the tunnel:

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

Add the service account to the group:

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

Create the VM

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 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.

Create the VM:

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.

Get the public IP address of the VM:

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.

Connect to the VM:
ssh <username>@<VM_address_or_FQDN>

Prepare and deploy a local HTTP service

Follow this section on your VM via SSH.

Start the busybox HTTP server on your VM:

Install the busybox package:

sudo apt-get update && sudo apt-get install -y busybox

In your home directory, create a www/ directory and add an HTML file to serve via the tunnel:

mkdir -p ~/www
cat > ~/www/index.html <<'EOF'
<!DOCTYPE html>
<html>
<head>
  <title>Nebius Tunnels test</title>
</head>
<body>
  <h1>Nebius Tunnels test page</h1>
  <p>This page tests the functionality of the Nebius Tunnels service.</p>
</body>
</html>
EOF

Create a unit file:

sudo tee /etc/systemd/system/busybox-httpd.service > /dev/null <<'EOF'
[Unit]
Description=Busybox HTTP service
After=network.target

[Service]
ExecStart=/bin/busybox httpd -f -p 8080 -h /home/<username>/www
Restart=on-failure
User=<username>

[Install]
WantedBy=multi-user.target
EOF

In the unit file, replace <username> with the username you used to connect to the VM.

Apply the new unit file, start the busybox-httpd service and check its status:

sudo systemctl daemon-reload
sudo systemctl enable --now busybox-httpd
sudo systemctl status busybox-httpd

Verify the tunnel agent

Follow this section on your VM via SSH.

The cloud-init configuration installs and starts the tunnel agent automatically when the VM boots, so there’s nothing left to run manually. 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 in the following format:

<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.

Access the service on the VM via the tunnel

On your local machine, add https:// to the beginning of the public endpoint address and open it in your browser, or run curl https://<public_endpoint> in your terminal.

​Costs

​Prerequisites

​Steps

​Create a tunnel

​Prepare agent access

​Create the VM

​Prepare and deploy a local HTTP service

​Verify the tunnel agent

​Access the service on the VM via the tunnel

Costs

Prerequisites

Steps

Create a tunnel

Prepare agent access

Create the VM

Prepare and deploy a local HTTP service

Verify the tunnel agent

Access the service on the VM via the tunnel