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):
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):
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
dbDirectorydirectory where the database is stored (default: "objectbox").dbMaxSizedatabase size limit; use a number with a unit, e.g. 256G (default: 100G)Kfor kibibytes, i.e. 1024 bytesMfor mebibytes, i.e. 1024 kibibytesGfor gibibytes, i.e. 1024 mebibytesTfor tebibytes, i.e. 1024 gibibytes
modelFileschema (model) file to create the database with or to use for a schema updatebindSync server will bind on this URL (scheme, host and port). It should look likews://hostname:port, for examplews://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 byifconfigorip addr, e.g.ws://192.168.0.125:9999.adminBindHTTP server (admin/web UI) will bind on this URL (schema, host and port combination).
Developer and debug options
unsecuredNoAuthenticationallows connections without any authentication. Note: this is unsecure and should only be used to simplify test setups.debugLogenable debug logs withtrue
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):
Authentication options
auth.jwtJWT is the primary method for authentication. See the JWT authentication page for details.
Sync filter expressions
syncFiltersthis 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
adminThreadsnumber 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.sharedSecretif not empty, enables the shared secret authentication with the given keyauth.google.clientIdsa list of GoogleAuth client IDs (strings)auth.obxAdminset it totrueto enable ObjectBox Admin users for sync authentication (e.g. for small deployments and tests)certificatePathSupply a SSL certificate directory to enable SSL. This directory must contain the filescert.pemandkey.pem.workerssets 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:
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.
Last updated