Skip to main content

Getting Started

This guide will get you running with a LiveKit installation in minutes.

Overview

At its core, LiveKit is a WebRTC SFU. This means it acts as a WebRTC peer and maintains connections with each participant in a room. Unlike vanilla WebRTC, each client participant connects to the LiveKit server, not to one another.

LiveKit uses JWT-based access tokens for authentication. Using LiveKit's server SDK, access tokens are generated with an API key and secret pair. This exchange takes place on the server side to avoid embedding the secret in client code. Here's the general flow:

  • your backend server generates an access token using LiveKit's server SDK
  • your client obtains this token from your backend
  • your client passes the token to LiveKit's client SDK
  • the LiveKit client connects to a LiveKit server instance with the provided token
  • LiveKit server validates the token and accepts your incoming connection

Setting up the server

Docker

LiveKit is published to docker hub. Everything in this guide can be done using the published docker image.

Building from source

Alternatively, you can build LiveKit on your machine. To do so, there are a few prerequisites:

  • Go 1.15+ is installed
  • GOPATH/bin is in your PATH

Then run:

git clone https://github.com/livekit/livekit-server
cd livekit-server
./bootstrap.sh
mage

Generate API key and secret

LiveKit server requires one or more sets of API key and secret pairs to authenticate clients. For your convenience, we've included a secure key/secret generator with the server binary.

% docker run --rm livekit/livekit-server generate-keys
API Key:  APIxxxxxxxx
API Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Start the server

docker run --rm \
-p 7880:7880 \
-p 7881:7881 \
-p 7882:7882/udp \
-e LIVEKIT_KEYS="<api-key>: <api-secret>" \
livekit/livekit-server \
--dev \
--node-ip=<machine-ip>

--node-ip is required when running via Docker with bridge networking (default).

2021-05-16T00:17:18.816-0700    INFO    server/main.go:176  configured key provider {"num_keys": 1}
2021-05-16T00:17:18.948-0700 INFO server/main.go:225 using single-node routing
2021-05-16T00:17:18.951-0700 INFO service/server.go:162 starting LiveKit server {"address": ":7880", "nodeId": "ND_nMu0nVnx", "version": "0.9.3", "rtc.tcp_port": 7881, "rtc.udp_port": 7882}

You now have an instance of LiveKit running in single-node mode! While this mode is suitable for development purposes, we don't recommended it for production.

Generate access token

For security, every participant that connects to a room needs an access token. By substituting a unique string for $participant_identity, you can generate a development access token with the following command:

docker run --rm -e LIVEKIT_KEYS="<api-key>: <api-secret>" livekit/livekit-server create-join-token --room myroom --identity $participant_identity
note

This token expires after a month, which is useful for development and testing, but inappropriate for use in production. To generate production tokens, see Access Token guide.

Connecting to your room

You are now ready to connect to the room with a client. Head over to our example browser client, paste the token you generated, and voilà! You are live with LiveKit.

browser client screenshot

Integrating Client SDKs

The JS client SDK is published to npm. Here's an example app using the JS SDK.

yarn

yarn add livekit-client

npm

npm install --save livekit-client

Integrating Server SDKs

The following server SDKs are designed to be used by your backend code. For access control to a room, the server SDKs generate and sign a one-time token for each client that connects to the room.

Server SDK is published to npm

yarn

yarn add livekit-server-sdk

npm

npm install --save livekit-server-sdk