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

​
Prerequisites

  1. Install and configure the Nebius CLI.
  2. Get the project ID and the tenant ID, and save them to environment variables: 
    export PROJECT_ID=<project_ID>
export TENANT_ID=<tenant_ID>
  3. Get the tunnel ID by listing tunnels in your project: 
    nebius tunnel list
    The command uses the project ID from your CLI profile configuration. Copy the ID of the tunnel that you want to connect to and save it to an environment variable: 
    export TUNNEL_ID=<tunnel_ID>

​
Connecting a service

  1. Install Docker Engine.
  2. Create a service account and save its ID: 
    export SA_ID=$(nebius iam service-account create \
  --name "tunnel-agent" \
  --parent-id "$PROJECT_ID" \
  --format jsonpath='{.metadata.id}')
    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.
  3. 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}')
  4. 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
    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.
  5. Add the service account to the group: 
    nebius iam group-membership create \
  --parent-id "$GROUP_ID" \
  --member-id "$SA_ID"
  6. Create a key pair: 
    openssl genrsa -out "./private_key.pem" 4096
openssl rsa -in "./private_key.pem" -pubout -out "./public_key.pem"
  7. 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}')
  8. Create config.yaml for the agent: 
    cat > config.yaml <<EOF
tunnel_id: $TUNNEL_ID

iam:
  service_account:
    service_account_id: $SA_ID
    public_key_id: $PUBLIC_KEY_ID
    private_key_path: "./private_key.pem"

services:
  - name: web
    target: localhost:8080
    type: http
EOF
    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
  9. 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-<routing_code>abcdef1234, the tunnel ID mask is abcdef1234.
    • region is the region of the project where the tunnel was created, for example eu-north1.