Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nestrilabs/nestri/llms.txt

Use this file to discover all available pages before exploring further.

Every nestri-server flag can be set by a CLI argument or a matching environment variable. Environment variables take the same values as the CLI flags and are the recommended approach when running the server inside a container. This page lists all flags grouped by category.
Pass --verbose (or set VERBOSE=true) to print the resolved value of every flag at startup — useful for verifying container configuration.

​
Application

These flags control the relay connection, virtual display, and general runtime behaviour.
​
--relay-url
string
required
WebSocket URL of the Nestri relay server. The server connects to this address over libp2p to exchange WebRTC session descriptions with browser clients.Environment variable: RELAY_URL
nestri-server --relay-url wss://relay.nestri.io
​
--room
string
Room name or identifier. Browser clients connect to this room to receive the stream. If not set, a random numeric ID is generated at startup.Environment variable: NESTRI_ROOM
​
--resolution
string
default:"1280x720"
Display and stream resolution in WxH format. Sets both the Wayland virtual display size and the GStreamer capsfilter applied to the video source.Environment variable: RESOLUTION
nestri-server --relay-url wss://relay.nestri.io --resolution 1920x1080
​
--framerate
number
default:"60"
Display and stream framerate. Valid range: 5–239 fps. This value is used in both the Wayland display configuration and the GStreamer caps.Environment variable: FRAMERATE
​
--vimputti-path
string
default:"/tmp/vimputti-0"
Path to the vimputti Unix socket. vimputti manages virtual input devices (gamepad, keyboard, mouse) forwarded from the browser. If the socket is not present at startup, input forwarding is disabled with a warning rather than a hard failure.Environment variable: VIMPUTTI_PATH
​
--verbose
boolean
default:"false"
Enable verbose output. When set, all resolved argument values are logged at startup and encoder parameter assignment is logged at DEBUG level.Environment variable: VERBOSE

​
Device

These flags control GPU selection and display rendering mode.
​
--gpu-vendor
string
Filter GPUs by vendor. Accepted values (case-insensitive): nvidia, amd, intel.Environment variable: GPU_VENDOR
​
--gpu-name
string
Filter GPUs by a case-insensitive substring match against the PCI device name (e.g. "7900" matches "RX 7900 XTX").Environment variable: GPU_NAME
​
--gpu-index
number
Select by 0-based index from the filtered GPU list. Out-of-bounds values cause a startup error.Environment variable: GPU_INDEX
​
--gpu-card-path
string
Force a specific GPU using a /dev/dri/card* or /dev/dri/renderD* path. Mutually exclusive with --gpu-vendor, --gpu-name, and --gpu-index.Environment variable: GPU_CARD_PATH
​
--software-render
boolean
default:"false"
Use CPU-based software rendering for the Wayland display (render-node=software). Not suitable for real-time game streaming.Environment variable: SOFTWARE_RENDER
​
--zero-copy
boolean
default:"false"
Enable zero-copy frame transfer (DMA-BUF for VAAPI/QSV, CUDA memory for NVENC). Experimental. Requires --video-encoder-type hardware.Environment variable: ZERO_COPY

​
Video encoding

​
--video-codec
string
default:"h264"
Preferred video codec. Accepted values: h264, h265, av1.Environment variable: VIDEO_CODEC
​
--video-encoder
string
Override automatic encoder selection with a specific GStreamer element name (e.g. nvh264enc, vah265lpenc).Environment variable: VIDEO_ENCODER
​
--video-encoder-type
string
default:"hardware"
Constrain encoder selection to hardware or software.Environment variable: VIDEO_ENCODER_TYPE
​
--video-rate-control
string
default:"cbr"
Rate control method. Accepted values: cbr, vbr, cqp.Environment variable: VIDEO_RATE_CONTROL
​
--video-latency-control
string
default:"lowest-latency"
Latency vs. quality tuning preset. Accepted values: lowest-latency, highest-quality.Environment variable: VIDEO_LATENCY_CONTROL
​
--video-cqp
number
default:"26"
Constant Quantization Parameter quality level (1–51). Lower is higher quality. Used only with --video-rate-control cqp.Environment variable: VIDEO_CQP
​
--video-bitrate
number
default:"6000"
Target video bitrate in kbps. Used by cbr and vbr rate control.Environment variable: VIDEO_BITRATE
​
--video-bitrate-max
number
default:"8000"
Maximum video bitrate in kbps. Used only by vbr rate control.Environment variable: VIDEO_BITRATE_MAX
​
--video-bit-depth
number
default:"8"
Video bit depth. Accepted values: 8, 10. 10-bit requires --zero-copy, a non-H.264 codec, and a capable encoder.Environment variable: VIDEO_BIT_DEPTH
​
--keyframe-dist-secs
number
default:"1"
Distance between keyframes in seconds. GOP size = framerate × keyframe-dist-secs.Environment variable: KEYFRAME_DIST_SECS

​
Audio

​
--audio-capture-method
string
default:"pipewire"
Audio capture backend. Accepted values: pipewire, pulseaudio, alsa.Environment variable: AUDIO_CAPTURE_METHOD
​
--audio-codec
string
default:"opus"
Preferred audio codec. Currently only opus is supported.Environment variable: AUDIO_CODEC
​
--audio-encoder
string
Override the audio encoder GStreamer element name. Defaults to opusenc.Environment variable: AUDIO_ENCODER
​
--audio-rate-control
string
default:"cbr"
Audio rate control method. Accepted values: cbr, vbr. CQP is not supported for audio.Environment variable: AUDIO_RATE_CONTROL
​
--audio-latency-control
string
default:"lowest-latency"
Audio latency tuning preset. Accepted values: lowest-latency, highest-quality.Environment variable: AUDIO_LATENCY_CONTROL
​
--audio-bitrate
number
default:"128"
Target audio bitrate in kbps.Environment variable: AUDIO_BITRATE
​
--audio-bitrate-max
number
default:"192"
Maximum audio bitrate in kbps. Used only by vbr rate control.Environment variable: AUDIO_BITRATE_MAX

​
Complete Docker example

The following example runs the Nestri Steam runner container with a full explicit configuration. All settings are passed as environment variables, which is the recommended pattern for containerised deployments. 
docker run -d \
  --gpus all \
  -e RELAY_URL="wss://relay.nestri.io" \
  -e NESTRI_ROOM="my-game-room" \
  -e RESOLUTION="1920x1080" \
  -e FRAMERATE="60" \
  -e GPU_VENDOR="nvidia" \
  -e VIDEO_CODEC="h264" \
  -e VIDEO_RATE_CONTROL="cbr" \
  -e VIDEO_BITRATE="8000" \
  -e VIDEO_BITRATE_MAX="10000" \
  -e VIDEO_LATENCY_CONTROL="lowest-latency" \
  -e VIDEO_ENCODER_TYPE="hardware" \
  -e KEYFRAME_DIST_SECS="1" \
  -e AUDIO_CAPTURE_METHOD="pipewire" \
  -e AUDIO_CODEC="opus" \
  -e AUDIO_BITRATE="128" \
  -e VERBOSE="false" \
  ghcr.io/nestrilabs/nestri/runner:nightly-steam-v3

Build docs developers (and LLMs) love

Get started for freeTalk to us