Skip to main content
IntroductionBuild AgentsAgent FrontendsTelephonyRoboticsWebRTC TransportManage & DeployReferences
XYouTubeSlack

Set up a private link on AWS

Connect a deployed LiveKit agent to a private service in your AWS network using AWS PrivateLink.

On this page

Overview Prerequisites Step 1: Create an endpoint service Step 2: Create a private link in LiveKit Step 3: Approve the connection in AWS Step 4: Confirm the link is healthy Step 5: Test from your agent Troubleshooting Additional resources

Overview

This guide shows how to set up a private link on AWS, connecting a deployed LiveKit agent to a private service in your AWS network over AWS PrivateLink. To learn more, see Private Links.

You expose your service in AWS, then create the private link with the LiveKit CLI.

Prerequisites

Before you begin, make sure you have the following:

Your NLB must be configured as follows:

  • Has a listener configured for the required TCP or TLS port.
  • Forwards to a target group whose targets are all healthy.
  • Spans at least two Availability Zones.
  • Has security groups and network ACLs that permit the expected traffic.

Step 1: Create an endpoint service

Private Links connect to an AWS endpoint service backed by a Network Load Balancer (NLB).

  1. Sign in to the AWS Console .

  2. Select VPC → PrivateLink and Lattice → Endpoint services.

  3. Select Create endpoint service.

  4. For Endpoint service settings, select Network.

  5. For Available load balancers, select your NLB.

  6. In the Additional settings section, select Acceptance required so connections wait for your approval.

  7. Select Create.

    Note the generated service name for the next step. It has the following form:

    com.amazonaws.vpce.<AWS_REGION>.vpce-svc-0a1b2c3d4e5f67890

  8. On the endpoint service details page, select Allow principals → Allow principals.

  9. In the Principals to add section, copy and paste the ARN of the LiveKit production principal:

    arn:aws:iam::266092630715:root

    This authorizes LiveKit to connect to your endpoint service. Don't use a wildcard principal. Adding the LiveKit principal explicitly ensures only authorized LiveKit connections can reach your service.

  10. Select Allow principals.

  1. Create the endpoint service for your NLB, requiring acceptance so connections wait for your approval:

    aws ec2 create-vpc-endpoint-service-configuration \
      --region <AWS_REGION> \
      --network-load-balancer-arns <NLB_ARN> \
      --acceptance-required

    The following example response includes the service ID and the generated service name. Note the ServiceId and ServiceName for the next steps:

    "ServiceId": "vpce-svc-0a1b2c3d4e5f67890",
    "ServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-0a1b2c3d4e5f67890"

  2. Allow LiveKit to connect by adding the LiveKit production principal:

    aws ec2 modify-vpc-endpoint-service-permissions \
      --region <AWS_REGION> \
      --service-id <SERVICE_ID> \
      --add-allowed-principals arn:aws:iam::266092630715:root

    This authorizes LiveKit to connect to your endpoint service. Don't use a wildcard principal. Adding the LiveKit principal explicitly ensures only authorized LiveKit connections can reach your service.

Step 2: Create a private link in LiveKit

Create a link with the LiveKit CLI or the LiveKit Cloud dashboard. For all CLI options, see the private-link create reference.

  1. Navigate to your project Settings page (https://cloud.livekit.io/projects/p_/settings/private-links) → Private links.
  2. Select Create new private link.
  3. Enter a name for the link and complete all other fields:
    • The LiveKit region must match the region your agent is deployed to.
    • For Cloud provider, select AWS.
    • The Port field must match the port configured for your NLB listener.
    • For Endpoint, enter the name of the AWS endpoint service you created in the previous step.
  4. Select Create.
lk --project <LIVEKIT_PROJECT> agent private-link create \
  --name <LINK_NAME> \
  --region <LIVEKIT_AGENT_REGION> \
  --port <TCP_PORT> \
  --endpoint '<AWS_ENDPOINT_SERVICE_NAME>'

Replace the following:

  • <LIVEKIT_PROJECT> Name of the project you want to create the link in.
  • <LINK_NAME> Name of the link you want to create.
  • <LIVEKIT_AGENT_REGION> Region your LiveKit agent is deployed to.
  • <TCP_PORT> Port your agent needs to reach. It must match the port configured for your NLB listener.
  • <AWS_ENDPOINT_SERVICE_NAME> Name of the endpoint service you created in the previous step.

LiveKit derives the AWS region from the endpoint service name, so you don't need to pass it separately. Your endpoint service doesn't need to be in the same region as your agent, but using the same region reduces latency. For a list of supported regions, see Supported providers and regions.

For example, the following command creates a private link named customer-redis to an endpoint service in the us-east-1 AWS region:

lk --project production agent private-link create \
  --name customer-redis \
  --region us-east \
  --port 6379 \
  --endpoint 'com.amazonaws.vpce.us-east-1.vpce-svc-0a1b2c3d4e5f67890'

Save the private link ID and the generated *.link hostname for later use.

Step 3: Approve the connection in AWS

After you create the link, LiveKit requests a connection to your endpoint service. You must approve the request in AWS.

Links must be in pending approval state to approve

Wait for the private link status to reach PENDING_APPROVAL before you approve the request in AWS. To view the status, see Confirm the link is healthy.

  1. In the AWS Console, select VPC → PrivateLink and Lattice → Endpoint services.
  2. Select your endpoint service and select the Endpoint connections tab.
  3. Find the pending connection and verify the requester account is 266092630715.
  4. Select Accept endpoint connection request.

  1. List pending connection requests, and verify the requester is 266092630715:

    aws ec2 describe-vpc-endpoint-connections \
      --region <AWS_REGION> \
      --filters Name=service-id,Values=<SERVICE_ID> \
                Name=vpc-endpoint-state,Values=pendingAcceptance \
      --query "VpcEndpointConnections[].{Endpoint:VpcEndpointId,Requester:VpcEndpointOwner}" \
      --output table

  2. Accept the connection request using the VPC endpoint ID from the previous command:

    aws ec2 accept-vpc-endpoint-connections \
      --region <AWS_REGION> \
      --service-id <SERVICE_ID> \
      --vpc-endpoint-ids <VPC_ENDPOINT_ID>

For the full CLI reference, see aws ec2 describe-vpc-endpoint-connections  and aws ec2 accept-vpc-endpoint-connections .

The connection can take a few minutes to appear while LiveKit provisions resources.

Step 4: Confirm the link is healthy

Check the link status before you connect from your agent. The link moves through PROVISIONING and PENDING_APPROVAL states before reaching HEALTHY. Wait for a HEALTHY status before you connect. For the full list of statuses, see Status values.

Check the link status using the CLI or the LiveKit Cloud dashboard:

View the link status on the Private links  page in the Status column.

lk --project <LIVEKIT_PROJECT> agent private-link health-status \
  --id <PRIVATE_LINK_ID>

Step 5: Test from your agent

The *.link hostname resolves only from a deployed agent, so run any connectivity test from within your agent runtime, not locally.

The following Python code opens 20 connections in a row and fails if any of them don't succeed:

import socket


host = "<GENERATED_HOSTNAME>.link"
port = <TCP_PORT>
attempts = 20
successes = 0


for attempt in range(1, attempts + 1):
    try:
        # The .link hostname resolves only inside the agent runtime.
        with socket.create_connection((host, port), timeout=10):
            successes += 1
            print(f"success: {attempt}/{attempts}")
    except Exception as error:
        print(f"failure: {attempt}/{attempts}: {error}")


if successes != attempts:
    raise RuntimeError(f"Private Links test failed: {successes}/{attempts} succeeded")

After you confirm TCP connectivity, send a real request to your service (for example, a Redis PING or a database query) to verify authentication, TLS, and end-to-end behavior.

Troubleshooting

IssueResolution
Service not foundVerify the endpoint service name and that you allowed the LiveKit principal.
Region unavailableContact LiveKit to enable support for that AWS region.
No endpoint connection appearsConfirm the allowed principal, wait a few minutes, and verify the Availability Zone coverage of the NLB.
Stuck in pending approvalAccept the endpoint connection request in AWS.
Approved but unhealthyCheck NLB target health, listener and target ports, security groups, ACLs, and Availability Zones.
Connection timeoutVerify the service listens on the configured port and accepts NLB traffic.
DNS failure in the agentConfirm the agent uses the same LiveKit region as the link and the generated *.link hostname.
TLS certificate failureConfigure the client TLS server name, or handle TLS termination at the correct layer.
Test fails from your local machineThe *.link hostname resolves only inside a deployed agent. Run connectivity tests from your agent runtime, not locally.

Additional resources

The following topics provide additional information about Private Links.

Private Links

How Private Links work, supported regions, and limitations.

AWS PrivateLink docs

Learn how to create and configure AWS PrivateLink-based VPC endpoints.

Monitor and manage Private Links

Check link status and manage links programmatically.

Private Links CLI reference

Reference for the private link commands in the LiveKit CLI.

Set up on Azure

Connect through Azure Private Link using a Private Link Service.