neko/webpage/docs/getting-started/configuration

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

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

```yaml title="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 ]
```

```json title="config.json"
{
  "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": [
        {
          "urls": [ "stun:stun.l.google.com:19302" ]
        }
      ],
      "frontend": [
        {
          "urls": [ "stun:stun.l.google.com:19305" ]
        }
      ]
    }
  }
}
```

```toml title="config.toml"
[capture.screencast]
enabled = false

[server]
pprof = true

[desktop]
screen = "1920x1080@60"

[member]
provider = "multiuser"

[member.multiuser]
admin_password = "admin"
user_password = "neko"

[session]
merciful_reconnect = true
implicit_hosting = false
inactive_cursors = true

[session.cookie]
enabled = false

[webrtc]
icelite = true

[[webrtc.iceservers.backend]]
urls = [ "stun:stun.l.google.com:19302" ]

[[webrtc.iceservers.frontend]]
urls = [ "stun:stun.l.google.com:19305" ]
```

```hcl title="config.hcl"
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 {
      urls = [ "stun:stun.l.google.com:19302" ]
    }

    frontend {
      urls = [ "stun:stun.l.google.com:19305" ]
    }
  }
}
```

```env title=".env"
CAPTURE_SCREENCAST_ENABLED=false

SERVER_PPROF=true

DESKTOP_SCREEN=1920x1080@60

MEMBER_PROVIDER=multiuser
MEMBER_MULTIUSER_ADMIN_PASSWORD=admin
MEMBER_MULTIUSER_USER_PASSWORD=neko

SESSION_MERCIFUL_RECONNECT=true
SESSION_IMPLICIT_HOSTING=false
SESSION_INACTIVE_CURSORS=true
SESSION_COOKIE_ENABLED=false

WEBRTC_ICELITE=true

WEBRTC_ICESERVERS_BACKEND="[{"urls":["stun:stun.l.google.com:19302"]}]"
WEBRTC_ICESERVERS_FRONTEND="[{"urls":["stun:stun.l.google.com:19305"]}]"
```

```properties title="config.properties"
capture.screencast.enabled = false

server.pprof = true

desktop.screen = 1920x1080@60

member.provider = multiuser
member.multiuser.admin_password = admin
member.multiuser.user_password = neko

session.merciful_reconnect = true
session.implicit_hosting = false
session.inactive_cursors = true
session.cookie.enabled = false

webrtc.icelite = true

webrtc.iceservers.backend[0].urls[0] = stun:stun.l.google.com:19302
webrtc.iceservers.frontend[0].urls[0] = 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 allows switching control implicitly without the need for explicit control request before
• 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: "/path/to/cert.pem"
  key: "/path/to/key.pem"
  cors: [ "*" ]
  metrics: true
  path_prefix: "/neko"
  pprof: true
  proxy: true
  static: "/var/www/neko"

• 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.
• 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: true
  level: "info"
  nocolor: true
  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.

import Configuration from './help.tsx'

Next Steps

import DocCardList from '@theme/DocCardList';