Skip to main content
IntroductionBuild AgentsAgent FrontendsTest & EvaluateTelephonyRoboticsWebRTC TransportManage & DeployReferences
XYouTubeSlack

Load testing

Simulate publishers, subscribers, and agent sessions with the lk perf commands.

On this page

Overview Subcommands Load test Agent load test

Overview

Use the lk perf commands to put simulated load on a LiveKit server or a running agent. For sizing guidance and sample results, see Benchmarking. To install the CLI, see Install the CLI.

lk perf [command [command options]]

Target a server with --project or --url, --api-key, and --api-secret, or use the default project.

Run the load tester on a machine with plenty of CPU and bandwidth. Large tests can need a higher open file limit (ulimit -n 65535). For more load than one machine can generate, run it from several machines.

Caution

Load testing on LiveKit Cloud is restricted by the acceptable use policy  and load-test allows at most 50 each of video publishers, audio publishers, and subscribers. Test traffic counts toward your plan's included allowances.

Subcommands

Load test

Run simulated publishers and subscribers in a single room, then print per-track and per-subscriber statistics such as bitrate and packet loss.

lk perf load-test [options]

Alias: lk load-test.

When you set both --video-publishers and --audio-publishers, the first participants publish both audio and video. With no publisher or subscriber counts, the test runs with one video publisher and one subscriber.

Options for perf load-test:

  • --room NAME: Name of the room to join. Default: a random name like testroom123.
  • --duration TIME: How long to run after all participants connect, such as 1m or 1h. Default: runs until canceled.
  • --video-publishers NUMBER: Number of participants that publish video tracks. Alias: --publishers. Default: 0.
  • --audio-publishers NUMBER: Number of participants that publish audio tracks. Default: 0.
  • --subscribers NUMBER: Number of participants that subscribe to tracks. Default: 0.
  • --identity-prefix PREFIX: Identity prefix for simulated participants. Default: a random prefix.
  • --video-resolution QUALITY: Resolution of published video: high, medium, or low. Default: high.
  • --video-codec CODEC: Video codec to publish: h264 or vp8. Default: publishers alternate between both codecs.
  • --num-per-second NUMBER: Number of participants to connect each second, up to 10. Default: 5.
  • --layout LAYOUT: Layout that subscribers simulate, which sets how many videos each one receives and at what quality. Default: speaker.
    • speaker: One video at high quality and five at low quality.
    • 3x3: Nine videos at medium quality.
    • 4x4: Sixteen videos at low quality.
    • 5x5: Twenty-five videos at low quality.
  • --no-simulcast: Publish video without simulcast. Default: false.
  • --simulate-speakers: Simulate random active speaker changes. Default: false.

Examples

Simulate an audio-only room with 10 speakers and 50 listeners for five minutes:

lk perf load-test \
  --room load-test \
  --audio-publishers 10 \
  --subscribers 50 \
  --duration 5m

Simulate a 25-person video conference in a 5x5 grid:

lk perf load-test \
  --room load-test \
  --video-publishers 25 \
  --audio-publishers 25 \
  --subscribers 25 \
  --layout 5x5 \
  --simulate-speakers \
  --duration 10m

Agent load test

Run a load test against a running agent. The CLI opens rooms one at a time, dispatches the agent to each, and plays the agent's speech back to it after a delay to simulate a user. When the test ends, it prints each room's dispatch time and agent join delay.

lk perf agent-load-test --rooms NUMBER --agent-name AGENT_NAME [options]

The agent must already be running in the same project, locally or on LiveKit Cloud. Without --agent-name, the agent must join through automatic dispatch.

Options for perf agent-load-test:

  • --rooms NUMBER: Number of rooms to open. Default: 0.
  • --agent-name NAME: Dispatch name of the running agent to dispatch to each room.
  • --echo-speech-delay DURATION: Delay before playing the agent's speech back. Default: 5s.
  • --duration TIME: How long to run, such as 1m or 1h. Default: runs until canceled.
  • --attribute KEY=VALUE: Attribute to set on the simulated participant. Repeatable.
  • --attribute-file JSON: JSON file of string attributes to set on the simulated participant. Overrides matching --attribute keys.

Examples

Open 20 sessions with the agent named my-agent for 10 minutes:

lk perf agent-load-test \
  --rooms 20 \
  --agent-name my-agent \
  --duration 10m

Pass participant attributes your agent reads at session start:

lk perf agent-load-test \
  --rooms 5 \
  --agent-name my-agent \
  --attribute-file attributes.json \
  --attribute scenario=load-test \
  --echo-speech-delay 2s