Skip to main content
Version: v3

Migration from V2

Currently, Neko is in compatibility mode, meaning that as soon as a single V2 configuration option is set, the legacy mode is enabled. This approach allows for a smooth transition from V2 to V3, where it does not expose the V2 API for new users but still allows existing users who use the old configuration to continue using it as before.

The legacy mode can be explicitly enabled or disabled by setting the NEKO_LEGACY environment variable to true or false.

warning

The legacy mode is sill used by the client. Feel free to migrate to the new configuration options, but do not disable the legacy mode unless you are using a new client that is compatible with V3 (e.g. demodesk/neko-client). When the new client will be released, the legacy mode will be automatically removed from the server.

If you set both V3 and V2 configuration options, the V2 configuration options will take precedence over the V3 configuration options. This is to ensure that the legacy mode works as expected and does not break existing configurations.

Docker Images​

Previously, neko was available primarily on Dockerhub as m1k1o/neko. While it stays as an option there, now the primary location is ghcr.io/m1k1o/neko.

ARM images were previously available as an flavor e.g. m1k1o/neko:arm-firefox or ghcr.io/m1k1o/neko/arm-firefox. Now, the ARM images are available as multi-arch images under the same tags as the amd64 images., e.g. ghcr.io/m1k1o/neko/firefox.

All applications available in the V2 images are also available in the V3 images. See the Docker Images documentation for more details.

Configuration​

V3 is compatible with V2 configuration options when legacy support is enabled. You should be able to run V3 with the V2 configuration without any issues.

The configuration in Neko V3 has been structured differently compared to V2. The V3 configuration is more modular and allows for more flexibility. The V3 configuration is split into multiple sections, each section is responsible for a specific part of the application. This allows for better organization and easier management of the configuration.

In order to migrate from V2 to V3, you need to update the configuration to the new format. The following table shows the mapping between the V2 and V3 configuration options.

V2 ConfigurationV3 Configuration
NEKO_LOGS=trueNEKO_LOG_DIR=/var/log/neko, V3 allows specifying the log directory
NEKO_CERTNEKO_SERVER_CERT
NEKO_KEYNEKO_SERVER_KEY
NEKO_BINDNEKO_SERVER_BIND
NEKO_PROXYNEKO_SERVER_PROXY
NEKO_STATICNEKO_SERVER_STATIC
NEKO_PATH_PREFIXNEKO_SERVER_PATH_PREFIX
NEKO_CORSNEKO_SERVER_CORS
NEKO_LOCKSNEKO_SESSION_LOCKED_CONTROLS and NEKO_SESSION_LOCKED_LOGINS,
V3 allows separate locks for controls and logins
NEKO_IMPLICIT_CONTROLNEKO_SESSION_IMPLICIT_HOSTING
NEKO_CONTROL_PROTECTIONNEKO_SESSION_CONTROL_PROTECTION
NEKO_HEARTBEAT_INTERVALNEKO_SESSION_HEARTBEAT_INTERVAL
NEKO_FILE_TRANSFER_ENABLEDNEKO_FILETRANSFER_ENABLED
NEKO_FILE_TRANSFER_PATHNEKO_FILETRANSFER_DIR

See the V3 configuration options. For file transfer, see the File Transfer Plugin.

WebRTC Video​

See the V3 configuration options for the WebRTC Video.

V2 ConfigurationV3 Configuration
NEKO_DISPLAYNEKO_CAPTURE_VIDEO_DISPLAY and NEKO_DESKTOP_DISPLAY,
consider using DISPLAY env variable if both should be the same
NEKO_VIDEO_CODECNEKO_CAPTURE_VIDEO_CODEC
NEKO_AV1=true deprecatedNEKO_CAPTURE_VIDEO_CODEC=av1
NEKO_H264=true deprecatedNEKO_CAPTURE_VIDEO_CODEC=h264
NEKO_VP8=true deprecatedNEKO_CAPTURE_VIDEO_CODEC=vp8
NEKO_VP9=true deprecatedNEKO_CAPTURE_VIDEO_CODEC=vp9
NEKO_VIDEONEKO_CAPTURE_VIDEO_PIPELINE, V3 allows multiple video pipelines
NEKO_VIDEO_BITRATEremoved, use custom pipeline instead
NEKO_HWENCremoved, use custom pipeline instead
NEKO_MAX_FPSremoved, use custom pipeline instead
Limitation

V2 did not have client-side cursor support, the cursor was always part of the video stream. In V3, the cursor is sent separately from the video stream. Therefore, when using legacy configuration, there will be two video streams created, one with the cursor (for V2 clients) and one without the cursor (for V3 clients). Please consider using new configuration options if this is not the desired behavior.

WebRTC Audio​

See the V3 configuration options for the WebRTC Audio.

V2 ConfigurationV3 Configuration
NEKO_DEVICENEKO_CAPTURE_AUDIO_DEVICE
NEKO_AUDIO_CODECNEKO_CAPTURE_AUDIO_CODEC
NEKO_G722=true deprecatedNEKO_CAPTURE_AUDIO_CODEC=g722
NEKO_OPUS=true deprecatedNEKO_CAPTURE_AUDIO_CODEC=opus
NEKO_PCMA=true deprecatedNEKO_CAPTURE_AUDIO_CODEC=pcma
NEKO_PCMU=true deprecatedNEKO_CAPTURE_AUDIO_CODEC=pcmu
NEKO_AUDIONEKO_CAPTURE_AUDIO_PIPELINE
NEKO_AUDIO_BITRATEremoved, use custom pipeline instead

Broadcast​

See the V3 configuration options for the Broadcast.

V2 ConfigurationV3 Configuration
NEKO_BROADCAST_PIPELINENEKO_CAPTURE_BROADCAST_PIPELINE
NEKO_BROADCAST_URLNEKO_CAPTURE_BROADCAST_URL
NEKO_BROADCAST_AUTOSTARTNEKO_CAPTURE_BROADCAST_AUTOSTART

Desktop​

See the V3 configuration options for the Desktop.

V2 ConfigurationV3 Configuration
NEKO_SCREENNEKO_DESKTOP_SCREEN

Authentication​

See the V3 configuration options for the Authentication.

V2 ConfigurationV3 Configuration
NEKO_PASSWORDNEKO_MEMBER_MULTIUSER_USER_PASSWORD with NEKO_MEMBER_PROVIDER=multiuser
NEKO_PASSWORD_ADMINNEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD with NEKO_MEMBER_PROVIDER=multiuser

In order for the legacy authentication to work, you need to set Multi-user.

Limitation

V2 clients might not be compatible with any other authentication provider than the multiuser.

WebRTC​

See the V3 configuration options for the WebRTC.

V2 ConfigurationV3 Configuration
NEKO_NAT1TO1NEKO_WEBRTC_NAT1TO1
NEKO_TCPMUXNEKO_WEBRTC_TCPMUX
NEKO_UDPMUXNEKO_WEBRTC_UDPMUX
NEKO_ICELITENEKO_WEBRTC_ICELITE
NEKO_ICESERVERS or NEKO_ICESERVERNEKO_WEBRTC_ICESERVERS_FRONTEND and NEKO_WEBRTC_ICESERVERS_BACKEND,
V3 allows separate ICE servers for frontend and backend
NEKO_IPFETCHNEKO_WEBRTC_IP_RETRIEVAL_URL
NEKO_EPRNEKO_WEBRTC_EPR

Full V2 Configuration Reference​

Here is a full list of all the configuration options available in Neko V2 that are still available in Neko V3 with legacy support enabled.

You can set the following environment variables in your docker-compose.yaml file or in your shell environment.

# enable legacy mode
NEKO_LEGACY: "true"
# save logs to file
NEKO_LOGS: "false"
# XDisplay to capture
NEKO_DISPLAY: <string>
# video codec to be used
NEKO_VIDEO_CODEC: <string>
# DEPRECATED: use video_codec
NEKO_AV1: "false"
# DEPRECATED: use video_codec
NEKO_H264: "false"
# DEPRECATED: use video_codec
NEKO_VP8: "false"
# DEPRECATED: use video_codec
NEKO_VP9: "false"
# video codec parameters to use for streaming
NEKO_VIDEO: <string>
# video bitrate in kbit/s
NEKO_VIDEO_BITRATE: <int>
# use hardware accelerated encoding
NEKO_HWENC: <string>
# maximum fps delivered via WebRTC, 0 is for no maximum
NEKO_MAX_FPS: <int>
# audio device to capture
NEKO_DEVICE: <string>
# audio codec to be used
NEKO_AUDIO_CODEC: <string>
# DEPRECATED: use audio_codec
NEKO_G722: "false"
# DEPRECATED: use audio_codec
NEKO_OPUS: "false"
# DEPRECATED: use audio_codec
NEKO_PCMA: "false"
# DEPRECATED: use audio_codec
NEKO_PCMU: "false"
# audio codec parameters to use for streaming
NEKO_AUDIO: <string>
# audio bitrate in kbit/s
NEKO_AUDIO_BITRATE: <int>
# custom gst pipeline used for broadcasting, strings {url} {device} {display} will be replaced
NEKO_BROADCAST_PIPELINE: <string>
# a default default URL for broadcast streams, can be disabled/changed later by admins in the GUI
NEKO_BROADCAST_URL: <string>
# automatically start broadcasting when neko starts and broadcast_url is set
NEKO_BROADCAST_AUTOSTART: "false"
# default screen resolution and framerate
NEKO_SCREEN: <string>
# password for connecting to stream
NEKO_PASSWORD: <string>
# admin password for connecting to stream
NEKO_PASSWORD_ADMIN: <string>
# path to the SSL cert used to secure the neko server
NEKO_CERT: <string>
# path to the SSL key used to secure the neko server
NEKO_KEY: <string>
# address/port/socket to serve neko
NEKO_BIND: <string>
# enable reverse proxy mode
NEKO_PROXY: "false"
# path to neko client files to serve
NEKO_STATIC: <string>
# path prefix for HTTP requests
NEKO_PATH_PREFIX: <string>
# list of allowed origins for CORS
NEKO_CORS: <strings>
# resources, that will be locked when starting (control, login)
NEKO_LOCKS: <strings>
# if enabled members can gain control implicitly
NEKO_IMPLICIT_CONTROL: "false"
# control protection means, users can gain control only if at least one admin is in the room
NEKO_CONTROL_PROTECTION: "false"
# heartbeat interval in seconds
NEKO_HEARTBEAT_INTERVAL: "120"
# sets a list of external IP addresses of 1:1 (D)NAT and a candidate type for which the external IP 
NEKO_NAT1TO1: <strings>
# single TCP mux port for all peers
NEKO_TCPMUX: <int>
# single UDP mux port for all peers
NEKO_UDPMUX: <int>
# configures whether or not the ice agent should be a lite agent
NEKO_ICELITE: "false"
# describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection 
NEKO_ICESERVER: <strings>
# describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection 
NEKO_ICESERVERS: <string>
# automatically fetch IP address from given URL when nat1to1 is not present
NEKO_IPFETCH: <string>
# limits the pool of ephemeral ports that ICE UDP connections can allocate from
NEKO_EPR: <string>

See the full V3 configuration reference for more details.

API​

V3 is compatible with the V2 API when legacy support is enabled. There was specifically created a compatibility layer (legacy API) that allows V2 clients to connect to V3. The legacy API is enabled by default, but it can be disabled if needed. In later versions, the legacy API will be removed.

Authentication​

In V2 there was only one authentication provider available, as in V3 called the multiuser provider. The API knew based on the provided password (as ?pwd= query string) if the user is an admin or not.

Since V3 handles authentication differently (see API documentation), there has been added ?usr= query string to the API to specify the username. The password is still provided as ?pwd= query string. The ?usr= query string is still optional, if not provided, the API will generate a random username.

Limitation

For every request in the legacy API, a new user session is created based on the ?usr=&pwd= query string. The session is destroyed after the API request is completed. So for HTTP API requests, the sessions are short-lived but for WebSocket API requests, the session is kept alive until the WebSocket connection is closed.

Only the multiuser provider (or the noauth provider) is supported without specifying the ?usr= query string.

WebSocket Messages​

Since WebSocket messages are not user-facing API, there exists no migration guide for them. When the legacy API is enabled, the user connects to the /ws endpoint and is handled by the compatibility layer V2 API. The V3 API is available at the /api/ws endpoint.

WebRTC API​

Since the WebRTC API is not user-facing API, there exists no migration guide for it. It has been changed to Big Endian format (previously Little Endian) to allow easier manipulation on the client side. V2 created a new data channel on the client side, V3 creates a new data channel on the server side. That means, the server just listens for a new data channel from the client and accepts it with the legacy API handler. It overwrites the existing V3 data channel with the legacy one.

HTTP API​

The V2 version had a very limited HTTP API, the V3 API is much more powerful and flexible. See the API documentation for more details.

GET /health​

Migrated to the Health endpoint for server health checks.

Returns 200 OK if the server is running.

GET /stats​

Migrated to the Stats endpoint for server statistics and the List Sessions endpoint for the session list.

Returns a JSON object with the following structure:

{
  // How many connections are currently active
  "connections": 0,
  // Who is currently having a session (empty if no one)
  "host": "<session_id>",
  // List of currently connected users
  "members": [
    {
      "session_id": "<session_id>",
      "displayname": "Name",
      "admin": true,
      "muted": false,
    }
  ],
  // List of banned IPs and who banned them as a session_id
  "banned": {
    "<ip>": "<session_id>"
  },
  // List of locked resources and who locked them as a session_id
  "locked": {
    "<resource>": "<session_id>"
  },
  // Server uptime
  "server_started_at": "2021-01-01T00:00:00Z",
  // When was the last admin or user left the session
  "last_admin_left_at": "2021-01-01T00:00:00Z",
  "last_user_left_at": "2021-01-01T00:00:00Z",
  // Whether the control protection or implicit control is enabled
  "control_protection": false,
  "implicit_control": false,
}

GET /screenshot.jpg​

Migrated to the Screenshot endpoint for taking screenshots.

Returns a screenshot of the desktop as a JPEG image.

GET /file​

The whole functionality of file transfer has been moved to a File Transfer Plugin.

Limitations​

In v2, locks and muted users were managed using a simple map that tracked who set the lock and what was locked. In v3, locks are now implemented as setting options and no longer store the session_id of the user who applied the lock. As a result, if a client refreshes the page or reconnects, the lock information is lost, and the user who set the lock is displayed as Somebody.

Additionally, when using the legacy API with a v2 client, API calls occur in a different order than expected. The client first retrieves the session list before registering the user, meaning the current session_id is not known when the session list is fetched. That means, the current user appears as Somebody in the session list.

Currently, the v3 has no native support for pipeline generation, meaning that the user has to manually specify the pipeline for video and audio if he wants to customize it. The v2 had a simple built-in support for setting the video bitrate, fps, audio bitrate, and hardware encoding. Since the introduction of multiple video pipelines in v3, this feature has been removed.