.\" Generated by scdoc 1.11.5 .\" Complete documentation for this program is not available as a GNU info page .ie \n(.g .ds Aq \(aq .el .ds Aq ' .nh .ad l .\" Begin generated content: .TH "wayvnc" "1" "2026\-07\-19" .PP .SH NAME .PP wayvnc \- A VNC server for wlroots\-based Wayland compositors.\& .PP .SH SYNOPSIS .PP \fBwayvnc\fR [options] [address.\&.\&.\&] .PP .SH OPTIONS .PP \fB\-a, \-\-desktop\fR .RS 4 Capture all outputs.\& .PP .RE \fB\-C, \-\-config=\fR .RS 4 Select a config file.\& .PP .RE \fB\-d, \-\-disable\-input\fR .RS 4 Disable all remote input.\& This allows using wayvnc without compositor support of virtual mouse / keyboard protocols.\& .PP .RE \fB\-D, \-\-detached\fR .RS 4 Start detached from a compositor.\& Run \fBwayvncctl attach\fR to attach to a compositor.\& .PP .RE \fB\-f, \-\-max\-fps=\fR .RS 4 Set the rate limit (default 30).\& .PP .RE \fB\-F, \-\-log\-filter=\fR .RS 4 Set a log filter.\& .PP .RE \fB\-g, \-\-gpu\fR .RS 4 Enable features that require GPU.\& .PP .RE \fB\-h, \-\-help\fR .RS 4 Get help.\& .PP .RE \fB\-k, \-\-keyboard=[\-variant]\fR .RS 4 Select keyboard layout.\& The variant can be appended if needed.\& .PP .RE \fB\-L, \-\-log\-level\fR .RS 4 Set log level.\& The levels are: error, warning, info, debug, trace and quiet.\& .PP .RE \fB\-n, \-\-name=\fR .RS 4 Set the desktop name.\& Default: WayVNC .PP .RE \fB\-o, \-\-output=\fR .RS 4 Select output to capture.\& .PP .RE \fB\-p, \-\-show\-performance\fR .RS 4 Show performance counters.\& .PP .RE \fB\-r, \-\-render\-cursor\fR .RS 4 Enable overlay cursor rendering.\& .PP .RE \fB\-R, \-\-disable\-resizing\fR .RS 4 Disable automatic desktop resizing.\& .PP .RE \fB\-s, \-\-seat=\fR .RS 4 Select seat by name.\& .PP .RE \fB\-t, \-\-transient\-seat\fR .RS 4 Create a transient seat for each client session.\& .PP .RE \fB\-T, \-\-toplevel=\fR .RS 4 Capture a toplevel.\& .PP .RE \fB\-S, \-\-socket=\fR .RS 4 Set wayvnc control socket path.\& Default: $XDG_RUNTIME_DIR/wayvncctl or /tmp/wayvncctl\-$UID .PP .RE \fB\-v, \-\-verbose\fR .RS 4 Be more verbose.\& Same as setting `\-\-log\-level=info`.\& .PP .RE \fB\-V, \-\-version\fR .RS 4 Show version info.\& .PP .RE .SH ADDRESSES .PP Multiple listening addresses can be specified by appending them to the argument list.\& .PP For a regular network address, a port number may be set by appending it to the address with \fB:\fR as a separator; e.\&g.\&: \fBlocalhost:5901\fR.\& .PP IPv6 addresses must be wrapped in square brackets if a port is specified; e.\&g.\& \fB[::]:5901\fR.\& .PP Different socket types may be specified by prefixing the address with the given type name with a \fB:\fR in between; e.\&g.\& \fBunix:/tmp/wayvnc.\&sock\fR.\& The socket types are: tcp, unix, fd, ws, ws\-unix and ws\-fd.\& .PP With the \fBfd\fR type, you can pass an already bound socket for the VNC server to listen on.\& The file descriptor is a numeric value inherited from wayvnc'\&s parent process.\& Example: \fBfd:42\fR.\& .PP The \fBws\fR family of prefixes encapsulates all communication over the given socket using WebSocket framing.\& Example: \fBws:0.\&0.\&0.\&0\fR.\& .PP .SH DESCRIPTION .PP This is a VNC server for wlroots\-based Wayland compositors.\& It attaches to a running Wayland session, creates virtual input devices and exposes a single display via the RFB protocol.\& The Wayland session may be a headless one, so it is also possible to run wayvnc without a physical display attached.\& .PP .SS MULTIPLE OUTPUTS .PP If the Wayland session consists of multiple outputs, only one will be captured.\& By default this will be the first one, but can be specified by the \fI\-o\fR command line argument.\& The argument accepts the short name such as \fIeDP\-1\fR or \fIDP\-4\fR.\& Running wayvnc in verbose mode (\fI\-v\fR) will display the names of all outputs on startup, or you can query them at runtime via the \fBwayvncctl output\-list\fR command.\& .PP You can also change which output is being captured on the fly via the \fBwayvncctl output\-set\fR command.\& .PP .SH CONFIGURATION .PP wayvnc searches for a config file in the location .RS 4 \(ti/$XDG_CONFIG_HOME/wayvnc/config .RE or if $XDG_CONFIG_HOME is not set .RS 4 \(ti/.\&config/wayvnc/config .PP .RE .SS SYNTAX .PP The configuration file is composed of key\-value pairs separated with an \fBequal\fR sign.\& Whitespace around either the key or the value is insignificant and is not considered to be part of the key or the value.\& .PP .SS KEYWORDS .PP \fBaddress\fR .RS 4 The address to which the server shall bind, e.\&g.\& 0.\&0.\&0.\&0 or localhost.\& .PP .RE \fBcertificate_file\fR .RS 4 The path to the certificate file for encryption.\& Only applicable when \fBenable_auth\fR=true.\& .PP .RE \fBenable_auth\fR .RS 4 Enable authentication and encryption.\& Setting this value to \fBtrue\fR requires also setting \fBcertificate_file\fR, \fBprivate_key_file\fR and \fBpassword\fR.\& The \fBusername\fR is optional and defaults to an empty string if not set.\& .PP .RE \fBenable_pam\fR .RS 4 Use PAM for authentication.\& When enabled, PAM overrides \fBusername\fR and \fBpassword\fR settings.\& Some authentication methods such as DES do not work with PAM.\& .PP .RE \fBpassword\fR .RS 4 Choose a password for authentication.\& Required when \fBenable_auth\fR is set and \fBenable_pam\fR is not used.\& .PP .RE \fBport\fR .RS 4 The port to which the server shall bind.\& Default is 5900.\& .PP .RE \fBprivate_key_file\fR .RS 4 The path to the private key file for TLS encryption.\& Only applicable when \fBenable_auth\fR=true.\& .PP .RE \fBrelax_encryption\fR .RS 4 Don'\&t require encryption after the user has been authenticated.\& This enables some security types such as Apple Diffie\-Hellman.\& .PP .RE \fBrsa_private_key_file\fR .RS 4 The path to the private key file for RSA\-AES encryption.\& Only applicable when \fBenable_auth\fR=true.\& .PP .RE \fBusername\fR .RS 4 Choose a username for authentication.\& If not set, defaults to an empty username.\& .PP .RE \fBallow_broken_crypto\fR .RS 4 Allow the use of insecure cryptographic methods such as DES authentication.\& When enabled, legacy VNC clients that do not support modern security types can authenticate using the \fBpassword\fR field.\& Use only for legacy client compatibility on a trusted network.\& .PP .RE \fBuse_relative_paths\fR .RS 4 Make file paths relative to the location of the config file.\& .PP .RE \fBxkb_layout\fR .RS 4 The keyboard layout to use for key code lookup.\& .PP Default: \fIXKB_DEFAULT_LAYOUT\fR or system default.\& .PP .RE \fBxkb_model\fR .RS 4 The keyboard model by which to interpret keycodes and LEDs.\& .PP Default: "pc105" .PP .RE \fBxkb_options\fR .RS 4 A comma\-separated list of options, through which the user specifies non\-layout related preferences such as which key is the Compose key.\& .PP Default: \fIXKB_DEFAULT_OPTIONS\fR or system default.\& .PP .RE \fBxkb_rules\fR .RS 4 The rules file describes how to interpret the values of the model, layout, variant and options fields.\& .PP Default: \fIXKB_DEFAULT_RULES\fR or system default.\& .PP .RE \fBxkb_variant\fR .RS 4 The keyboard variant to use for keycode lookup.\& .PP Default: \fIXKB_DEFAULT_VARIANT\fR or system default.\& .PP .RE .SS EXAMPLE .PP .nf .RS 4 use_relative_paths=true address=0\&.0\&.0\&.0 enable_auth=true username=luser password=p455w0rd rsa_private_key_file=rsa_key\&.pem private_key_file=tls_key\&.pem certificate_file=tls_cert\&.pem .fi .RE .PP .SH WAYVNCCTL CONTROL SOCKET .PP To facilitate runtime interaction and control, wayvnc opens a unix domain socket at \fB$XDG_RUNTIME_DIR\fR/wayvncctl (or a fallback of /tmp/wayvncctl\-\fB$UID\fR).\& A client can connect and exchange JSON\-formatted IPC messages to query and control the running wayvnc instance.\& .PP .SS IPC COMMANDS .PP \fIHELP\fR .PP The \fBhelp\fR command, when issued without any parameters, lists the names of all available commands.\& .PP If an optional \fBcommand\fR parameter refers to one of those commands by name, the response data will be a detailed description of that command and its parameters.\& .PP \fIEVENT\-RECEIVE\fR .PP The \fBevent\-receive\fR command registers for asynchronous server events.\& See the \fIEVENTS\fR section below for details on the event message format, and the \fIIPC EVENTS\fR section below for a description of all possible server events.\& .PP Event registration registers for all available server events and is scoped to the current connection only.\& If a client disconnects and reconnects, it must re\-register for events.\& .PP \fICLIENT\-LIST\fR .PP The \fBclient\-list\fR command retrieves a list of all VNC clients currently connected to wayvnc.\& .PP \fICLIENT\-DISCONNECT\fR .PP The \fBclient\-disconnect\fR command disconnects a single VNC client.\& .PP Parameters: .PP \fBid\fR .RS 4 Required: The ID of the client to disconnect.\& This ID can be found from the \fIGET\-CLIENTS\fR command or receipt of a \fICLIENT\-CONNECTED\fR event.\& .PP .RE \fISET\-DESKTOP\-NAME\fR .PP The \fBset\-desktop\-name\fR command changes the desktop name sent to new clients and updates the name for connected clients that support updating the desktop name.\& .PP Parameters: .PP \fBdesktop\-name\fR .RS 4 Required: The desktop name.\& .PP .RE \fIOUTPUT\-LIST\fR .PP The \fBoutput\-list\fR command retrieves a list of all outputs known to wayvnc and whether or not each one is currently being captured.\& .PP \fIOUTPUT\-CYCLE\fR .PP For multi\-output Wayland displays, the \fBoutput\-cycle\fR command switches which output is actively captured by wayvnc.\& Running this once will switch to the next available output.\& If no more outputs are available, it cycles back to the first again.\& .PP \fIOUTPUT\-SET\fR .PP For multi\-output Wayland displays, the \fBoutput\-set\fR command switches which output is actively captured by wayvnc by name.\& .PP \fBoutput\-name=name\fR .RS 4 Required: The name of the output to capture next.\& .PP .RE \fIVERSION\fR .PP The \fBversion\fR command queries the running wayvnc instance for its version information.\& Much like the \fI\-V\fR option, the response data will contain the version numbers of wayvnc, as well as the versions of the neatvnc and aml components.\& .PP \fIWAYVNC\-EXIT\fR .PP The \fBwayvnc\-exit\fR command disconnects all clients and shuts down wayvnc.\& .PP .SS IPC EVENTS .PP \fICAPTURE_CHANGED\fR .PP The \fBcapture\-changed\fR event is sent when the currently captured output changes.\& .PP Parameters: .PP \fBoutput=.\&.\&.\&\fR .RS 4 The name of the output now being captured.\& .PP .RE \fICLIENT\-CONNECTED\fR .PP The \fBclient\-connected\fR event is sent when a new VNC client connects to wayvnc.\& .PP Parameters: .PP \fBid=.\&.\&.\&\fR .RS 4 A unique identifier for this client.\& .PP .RE \fBconnection_count=.\&.\&.\&\fR .RS 4 The total number of connected VNC clients including this one.\& .PP .RE \fBaddress=.\&.\&.\&\fR .RS 4 The IP address of this client.\& May be null.\& .PP .RE \fBusername=.\&.\&.\&\fR .RS 4 The username used to authenticate this client.\& May be null.\& .PP .RE \fICLIENT\-DISCONNECTED\fR .PP The \fBclient\-disconnected\fR event is sent when a VNC client disconnects from wayvnc.\& .PP Parameters: .PP \fBid=.\&.\&.\&\fR .RS 4 A unique identifier for this client.\& .PP .RE \fBconnection_count=.\&.\&.\&\fR .RS 4 The total number of connected VNC clients not including this one.\& .PP .RE \fBaddress=.\&.\&.\&\fR .RS 4 The IP address of this client.\& May be null.\& .PP .RE \fBusername=.\&.\&.\&\fR .RS 4 The username used to authenticate this client.\& May be null.\& .PP .RE .SS IPC MESSAGE FORMAT .PP The \fBwayvncctl(1)\fR command line utility will construct properly\-formatted json ipc messages, but any client will work.\& The client initiates the connection and sends one or more request objects, each of which will receive a corresponding response object.\& .PP \fBNote\fR: This message format is unstable and may change substantially over the next few releases.\& .PP \fIREQUEST\fR .PP The general form of a json\-ipc request message is: .PP .nf .RS 4 { "method": "command\-name", "id": 123, "params": { "key1": "value1", "key2": "value2", } } .fi .RE .PP The \fBmethod\fR is the name of the command to be executed.\& Use the \fBhelp\fR method to query a list of all valid method names.\& .PP The \fBid\fR field is optional and may be any valid JSON number or string.\& If provided, the response to this request will contain the identical id value, which the client may use to coordinate multiple requests and responses.\& .PP The \fBparams\fR object supplies optional parameters on a per\-method basis, and may be omitted if empty.\& .PP \fIRESPONSE\fR .PP .nf .RS 4 { "id": 123, "code": 0, "data": { \&.\&.\&. } } .fi .RE .PP If the request had an id, the response will have an identical value for \fBid\fR.\& .PP The numerical \fBcode\fR provides an indication of how the request was handled.\& A value of \fB0\fR always signifies success.\& Any other value means failure, and varies depending on the method in question.\& .PP The \fBdata\fR object contains method\-specific return data.\& This may be structured data in response to a query, a simple error string in the case of a failed request, or it may be omitted entirely if the error code alone is sufficient.\& .PP \fIEVENTS\fR .PP Events are asynchronous messages sent from a server to all registered clients.\& The message format is identical to a \fIREQUEST\fR, but without an "id" field, and a client must not send a response.\& .PP Example event message: .PP .nf .RS 4 { "method": "event\-name", "params": { "key1": "value1", "key2": "value2", } } .fi .RE .PP In order to receive any events, a client must first register to receive them by sending an \fIevent\-receive\fR request IPC.\& Once the success response has been sent by the server, the client must expect that asynchronous event messages may be sent by the server at any time, even between a request and the associated response.\& .PP .SH ENVIRONMENT .PP The following environment variables have an effect on wayvnc: .PP \fIWAYLAND_DISPLAY\fR .RS 4 Specifies the name of the Wayland display that the compositor to which wayvnc shall bind is running on.\& .PP .RE \fIXDG_CONFIG_HOME\fR .RS 4 Specifies the location of configuration files.\& .PP .RE \fIXDG_RUNTIME_DIR\fR .RS 4 Specifies the default location for the wayvncctl control socket.\& .PP .RE .SH FAQ .PP \fBWayvnc complains that a protocol is not supported\fR .PP .RS 4 The error might look like this: .nf .RS 4 wl_registry@2: error 0: invalid version for global zxdg_output_manager_v1 (4): have 2, wanted 3 ERROR: \&.\&./src/main\&.c: 388: Screencopy protocol not supported by compositor\&. Exiting\&. Refer to FAQ section in man page\&. ERROR: \&.\&./src/main\&.c: 1024: Failed to initialise wayland .fi .RE .PP This means that your Wayland compositor does not implement the screencopy protocol and wayvnc won'\&t work with it.\& Screencopy is implemented by wlroots\-based compositors such as Sway and Wayfire.\& .PP .RE \fBHow can I run wayvnc in headless mode/over an SSH session?\&\fR .PP .RS 4 Set the environment variables \fIWLR_BACKENDS\fR=headless and \fIWLR_LIBINPUT_NO_DEVICES\fR=1 before starting the compositor, then run wayvnc as normal.\& .PP .RE \fBHow can I pass my mod\-key from Sway to the remote desktop session?\&\fR .PP .RS 4 Create an almost empty mode in your sway config.\& Example: .nf .RS 4 mode passthrough { bindsym $mod+Pause mode default } bindsym $mod+Pause mode passthrough .fi .RE This makes it so that when you press $mod+Pause, all keybindings, except the one to switch back, are disabled.\& .PP .RE \fBNot all symbols show up when I'\&m typing.\& What can I do to fix this?\&\fR .PP .RS 4 Try setting the keyboard layout in wayvnc to the one that most closely matches the keyboard layout that you'\&re using on the client side.\& An exact layout isn'\&t needed, just one that has all the symbols that you use.\& .PP .RE \fBHow do I enable the Compose key?\&\fR .PP .RS 4 Set "xkb_options=compose:menu" in the config file.\& Any key that is not otherwise used will work.\& There just needs to be some key for wayvnc to match against.\& .PP .RE .SH AUTHORS .PP Maintained by Andri Yngvason .\& Up\-to\-date sources can be found at https://github.\&com/any1/wayvnc and bug reports or patches can be submitted to GitHub'\&s issue tracker.\& .PP .SH SEE ALSO .PP \fBwayvncctl(1)\fR