Skip to main content


The Hivekit-Server is configured via a YAML file packaged together with the executable. By default, the server looks for a file called conf.yml in the same directory as the executable, but you can also point it to other config files using the -c flag, e.g.

./hivekit-server -c ../config/myotherconfig.yml

Any changes to the configuration file require a restart of the server. The configuration file contains the following options:

# Network Settings for HTTP & Websocket
httpPath: /api/v1/ # The path for HTTP clients to send messages to
websocketPath: /ws # The path for websocket clients to connect to

httpHost: # Host for HTTP and Websocket Connections
httpPort: 8090 # Port for HTTP and Websocket Connections

# The Hivekit server can handle cross origin resource sharing for
# requests between domains. If enableCors is set to true, the server
# will respond to preflight OPTIONS request and return the appropriate
# access-control-allow-origin, access-control-allow-methods, access-control-allow-headers
# and access-control-allow-credentials headers
enableCors: true

# This path is meant to be pinged by reverse proxies via HTTP GET, load balancers and monitoring tools.
# It returns a 200 response as well as a JSON map with current utilization stats for the server
healthCheckPath: /health-check

# Network Settings for TCP.
# Hivekit supports raw TCP access for fast, low level communication.
# This port must be different from the HTTP/WS port
tcpEndabled: true
tcpPort: 8091

# Settings for admin dashboard
# Hivekit comes with a build in admin dashboard that can be reached by default at
# localhost:8090/admin/
adminDashboardEnabled: true # disable for production servers!
adminDashboardHttpPath: admin # available at /admin/
adminPassword: CHANGE_ME # only set this for development purposes

# Performance
# These settings can be used to tweak the performance of the Hivekit Server.

# Message backlog that is filling up while writing to the socket. Increase for
# low latency environments. Must be a power of 2 (64, 128, 256, 512, 1024 etc...)
outgoingMessageBufferSize: 128

# This provides batching for messages, sent out by sentToUrl and similar functions
# that emit data from instructions
outgoingMessageBufferInterval: 500ms

# For fast changing objects, subscriptions are throttled to this duration. Having a lower
# duration means subscription updates are sent out sooner after the change, but at higher frequency
subscriptionBatchInterval: 100ms

# Most instructions are run in response to events. But some, e.g. those that need to check for the
# absence of an event are run on an interval. Instructions that run on an interval start with
# EVERY <duration>, e.g. EVERY 15s
# this duration specifies how often these instructions should be evaluated
minCheckInterval: 30s

# The number of changes after which the server will create a snapshot of the realm and save it to memory.
# This is a costly operation, so decide which level of persistence (if any!) you need.
# -1 = disable persistance
# 1 = save every change
# the higher the number, the fewer times the server will save its state and the faster it runs.
# however, if the number is too high and the server stops it will loose the changes since the last change.
saveFrequency: 80000

# The original implementation of presence ran on an interval. Every x duration it
# checked which endpoints where still connected and which HTTP updates where still
# fresh enough to count as "connected". Future generations will do this based on events
presenceRefreshRate: 100ms

# Logging
logLevel: debug #Supported values are trace, debug, info, warning, error and fatal

# Authentication
authType: jwt # Currently only JWT is supported
authCookieName: cookieKey #Name of the cookie to look for the auth token in. Use gtoken for Google Identity Platform or cognito for AWS cognito

# Hivekit uses the issuer claim (iss) in the token's header to determine how to validate the token.
# If the issuer is, the token will be validated against keys from Google Identity Platform
# If the issuer is either or unknown, the token will be validated against the secret configured here
authTokenSecret: CHANGE_ME

# If the token is to be validated against Google Identity Platform, point
# to the required service account json here
pathToGoogleServiceAccountJson: yourproject-com-firebase-adminsdk-abcde-fghij3423.json

# Hivekit supports Multi Tenancy. Which tenant or organisation a user belongs to is determined
# by the org id passed in a claim with this key:
tenantIdClaimKey: tenantId

# Persistence
persistenceType: none # currently none and postgres are supported
persistenceMessageBufferSize: 2 # DEPRECATED

# Settings for persistence type Postgres
pgHost: 12.345.678.122
pgPort: 5432
pgUser: postgres
pgPassword: CHANGE_ME
pgDatabase: hivekit

# When saving and restoring its state, the server will only restore data for this environment key
environment: dev