Comment on page

Sync Server Configuration

To setup ObjectBox Sync Server to your needs, there are various configuration options, which are presented on this page.
There are two approaches to configure ObjectBox Sync Server:
  • command line parameters (CLI): simple/quick approach for most settings
  • configuration file (JSON): recommended for complex settings and required for clusters
Note that both approaches can be combined.

Configuration via command line (CLI)

A good start is to have a look at the output of running sync-server --help (your output may vary, e.g. when using a newer version of the Sync Server):
$ sync-server --help
ObjectBox Sync Server
sync-server [OPTION...]
--admin-bind arg host/IP and port the admin http server should
listen on (default:
--admin-threads arg number of the worker threads used by admin
http server (default: 4)
--admin-off do not start the admin http server
--async-tx-slot arg If async DB TXs are "too fast", this adds a
delay to fill up the slot (default: 3000)
-b, --bind arg host/IP and port the sync server should
listen on (default: ws://
-c, --conf arg configuration file path (default:
--cert arg certificate file path (default: )
--cluster-id arg cluster ID to enable cluster mode for servers
(default: )
--debug enable debug logs
--fixed-follower the server never becomes the leader of the
cluster (default: false)
--fixed-leader make the server the (only!) leader of the
cluster (danger: read docs carefully!) (default:
-d, --db-directory arg directory where the database is stored
(default: objectbox)
--db-max-size arg database size limit; use a number with a unit
(K/M/G/T), e.g. 256G (default: 104857600K)
-h, --help show help
-m, --model arg schema model file to load (JSON) (default: )
[UNSECURE] allow connections without
--workers arg number of workers for the main task pool
(default is hardware dependent, e.g. 3 * CPU
"cores") (default: 0)
More details about the options can be found in the section on the configuration file. Just note that the naming convention is different (e.g. dbMaxSize instead of db-max-size), but both refer to the same underlying option.

Configuration file

Alternatively, you can choose to provide the configuration in a JSON file. This is the preferred choice if the options are getting more complex (e.g. you can checkin the configuration file into version control). Also, it's the only way to configure a cluster.
By default, the configuration file is read from sync-server-config.json in the current working directory. To use a different location, supply it via the --conf <path-to-config> option.
Some options have a default value, so if you are OK with the default, there is no need to specify it.
The available options are:
"dbDirectory": "objectbox",
"dbMaxSize": "100G",
"modelFile": "",
"bind": "ws://",
"adminBind": "",
"adminThreads": 4,
"certificatePath": "",
"auth": {
"sharedSecret": "",
"google": {
"clientIds": []
  • dbDirectory directory where the database is stored (default: "objectbox").
  • dbMaxSize database size limit; use a number with a unit, e.g. 256G (default: 100G)
    • K for kibibytes, i.e. 1024 bytes
    • M for mebibytes, i.e. 1024 kibibytes
    • G for gibibytes, i.e. 1024 mebibytes
    • T for tebibytes, i.e. 1024 gibibytes
  • modelFile schema (model) file to create the database with or to use for a schema update
  • bind Sync server will bind on this URL (schema, host and port). It should look like ws://hostname:port, for example ws:// You can also bind to a specific IP address on the server machine by providing the exact address, as given by ifconfig or ip addr, e.g. ws://
  • adminBind HTTP server (admin/web UI) will bind on this URL (schema, host and port combination).
  • adminThreads number of threads the HTTP server uses (default: 4). A low number is typically enough as it's for admins only. You may need to increase if running in some cloud setups that keep the connections active (e.g. Kubernetes).
  • certificatePath Supply a SSL certificate directory to enable SSL. This directory must contain the files cert.pem and key.pem.
  • auth.sharedSecret if not empty, enables the shared secret authentication with the given key
  • a list of GoogleAuth client IDs (strings)
  • unsecured-no-authentication: allow connections without authentication (note: this is unsecure and shall only be used to simplify test setups.
To setup a cluster, please refer to the cluster page for specific configuration options.

Combining CLI and file configuration

You can mix both approaches, i.e. have a configuration file and use command line (CLI) options. In this case, CLI options have precedence over the options in the JSON config file. Thus, you can store your base configuration in a file, and override or add settings by providing command line arguments.