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.

nestri-server discovers GPUs automatically on startup by enumerating /sys/class/drm, reading each card’s PCI vendor ID from /sys/class/drm/cardN/device/vendor, and resolving the human-readable device name from /usr/share/hwdata/pci.ids. By default the server picks the first GPU with a recognised vendor. Every flag described below narrows or overrides that automatic choice.
All flags have a matching environment variable. Environment variables are the recommended approach when running nestri-server inside a container.

​
GPU detection

At startup, nestri-server logs each discovered GPU: 
[INFO] Gathering GPU information..
[INFO] > [GPU:0] RX 7900 XTX (Vendor: AMD, Card Path: /dev/dri/card1, Render Path: /dev/dri/renderD128, PCI Bus ID: 0000:03:00.0)
[INFO] > [GPU:1] UHD Graphics 770 (Vendor: Intel, Card Path: /dev/dri/card0, Render Path: /dev/dri/renderD129, PCI Bus ID: 0000:00:02.0)
The server stores the card path (e.g. /dev/dri/card1) and render node path (e.g. /dev/dri/renderD128) for each GPU. The render node is passed to waylanddisplaysrc as the render-node property. GPUs with unrecognised vendor IDs are silently excluded from auto-selection but can still be forced via --gpu-card-path.

​
Supported vendors

VendorPCI vendor IDEncoder APIGStreamer prefix
NVIDIA0x10deNVENCnv*
AMD0x1002VAAPIva*
Intel0x8086VAAPI / QuickSync (QSV)va* / qsv*

​
Selection flags

The four selection flags are applied as a filter chain: --gpu-vendor and --gpu-name narrow the candidate list, then --gpu-index selects a single entry from that narrowed list. --gpu-card-path is mutually exclusive with all three and bypasses the filter chain entirely.
​
--gpu-vendor
string
Filter GPUs by vendor name. Accepted values (case-insensitive): nvidia, amd, intel.Environment variable: GPU_VENDOR
nestri-server --relay-url ws://relay:8088 --gpu-vendor amd
# or
GPU_VENDOR=amd nestri-server --relay-url ws://relay:8088
​
--gpu-name
string
Filter GPUs by a case-insensitive substring match against the device name from the PCI database. Useful when you have multiple GPUs from the same vendor and want to target one by model.Environment variable: GPU_NAME
# Matches "RX 7900 XTX", "RX 7900 XT", etc.
nestri-server --relay-url ws://relay:8088 --gpu-name "7900"
​
--gpu-index
number
Select by 0-based index from the filtered (or full) GPU list. If the index is out of bounds, the server exits with an error listing the valid range.Environment variable: GPU_INDEX
# Select the second detected GPU
nestri-server --relay-url ws://relay:8088 --gpu-index 1
​
--gpu-card-path
string
Force a specific GPU by supplying the exact /dev/dri/card* or /dev/dri/renderD* path. Both forms are accepted and matching is case-insensitive. This flag conflicts with --gpu-vendor, --gpu-name, and --gpu-index — you cannot combine it with any of them.Environment variable: GPU_CARD_PATH
nestri-server --relay-url ws://relay:8088 --gpu-card-path /dev/dri/renderD128

​
Docker GPU passthrough

The container needs access to the host GPU devices. The correct method depends on the vendor.
Install the NVIDIA Container Toolkit and pass --gpus all (or a specific device with --gpus '"device=0"'):
docker run -d \
  --gpus all \
  -e RELAY_URL="wss://relay.example.com" \
  -e NESTRI_ROOM="my-room" \
  ghcr.io/nestrilabs/nestri/runner:nightly-steam-v3
To select a specific NVIDIA GPU when multiple are present, combine GPU_VENDOR and GPU_INDEX:
docker run -d \
  --gpus all \
  -e RELAY_URL="wss://relay.example.com" \
  -e NESTRI_ROOM="my-room" \
  -e GPU_VENDOR=nvidia \
  -e GPU_INDEX=1 \
  ghcr.io/nestrilabs/nestri/runner:nightly-steam-v3

​
Zero-copy mode

​
--zero-copy
boolean
default:"false"
Enable zero-copy frame transfer between the display capture source and the hardware encoder. When enabled, frames bypass system memory and travel over DMA-BUF (for VAAPI and QSV) or CUDA shared memory (for NVENC), which can reduce latency and CPU overhead on some systems.Environment variable: ZERO_COPYZero-copy is only supported with hardware encoders. If --zero-copy is set alongside --video-encoder-type software, the server emits a warning and disables zero-copy automatically.
Zero-copy is experimental. It may improve performance on some GPU/driver combinations and fail silently or produce artefacts on others. Test carefully before enabling it in production.
When zero-copy is active, the GStreamer caps on the video source change:
Encoder APIMemory typeIntermediate element
VAAPI / QSVvideo/x-raw(memory:DMABuf)vapostproc → video/x-raw(memory:VAMemory)
NVENCvideo/x-raw(memory:CUDAMemory)None — fed directly to the encoder

​
Software rendering

​
--software-render
boolean
default:"false"
Use CPU-based software rendering for the Wayland display instead of a GPU render node. When enabled, waylanddisplaysrc is started with render-node=software.Environment variable: SOFTWARE_RENDERThis flag is useful for debugging or for running nestri-server in environments without a discrete GPU, but it is not suitable for real-time game streaming due to high CPU load and latency.
You can combine --software-render with a hardware video encoder. The display will be rendered on the CPU, but the resulting frames can still be handed off to a hardware encoder for efficient compression.

Build docs developers (and LLMs) love

Get started for freeTalk to us