wayvnc(1)

📦
version 0.10.2 · 15 versions
, in arch rolling

wayvnc(1) — the General Commands Manual, but make it cute 💖

okay so this is wayvnc(1), straight out of the General Commands Manual, and bestie, it's lowkey a whole vibe. let's get into it 🫶

✨ NAME ✨

wayvnc — a VNC server for wlroots-based Wayland compositors. that's the whole name, and it ate. 💅

🎀 SYNOPSIS 🎀

wayvnc [options] [address...]

🌸 OPTIONS 🌸

like, there are a LOT of them, but they're all iconic in their own way:

  • -a, --desktop — capture all outputs. all of them. the whole desktop buffet. 🍓
  • -C, --config=<path> — pick which config file to use.
  • -d, --disable-input — turn off all remote input. this is the move when your compositor doesn't support the virtual mouse / keyboard protocols, so you can still run wayvnc without them.
  • -D, --detached — start detached from a compositor. then you run wayvncctl attach to attach yourself to one. very main character energy.
  • -f, --max-fps=<fps> — set the rate limit. default is 30.
  • -F, --log-filter=<file> — set a log filter.
  • -g, --gpu — turn on features that require GPU.
  • -h, --help — get help. we love a self-aware icon.
  • -k, --keyboard=<layout>[-variant] — pick the keyboard layout. append the variant too if you need it.
  • -L, --log-level — set log level. the levels are: error, warning, info, debug, trace and quiet.
  • -n, --name=<name> — set the desktop name. default: WayVNC.
  • -o, --output=<name> — select which output to capture.
  • -p, --show-performance — show performance counters. numbers!! ✨
  • -r, --render-cursor — enable overlay cursor rendering. your cursor gets its moment.
  • -R, --disable-resizing — disable automatic desktop resizing.
  • -s, --seat=<name> — select a seat by name.
  • -t, --transient-seat — create a transient seat for each client session.
  • -T, --toplevel=<identifier> — capture a toplevel.
  • -S, --socket=<path> — set the wayvnc control socket path. default: $XDG_RUNTIME_DIR/wayvncctl or /tmp/wayvncctl-$UID.
  • -v, --verbose — be more verbose. same as setting --log-level=info.
  • -V, --version — show version info.

🦋 ADDRESSES 🦋

you can give it more than one listening address — just tack them onto the argument list. multiple addresses, multiple slays.

for a regular network address, you can set a port number by appending it to the address with : as a separator. like: localhost:5901.

IPv6 addresses must be wrapped in square brackets if you're specifying a port. like: [::]:5901.

different socket types? yes bestie, you just prefix the address with the type name and a : in between. like: unix:/tmp/wayvnc.sock. the socket types are: tcp, unix, fd, ws, ws-unix and ws-fd.

with the fd type, you can pass an already bound socket for the VNC server to listen on. that file descriptor is a numeric value inherited from wayvnc's parent process. example: fd:42.

the ws family of prefixes encapsulates all communication over the given socket using WebSocket framing. example: ws:0.0.0.0.

💜 DESCRIPTION 💜

so here's the tea: 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. and the Wayland session can totally be a headless one — so yes, you can run wayvnc with no physical display attached at all. no monitor, no problem. 🧚

👑 MULTIPLE OUTPUTS 👑

if your Wayland session has multiple outputs, only one gets captured. by default that's the first one, but you can specify it with the -o command line argument. the argument accepts the short name, such as eDP-1 or DP-4. running wayvnc in verbose mode (-v) will display the names of all outputs on startup, or you can query them at runtime via the wayvncctl output-list command.

you can also change which output is being captured on the fly via the wayvncctl output-set command. live switches, we love to see it. 🔥

🌈 CONFIGURATION 🌈

wayvnc searches for a config file in this location:

~/$XDG_CONFIG_HOME/wayvnc/config

or, if $XDG_CONFIG_HOME is not set:

~/.config/wayvnc/config

⭐ SYNTAX ⭐

the config file is made of key-value pairs separated with an equal sign. whitespace around either the key or the value is insignificant and is not considered part of the key or the value. so go ahead and space it out, it's fine. 💅

🍓 KEYWORDS 🍓

  • address — the address to which the server shall bind, e.g. 0.0.0.0 or localhost.
  • certificate_file — the path to the certificate file for encryption. only applicable when enable_auth=true.
  • enable_auth — enable authentication and encryption. setting this value to true requires also setting certificate_file, private_key_file and password. the username is optional and defaults to an empty string if not set.
  • enable_pam — use PAM for authentication. when enabled, PAM overrides username and password settings. some authentication methods such as DES do not work with PAM. ⚠️
  • password — choose a password for authentication. required when enable_auth is set and enable_pam is not used.
  • port — the port to which the server shall bind. default is 5900.
  • private_key_file — the path to the private key file for TLS encryption. only applicable when enable_auth=true.
  • relax_encryption — don't require encryption after the user has been authenticated. this enables some security types such as Apple Diffie-Hellman.
  • rsa_private_key_file — the path to the private key file for RSA-AES encryption. only applicable when enable_auth=true.
  • username — choose a username for authentication. if not set, defaults to an empty username.
  • allow_broken_crypto — 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 password field. use only for legacy client compatibility on a trusted network.
ok genuine warning here bestie: allow_broken_crypto is literally called broken. insecure cryptographic methods, DES authentication — only for legacy client compatibility on a trusted network. don't be out here enabling it on the open internet. 😭
  • use_relative_paths — make file paths relative to the location of the config file.
  • xkb_layout — the keyboard layout to use for key code lookup.
    • default: XKB_DEFAULT_LAYOUT or system default.
  • xkb_model — the keyboard model by which to interpret keycodes and LEDs.
    • default: "pc105"
  • xkb_options — a comma-separated list of options, through which the user specifies non-layout related preferences such as which key is the Compose key.
    • default: XKB_DEFAULT_OPTIONS or system default.
  • xkb_rules — the rules file describes how to interpret the values of the model, layout, variant and options fields.
    • default: XKB_DEFAULT_RULES or system default.
  • xkb_variant — the keyboard variant to use for keycode lookup.
    • default: XKB_DEFAULT_VARIANT or system default.

🧚 EXAMPLE 🧚

here's a whole config that's giving "i know what i'm doing":

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

💅 WAYVNCCTL CONTROL SOCKET 💅

okay so this is the good part, bestie. so wayvnc doesn't just sit there being a screen — it opens a unix domain socket at $XDG_RUNTIME_DIR/wayvncctl (or, if that's not happening, it falls back to /tmp/wayvncctl-$UID) 🫶. a client can connect to that socket and they just... exchange JSON-formatted IPC messages to query and control the running wayvnc instance. runtime interaction. control. iconic behaviour, no cap.

🔌 IPC COMMANDS 🔌

HELP

the help command, when you issue it with zero parameters, literally just lists the names of all available commands. that's it. that's the whole vibe check.

if you pass the optional command parameter referring to one of those commands by name, the response data will be a detailed description of that command and its parameters ✨.

EVENT-RECEIVE

the event-receive command registers you for asynchronous server events. peek the EVENTS section below for the deets on the event message format, and the IPC EVENTS section below for a description of all possible server events 👑

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. no carrying over. tragic but true 😭

CLIENT-LIST

the client-list command retrieves a list of all VNC clients currently connected to wayvnc.

CLIENT-DISCONNECT

the client-disconnect command disconnects a single VNC client. bye bestie 💅

parameters:

  • id — Required: the ID of the client to disconnect. this ID can be found from the GET-CLIENTS command or receipt of a CLIENT-CONNECTED event.

SET-DESKTOP-NAME

the set-desktop-name command changes the desktop name sent to new clients, and updates the name for connected clients that support updating the desktop name. glow-up for everyone 💖

parameters:

  • desktop-name — Required: the desktop name.

OUTPUT-LIST

the output-list command retrieves a list of all outputs known to wayvnc, plus whether or not each one is currently being captured. yes queen, we're checking which screens are getting the attention 👀

OUTPUT-CYCLE

for multi-output Wayland displays, the output-cycle command switches which output is actively captured by wayvnc. run this once and it switches to the next available output. if no more outputs are available, it cycles back to the first one again 🔁. full circle. main character energy.

OUTPUT-SET

for multi-output Wayland displays, the output-set command switches which output is actively captured by wayvnc by name.

  • output-name=name — Required: the name of the output to capture next.

VERSION

the version command queries the running wayvnc instance for its version information. much like the -V option, the response data will contain the version numbers of wayvnc, as well as the versions of the neatvnc and aml components 🎀. everyone gets their moment.

WAYVNC-EXIT

the wayvnc-exit command disconnects all clients and shuts down wayvnc. it's giving final boss exit. no survivors 💀

📡 IPC EVENTS 📡

CAPTURE_CHANGED

the capture-changed event is sent when the currently captured output changes.

parameters:

  • output=... — the name of the output now being captured.

CLIENT-CONNECTED

the client-connected event is sent when a new VNC client connects to wayvnc. new friend acquired 🦋

parameters:

  • id=... — a unique identifier for this client.
  • connection_count=... — the total number of connected VNC clients including this one.
  • address=... — the IP address of this client. may be null.
  • username=... — the username used to authenticate this client. may be null.

CLIENT-DISCONNECTED

the client-disconnected event is sent when a VNC client disconnects from wayvnc 😭

parameters:

  • id=... — a unique identifier for this client.
  • connection_count=... — the total number of connected VNC clients not including this one.
  • address=... — the IP address of this client. may be null.
  • username=... — the username used to authenticate this client. may be null.

📨 IPC MESSAGE FORMAT 📨

the wayvncctl(1) 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. teamwork, but make it JSON 💜

Note: this message format is unstable and may change substantially over the next few releases. forewarned is forearmed, bestie ⚠️

REQUEST

the general form of a json-ipc request message is:

{
     "method": "command-name",
     "id": 123,
     "params": {
          "key1": "value1",
          "key2": "value2",
     }
}

the method is the name of the command to be executed. use the help method to query a list of all valid method names 🧚

the id 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. matching bracelets but for messages 🎀

the params object supplies optional parameters on a per-method basis, and may be omitted if empty.

RESPONSE

{
     "id": 123,
     "code": 0,
     "data": {
          ...
     }
}

if the request had an id, the response will have an identical value for id. consistency slay ✨

the numerical code provides an indication of how the request was handled. a value of 0 always signifies success. any other value means failure, and varies depending on the method in question 🚨

the data 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.

EVENTS

events are asynchronous messages sent from a server to all registered clients. the message format is identical to a REQUEST, but without an "id" field, and a client must not send a response. iykyk, don't text back 🙈

example event message:

{
     "method": "event-name",
     "params": {
          "key1": "value1",
          "key2": "value2",
     }
}

in order to receive any events, a client must first register to receive them by sending an event-receive 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 👀. so stay alert bestie.

🌈 ENVIRONMENT 🌈

the following environment variables have an effect on wayvnc:

  • WAYLAND_DISPLAY — specifies the name of the Wayland display that the compositor to which wayvnc shall bind is running on.
  • XDG_CONFIG_HOME — specifies the location of configuration files.
  • XDG_RUNTIME_DIR — specifies the default location for the wayvncctl control socket.

🌸 FAQ 🌸

"Wayvnc complains that a protocol is not supported"

the error might look like this:

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

this means that your Wayland compositor does not implement the screencopy protocol, and wayvnc won't work with it. periodt. screencopy is implemented by wlroots-based compositors such as Sway and Wayfire 🫶

"How can I run wayvnc in headless mode/over an SSH session?"

set the environment variables WLR_BACKENDS=headless and WLR_LIBINPUT_NO_DEVICES=1 before starting the compositor, then run wayvnc as normal ✨

"How can I pass my mod-key from Sway to the remote desktop session?"

create an almost empty mode in your sway config. example:

mode passthrough {
     bindsym $mod+Pause mode default
}
bindsym $mod+Pause mode passthrough

this makes it so that when you press $mod+Pause, all keybindings — except the one to switch back — are disabled. sneaky little escape hatch 👑

"Not all symbols show up when I'm typing. What can I do to fix this?"

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 💅

"How do I enable the Compose key?"

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 🎀

👑 AUTHORS 👑

maintained by Andri Yngvason <andri@yngvason.is>. 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 🫶

⭐ SEE ALSO ⭐

and that's the whole page, bestie — wayvnc(1), the 2026-10-01 edition, brought to you straight from the source. go forth and control your desktop from the group chat 💖✨🎀

📦 where this page comes from