Skip to main content
Version: v3

Configuration

Neko uses the Viper library to manage configuration. The configuration file is optional and is not required for Neko to run. If a configuration file is present, it will be read in and merged with the default configuration values.

The merge order is as follows:

  • Default configuration values
  • Configuration file
  • Environment variables
  • Command-line arguments
Example merging order
# Default Value: 127.0.0.1:8080

# Config File
cat config.yaml <<EOF
server:
  bind: "127.0.0.1:8081"
EOF

# Environment Variable
export NEKO_SERVER_BIND=127.0.0.1:8082

# Command-line Argument
./neko -config=config.yaml -server.bind=127.0.0.1:8083

The final value of server.bind will be 127.0.0.1:8083.

Configuration File​

You have multiple ways to specify the configuration file for the neko server:

  • Command-line argument: -config=/path/to/config.yaml
  • Environment variable: NEKO_CONFIG=/path/to/config.yaml
  • Place the neko.yaml file in the same directory as the neko binary.
  • Place the neko.yaml file to /etc/neko/neko.yaml (ideal for Docker containers).

The configuration file can be specified in YAML, JSON, TOML, HCL, envfile, and Java properties format. Throughout the documentation, we will use the YAML format.

Example configuration files
config.yaml
capture:
  screencast:
    enabled: false

server:
  pprof: true

desktop:
  screen: "1920x1080@60"

member:
  provider: "multiuser"
  multiuser:
  admin_password: "admin"
  user_password: "neko"

session:
  merciful_reconnect: true
  implicit_hosting: false
  inactive_cursors: true
  cookie:
    enabled: false

webrtc:
  icelite: true
  iceservers:
    # Backend servers are ignored if icelite is true.
    backend:
      - urls: [ stun:stun.l.google.com:19302 ]
    frontend:
      - urls: [ stun:stun.l.google.com:19305 ]

Room Configuration​

This is the initial configuration of the room that can be modified by an admin in real-time.

session:
  private_mode: false
  locked_logins: false
  locked_controls: false
  control_protection: false
  implicit_hosting: true
  inactive_cursors: false
  merciful_reconnect: true
  heartbeat_interval: 120
  • private_mode whether private mode is enabled, users do not receive the room video or audio.
  • locked_logins whether logins are locked for users, admins can still login.
  • locked_controls whether controls are locked for users, admins can still control.
  • control_protection users can gain control only if at least one admin is in the room.
  • implicit_hosting automatically grants control to a user when they click on the screen, unless an admin has locked the controls.
  • inactive_cursors whether to show inactive cursors server-wide (only for users that have it enabled in their profile).
  • merciful_reconnect whether to allow reconnecting to the websocket even if the previous connection was not closed. This means that a new login can kick out the previous one.
  • heartbeat_interval interval in seconds for sending a heartbeat message to the server. This is used to keep the connection alive and to detect when the connection is lost.

Server Configuration​

This is the configuration of the neko server.

server:
  bind: "127.0.0.1:8080"
  cert: <string>
  key: <string>
  cors: [ <string> ]
  metrics: true
  path_prefix: "/"
  pprof: false
  proxy: false
  static: <string>
  • bind address/port/socket to serve neko. For docker you might want to bind to 0.0.0.0 to allow connections from outside the container.
  • cert and key paths to the SSL cert and key used to secure the neko server. If both are empty, the server will run in plain HTTP.
  • cors is a list of allowed origins for CORS.
    • If empty, CORS is disabled, and only same-origin requests are allowed.
    • If * is present, all origins are allowed. Neko will respond always with the requested origin, not with * since credentials are not allowed with wildcard.
    • If a list of origins is present, only those origins are allowed for CORS.
  • metrics when true, prometheus metrics are available at /metrics.
  • path_prefix is the prefix for all HTTP requests. This is useful when running neko behind a reverse proxy and you want to serve neko under a subpath, e.g. /neko.
  • pprof when true, the pprof endpoint is available at /debug/pprof for debugging and profiling. This should be disabled in production.
  • proxy when true, neko will trust the X-Forwarded-For and X-Real-IP headers from the reverse proxy. Make sure your reverse proxy is configured to set these headers and never trust them when not behind a reverse proxy. See Reverse Proxy Setup for more information.
  • static path to the directory containing the neko client files to serve. This is useful if you want to serve the client files on the same domain as the server.

Logging Configuration​

This is the configuration of the logging system.

log:
  dir: <string>
  json: false
  level: "info"
  nocolor: false
  time: "unix"
  • dir directory to store logs. If empty, logs are written to stdout. This is useful when running neko in a container.
  • json when true, logs are written in JSON format.
  • level log level to set. Available levels are trace, debug, info, warn, error, fatal, panic, and disabled.
  • nocolor when true, ANSI colors are disabled in non-JSON output. Accepts as well NO_COLOR environment variable.
  • time time format used in logs. Available formats are unix, unixms, and unixmicro.
tip

Shortcut environment variable to enable DEBUG mode: NEKO_DEBUG=true

Full Configuration Reference​

Here is a full configuration with default values as shown in the help command. Please refer to the sub-sections for more details.

You can create a /etc/neko/neko.yaml file with the following configuration options.

capture:
  audio:
    # audio codec to be used (string)
    codec: "opus"
    # pulseaudio device to capture (string)
    device: "audio_output.monitor"
    # gstreamer pipeline used for audio streaming (string)
    pipeline: <string>
  broadcast:
    # broadcast audio bitrate in KB/s (int)
    audio_bitrate: 128
    # automatically start broadcasting when neko starts and broadcast_url is set (boolean)
    autostart: true
    # gstreamer pipeline used for broadcasting (string)
    pipeline: <string>
    # broadcast speed preset for h264 encoding (string)
    preset: "veryfast"
    # initial URL for broadcasting, setting this value will automatically start broadcasting (string)
    url: <string>
    # broadcast video bitrate in KB/s (int)
    video_bitrate: 4096
  microphone:
    # pulseaudio device used for microphone (string)
    device: "audio_input"
    # enable microphone stream (boolean)
    enabled: true
  screencast:
    # enable screencast (boolean)
    enabled: false
    # gstreamer pipeline used for screencasting (string)
    pipeline: <string>
    # screencast JPEG quality (string)
    quality: "60"
    # screencast frame rate (string)
    rate: "10/1"
  video:
    # video codec to be used (string)
    codec: "vp8"
    # X display to capture (string)
    display: <string>
    # ordered list of video ids (strings)
    ids: [ <string> ]
    # shortcut for configuring only a single gstreamer pipeline, ignored if pipelines is set (string)
    pipeline: <string>
    # pipelines config used for video streaming (object)
    pipelines: {}
  webcam:
    # v4l2sink device used for webcam (string)
    device: "/dev/video0"
    # enable webcam stream (boolean)
    enabled: false
    # webcam stream height (int)
    height: 720
    # webcam stream width (int)
    width: 1280
desktop:
  # X display to use for desktop sharing (string)
  display: <string>
  # whether to handle file chooser dialog externally (boolean)
  file_chooser_dialog: false
  input:
    # whether custom xf86 input driver should be used to handle touchscreen (boolean)
    enabled: true
    # socket path for custom xf86 input driver connection (string)
    socket: "/tmp/xf86-input-neko.sock"
  # default screen size and framerate (string)
  screen: "1280x720@30"
  # automatically unminimize window when it is minimized (boolean)
  unminimize: true
  # whether drop upload is enabled (boolean)
  upload_drop: true
member:
  file:
    # member file provider: whether the passwords are hashed using sha256 or not (recommended) (boolean)
    hash: true
    # member file provider: path to the file containing the users and their passwords (string)
    path: <string>
  multiuser:
    # member multiuser provider: password for admin users (string)
    admin_password: "admin"
    # member multiuser provider: profile template for admin users (object)
    admin_profile: {}
    # member multiuser provider: password for regular users (string)
    user_password: "neko"
    # member multiuser provider: profile template for regular users (object)
    user_profile: {}
  object:
    # member object provider: list of users with their passwords and profiles (array)
    users: []
  # selected member provider (string)
  provider: "multiuser"
plugins:
  # path to neko plugins to load (string)
  dir: "./bin/plugins"
  # load plugins in runtime (boolean)
  enabled: false
  # if true, neko will exit if there is an error when loading a plugin (boolean)
  required: false
server:
  # address/port/socket to serve neko (string)
  bind: "127.0.0.1:8080"
  # path to the SSL cert used to secure the neko server (string)
  cert: <string>
  # list of allowed origins for CORS, if empty CORS is disabled, if '*' is present all origins are allowed (strings)
  cors: [ <string> ]
  # path to the SSL key used to secure the neko server (string)
  key: <string>
  # enable prometheus metrics available at /metrics (boolean)
  metrics: true
  # path prefix for HTTP requests (string)
  path_prefix: "/"
  # enable pprof endpoint available at /debug/pprof (boolean)
  pprof: false
  # trust reverse proxy headers (boolean)
  proxy: false
  # path to neko client files to serve (string)
  static: <string>
session:
  # API token for interacting with external services (string)
  api_token: <string>
  # users can gain control only if at least one admin is in the room (boolean)
  control_protection: false
  cookie:
    # domain of the cookie (string)
    domain: <string>
    # whether cookies authentication should be enabled (boolean)
    enabled: true
    # expiration of the cookie (duration)
    expiration: "24h0m0s"
    # use http only cookies (boolean)
    http_only: true
    # name of the cookie that holds token (string)
    name: "NEKO_SESSION"
    # path of the cookie (string)
    path: <string>
    # use secure cookies (boolean)
    secure: true
  # if sessions should be stored in a file, otherwise they will be stored only in memory (string)
  file: <string>
  # interval in seconds for sending heartbeat messages (int)
  heartbeat_interval: 120
  # allow implicit control switching (boolean)
  implicit_hosting: true
  # show inactive cursors on the screen (boolean)
  inactive_cursors: false
  # whether controls should be locked for users initially (boolean)
  locked_controls: false
  # whether logins should be locked for users initially (boolean)
  locked_logins: false
  # allow reconnecting to websocket even if previous connection was not closed (boolean)
  merciful_reconnect: true
  # whether private mode should be enabled initially (boolean)
  private_mode: false
webrtc:
  # limits the pool of ephemeral ports that ICE UDP connections can allocate from (string)
  epr: <string>
  estimator:
    # enables debug logging for the bandwidth estimator (boolean)
    debug: false
    # how bigger the difference between estimated and stream bitrate must be to trigger upgrade/downgrade (float)
    diff_threshold: 0.15
    # how long to wait before downgrading again after previous downgrade (duration)
    downgrade_backoff: "10s"
    # enables the bandwidth estimator (boolean)
    enabled: false
    # initial bitrate for the bandwidth estimator (int)
    initial_bitrate: 1000000
    # passive estimator mode, when it does not switch pipelines, only estimates (boolean)
    passive: false
    # how often to read and process bandwidth estimation reports (duration)
    read_interval: "2s"
    # how long to wait for stable connection (upward or neutral trend) before upgrading (duration)
    stable_duration: "12s"
    # how long to wait for stalled bandwidth estimation before downgrading (duration)
    stalled_duration: "24s"
    # how long to wait for stalled connection (neutral trend with low bandwidth) before downgrading (duration)
    unstable_duration: "6s"
    # how long to wait before upgrading again after previous upgrade (duration)
    upgrade_backoff: "5s"
  # configures whether or not the ICE agent should be a lite agent (boolean)
  icelite: false
  iceservers:
    # STUN and TURN servers used by the backend (array)
    backend: []
    # STUN and TURN servers used by the frontend (array)
    frontend: []
  # configures whether cadidates should be sent asynchronously using Trickle ICE (boolean)
  icetrickle: true
  # URL address used for retrieval of the external IP address (string)
  ip_retrieval_url: "https://checkip.amazonaws.com"
  # sets a list of external IP addresses of 1:1 (D)NAT and a candidate type for which the external IP address is used (strings)
  nat1to1: [ <string> ]
  # single TCP mux port for all peers (int)
  tcpmux: 0
  # single UDP mux port for all peers, replaces EPR (int)
  udpmux: 0
# configuration file path (string)
config: <string>
# enable debug mode (boolean)
debug: false
log:
  # logging directory to store logs (string)
  dir: <string>
  # logs in JSON format (boolean)
  json: false
  # set log level (trace, debug, info, warn, error, fatal, panic, disabled) (string)
  level: "info"
  # no ANSI colors in non-JSON output (boolean)
  nocolor: false
  # time format used in logs (unix, unixms, unixmicro) (string)
  time: "unix"

Next Steps​