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, connect to a Compute virtual machine (VM), deploy a demo service on it, run the tunnel agent 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

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
Create a Compute VM with a public IP address or select an existing one that has a public IP address. You need to use this address only to connect to the VM over SSH. Tunnels don’t require a public IP address or any firewall configuration on the VM.
Set up SSH access to the VM.
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’ll 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

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 an authorized key pair:

openssl genrsa -out ./private_key.pem 4096
openssl rsa -in ./private_key.pem -pubout -out ./public_key.pem

Upload the public key and save its ID:

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}')

Connect to the VM

Copy the service account private key to the VM:
scp ./private_key.pem <username>@<VM_address_or_FQDN>:~/private_key.pem
In subsequent steps, the tunnel agent running on the VM uses this private key to authenticate as the service account that you set up earlier.
Note the values you’ll need to fill in the agent configuration on the VM:
echo $TUNNEL_ID $SA_ID $PUBLIC_KEY_ID
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 busybox’s 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

Run the tunnel agent

Follow this section on your VM via SSH.

Download and extract the nebius-tunnel-agent binary for Linux x86_64:

curl -LO https://storage.eu-north1.nebius.cloud/products/releases/nebius-tunnel-agent/latest/nebius-tunnel-agent-linux-x86_64.tar.gz
tar -xzf nebius-tunnel-agent-linux-x86_64.tar.gz

Create config.yaml for the agent:

cat > config.yaml <<EOF
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
EOF

In the file, replace the placeholders with the values you created locally:

<tunnel_ID> with the value of $TUNNEL_ID
<service_account_ID> with the value of $SA_ID
<authorized_key_ID> with the value of $PUBLIC_KEY_ID

Run the agent:
./nebius-tunnel-agent -config ./config.yaml
When the agent connects, it returns 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

​Connect to the VM

​Prepare and deploy a local HTTP service

​Run the tunnel agent

​Access the service on the VM via the tunnel

Costs

Prerequisites

Steps

Create a tunnel

Prepare agent access

Connect to the VM

Prepare and deploy a local HTTP service

Run the tunnel agent

Access the service on the VM via the tunnel