Configuration

To set up 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 basic settings (limitations apply)

• configuration file (JSON): recommended for complex settings and required for sync filters and clusters

Note that both approaches can be combined (CLI parameters take precedence over file configuration).

Configuration via command line (CLI)

Running the Sync Server from the command line is a simple way to get started. It's a good idea to 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 CLI Help Output (click to expand)

sync-server --help
001-16:12:08.9830 [INFO ] [SvSyAp] Starting ObjectBox Sync Server version 5 (protocol version: 6, core: 4.0.3-2025-01-24 (SyncServer, http, graphql, admin, tree, dlog, cluster, backup, lmdb, VectorSearch, SyncMongoDb))
ObjectBox Sync Server
Usage:
  sync-server [OPTION...]

      --admin-bind arg          host/IP and port the admin http server 
                                should listen on (default: 
                                http://127.0.0.1:9980)
      --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)
      --auth-obx-admin          Enable ObjectBox Admin Users database for 
                                authentication
      --auth-required arg       Comma-separated list of authentication 
                                methods (credential types) required for 
                                clients to connect (default: "")
  -b, --bind arg                host/IP and port the sync server should 
                                listen on (default: "")
  -c, --conf arg                configuration file path (default: 
                                sync-server-config.json)
      --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
      --fixed-leader            make the server the (only!) leader of the 
                                cluster (danger: read docs carefully!)
  -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
      --jwt-public-key-url arg  URL to the public key for JWT token 
                                validation (default: "")
      --jwt-claim-aud arg       Expected audience claim in JWT token 
                                (default: "")
      --jwt-claim-iss arg       Expected issuer claim in JWT token 
                                (default: "")
  -m, --model arg               schema model file to load (JSON) (default: 
                                "")
      --mongo-url arg           MongoDB Sync Connector: URL to the MongoDB 
                                instance (default: "")
      --mongo-db arg            MongoDB Sync Connector: name of the primary 
                                MongoDB database to sync (default: "")
      --no-stacks               disable stack traces when logging errors
      --unsecured-no-authentication
                                [UNSECURE] allow connections without 
                                authentication
      --workers arg             number of workers for the main task pool 
                                (default is hardware dependent, e.g. 3 * 
                                CPU "cores") (default: 0)
      --restore-backup arg      restores the DB to the given backup file 
                                (by default, restoration takes place only 
                                if no DB exist)
      --backup-overwrites-db    forces the restoration of the backup even 
                                if the DB already exists (danger: 
                                overwrites the db permanently!)

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

In the long run, you should store the configuration in a JSON file. This is the preferred choice if our options are getting more complex. Also, you can check in the configuration file into version control.

Note that some options are only available in the config file (not the CLI):

• Cluster

• Sync Filters

• Individual debug log flags

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.

Example file for a local development setup (not intended for production use as auth is disabled):

{
  "dbDirectory": "objectbox",
  "dbMaxSize": "100G",
  "modelFile": "objectbox-model.json",
  "bind": "ws://0.0.0.0:9999",
  "adminBind": "http://127.0.0.1:9980",
  "_note": "unsecuredNoAuthentication should not be used in production",
  "unsecuredNoAuthentication": true,
  "debugLog": true
}

Start JSON keys with underscore (_) to add comments or to temporarily disable a setting. These keys are exempt from validation and will be ignored by the Sync Server.

Example: "_debug": true and "_note1": "my comment" are ignored.

Primary options

• 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 (scheme, host and port). It should look like ws://hostname:port, for example ws://127.0.0.1:9000. 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://192.168.0.125:9999.

• adminBind HTTP server (admin/web UI) will bind on this URL (schema, host and port combination).

Developer and debug options

• unsecuredNoAuthentication allows connections without any authentication. Note: this is unsecure and should only be used to simplify test setups.

• debugLog enable debug logs with true

When using debug logs, advanced users can enable additional logs for internal components (e.g. ObjectBox support may ask you to enable specific logs). This is done using boolean flags in the log JSON object (all default to false when omitted).

• transactionRead: Log the lifecycle of read transactions (begin/commit/abort).

• transactionWrite: Log the lifecycle of write transactions and commits to help diagnose write-related issues.

• queries: Log executed queries to aid in understanding which lookups are performed at runtime.

• queryParameters: Log parameter values bound to queries. May include sensitive data.

• asyncQueue: Log asynchronous operations.

• cacheHits: Log cache hits and misses to evaluate cache effectiveness (note: only a few metadata items are cached).

• cacheAll: Log all cache operations (puts/gets/evictions); very verbose and intended for deep diagnostics.

• tree: Log special tree data models.

• exceptionStackTrace: Attempt to include stack traces for certain internal error logs (Linux-only, experimental).

• threadingSelfTest: Run a quick threading self-test at startup and log its progress and results.

• wal: Enable detailed write-ahead logging (WAL, not used by default) debug output.

• idMapping: Log how IDs are mapped between local and global spaces during synchronization.

• syncFilterVariables: Log values of sync filter variables per client (e.g. derived from JWT or the login message). May include sensitive data.

Example to enable sync-related debug logs (this quickly gets excessive; don't do this by default):

{
  "debugLog": true,
  "log": {
    "idMapping": true,
    "syncFilterVariables": true
  }
}

Authentication options

• auth.jwt JWT is the primary method for authentication. See the JWT authentication page for details.

Sync filter expressions

• syncFilters this JSON object contains all filter expressions. Each filter has the type as key and a string value as the expression. Details are available in the sync filters page.

Advanced options

• 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).

• auth.sharedSecret if not empty, enables the shared secret authentication with the given key

• auth.google.clientIds a list of GoogleAuth client IDs (strings)

• auth.obxAdmin set it to true to enable ObjectBox Admin users for sync authentication (e.g. for small deployments and tests)

• certificatePath Supply a SSL certificate directory to enable SSL. This directory must contain the files cert.pem and key.pem.

• workers sets the number of concurrent workers for the main task pool (default is hardware dependent, e.g. 3 times the number of CPU cores).

Clusters

To set up a cluster, please refer to the cluster page for specific configuration options.

Authentication

Authentication settings for clients are required; the Sync Server won't start without them. If you try, it should look something like this:

$ ./sync-server --model=objectbox-model.json
...
001-13:05:07.3526 [ERROR] [SySvAp] Runtime error: Authenticator must be set before starting
001-13:05:07.4524 [INFO ] [SvSync] Stopped (port 0)
Authenticator must be set before starting

During development on your private network, you can disable authentication altogether using the option --unsecured-no-authentication. This allows all clients, which know the server's URL, to connect without additional checks.

Warning: it should be obvious that this setting is not intended for production usage.

For production usage, please refer to the JWT authentication page on how to authenticate your clients.

Other authentication methods are mentioned above in the configuration overview, i.e. Google Authentication with client IDs, shared secret, Admin users. Typically, we recommend using JWT, but there may be occasions where you need to use other authentication methods. Let the ObjectBox team know about your use case and requirements. E.g. it is possible to define multiple authenticators.

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.