# TypeDB Configuration

You can configure a TypeDB server via two means: a YAML config file or command line options. Command line options override values defined in the config file.

For a full list of configurable properties run:

```bash
typedb server --help
```

This page lists & explains the available options.

## [](#_general_cli_arguments)General CLI arguments

General, non-configuration arguments available on the CLI.

  

General CLI arguments

`--config <path-to-file>`

Specify a custom configuration file

`--help`

`-h`

Show help message.

`--version`

`-V`

Print version information and exit.

## [](#_configuration_file)Configuration file

By default, TypeDB looks for a `config.yml` file in the same folder as the TypeDB server executable (i.e., `/server/config.yml`). This path can be overridden using the CLI argument: `--config <path-to-your-config>`.

## [](#_command_line_overrides)Command line overrides

When using the command line to override a specific option, all CLI arguments must:

*   start with the double dash prefix `--`,
    
*   be separated from their value (if any) either by an equals sign (`--arg=val`) or a whitespace (`--arg val`).
    

e.g., `--server.listen-address=0.0.0.0:1730`

## [](#_overview)Configuration options

### [](#_server)Server

The `server` section of the configuration contains network and encryption options. For example, a server can be booted up to listen on `0.0.0.0:1730` by using this command:

```bash
typedb server --server.listen-address=0.0.0.0:1730
```

#### [](#_listen_vs_advertise)Listen vs. advertise addresses

Each public network endpoint has two addresses:

*   The **listen** address is what the server binds to locally — the interface and port where it accepts connections.
    
*   The **advertise** address is what the server reports back to clients (and, in clustered deployments, to peer servers). Clients use the advertise address to connect if it is presented.
    

When the server is reached directly, both can be the same. When the server sits behind a NAT, reverse proxy, or load balancer, the listen address is the local bind (often `0.0.0.0:<port>`) and the advertise address is the externally-reachable host:port that clients should dial.

If `advertise-address` is omitted, the server does not report back any address to gRPC/HTTP connections. Then, the clients must not depend on the server’s information, using the initial connection address for further communication.

Multi-node environments **must** use advertise addresses for efficient failover logic execution on the client side.

 

Server

`server.listen-address`

Server gRPC listen host and port — the address the server binds to. Default value: `0.0.0.0:1729`.  
Alias (deprecated): `server.address`. Specifying both `server.listen-address` and `server.address` is rejected.

`server.advertise-address`

Server gRPC advertise host and port — the address shared with clients. Required when the listen and advertise addresses differ (e.g., behind a proxy or NAT).

`server.http.enabled`

Enable/disable HTTP endpoint. Default value: `true`.  

`server.http.listen-address`

HTTP listen host and port — the address the server binds to. Cannot be the same as `server.listen-address`. Default value: `0.0.0.0:8000`.  
Alias (deprecated): `server.http.address`. Specifying both `server.http.listen-address` and `server.http.address` is rejected.

`server.http.advertise-address`

HTTP advertise URL shared with clients (include the scheme, e.g. `[http://127.0.0.1:8000](http://127.0.0.1:8000)` or `[https://typedb.example.com](https://typedb.example.com)`). Required when the listen and advertise addresses differ. Default value: derived from `server.http.listen-address`.

`server.authentication.token-expiration-seconds`

The amount of seconds generated authentication tokens will remain valid, specified in seconds. Default value: `14400` (4 hours).  

#### [](#_admin)Admin endpoint

TypeDB exposes a separate admin gRPC endpoint over a local IPC channel — a Unix domain socket on Linux and macOS, a Named Pipe on Windows — used by the bundled `typedb admin` CLI tool to inspect and manage a running server (see [TypeDB Admin Tool](../../tools/admin/index.md)).

 

Server admin

`server.admin.enabled`

Enable/disable the local admin endpoint. Default value: `false`.  

`server.admin.socket-path`

Filesystem path of the admin Unix domain socket (Linux/macOS) or the Named Pipe name (Windows). Default value: `<data-directory>/admin.sock` on Linux/macOS, `\\.\pipe\typedb-admin` on Windows.  
On Linux/macOS the path must be short enough to fit `sun_path` (typically ≤ 108 bytes).  

#### [](#_encryption)Encryption

Configure the TLS certificate & private-key to be used for inflight encryption.

 

Server encryption

`server.encryption.enabled`

Enable in-flight encryption. Do not specify this argument to leave it disabled.  

`server.encryption.certificate`

Encryption certificate in PEM format. Must be supplied if encryption is enabled.  

`server.encryption.certificate-key`

Encryption certificate key. Must be supplied if encryption is enabled.  

`server.encryption.ca-certificate`

Encryption CA in PEM format. (Optional)  

### [](#_storage)Storage

The `storage` section of the configuration contains the storage layer options.

For production use, it is recommended that the `storage.data-directory` is set to a path outside the `$TYPEDB_HOME` (directory with TypeDB server files).

This helps to make the process of upgrading TypeDB easier.

 

Storage

`storage.data-directory`

Path to the user data directory. Defaults to within the server distribution under `server/data`.  

`storage.rocksdb.cache-size`

Size of the shared RocksDB block cache, the in-memory cache of data blocks read from disk. This is a single pool shared by all databases on the server. Default value: `1gb` (1 GiB).  
This is a soft limit: it may be exceeded by index and filter blocks that RocksDB pins in memory.

`storage.rocksdb.write-buffers-limit`

Total memory budget for the RocksDB write-buffer manager — the in-memory write buffers (memtables) that hold writes before they are organized on disk. This is a single pool shared by **all** databases on the server. Default value: `512mb` (512 MiB).  
When the limit is reached, writes are stalled (slowed) until memory is freed by a flush, rather than allowed to grow without bound. Note: does not affect durability guarantees, which are provided by the WAL.

Size values such as `storage.rocksdb.cache-size` and `storage.rocksdb.write-buffers-limit` are written as an integer with an optional, case-insensitive unit suffix: `B`, `KB`/`KiB`, `MB`/`MiB`, `GB`/`GiB`, or `TB`/`TiB`. A bare number is interpreted as bytes.

The units are binary (powers of 1024), so `KB` is identical to `KiB`, `MB` to `MiB`, and so on. `1gb` means 1 GiB = 1,073,741,824 bytes. Fractional values (e.g. `1.5gb`) are not accepted; use a smaller unit instead (e.g. `1536mb`). Examples: `1gb`, `512mb`, `1024MiB`, `2048`.

### [](#_diagnostics)Diagnostics

TypeDB optionally reports anonymous diagnostics to guide the development and optimisation of TypeDB. This data includes unexpected errors and occasional system status updates for number and size of databases, as well as numbers of transactions and queries executed per hour.

To see what information is being reported, enable and access the monitoring Web page of the server (e.g. `localhost:4104/diagnostics?format=json`).

See [Diagnostics monitoring endpoint](../diagnostics-endpoint/index.md) for the full list of Prometheus metrics exposed and how to scrape them.

 

Diagnostics

`diagnostics.reporting.metrics`

Enable usage metrics reporting by setting a boolean flag. Default value: `true`.  

`diagnostics.reporting.errors`

Enable critical error reporting by setting a boolean flag. Default value: `true`.  

`diagnostics.monitoring.enable`

Enable a diagnostics monitoring HTTP endpoint by setting a boolean flag. Default value: `true`.  

`diagnostics.monitoring.port`

Port on which to expose the diagnostics monitoring endpoint. Default value: `4104`.  

### [](#_log)Logging

You can configure the directory that TypeDB uses for server logs.

 

Logging

`logging.directory`

Path to the server logs directory. Defaults to within the server distribution under `server/logs`.  

## [](#_machine_requirements)Host machine configuration

This section describes recommended changes to the host OS.

### [](#_open_file_limit)Open file limit

To support large data volumes, it is important to check the open file limit the operating system imposes. Some Unix distributions default to `1024` open file descriptors. This can be checked with the following command:

```bash
ulimit -n
```

We recommend this is increased to at least `50 000`.

### [](#_memory_usage)Memory usage

The resident memory of a TypeDB server is dominated by the two shared RocksDB pools configured under `storage.rocksdb`, plus transactional and query execution memory.

*   **Block cache** (`storage.rocksdb.cache-size`, default `1gb`) — caches uncompressed data blocks read from disk so that hot reads are served from memory. Increasing this generally improves read performance.
    
*   **Write buffers** (`storage.rocksdb.write-buffers-limit`, default `512mb`) — hold writes in memory as they are flushed to disk. Hitting the limit causes write slowdowns as memory is cleared. Increasing this generally improves bulk loading performance but rarely affects low throughput occasional writes.
    

Both `storage.rocksdb` limits are server-wide totals, so they do not need to be scaled up for each additional database. They should instead be sized relative to the host’s total RAM and the active working set across all databases.

Working, dynamically allocated memory is also required for TypeDB’s transactional write buffers, query execution working space, and the OS page cache. The easiest way to keep these predictable is to try to use smaller rather than larger write transactions.

As rough guidance for a dedicated host:

*   To improve read performance, increase `storage.rocksdb.cache-size` so that the working set fits in cache. As a minimum, aim for at least 5% of the on-disk data size across all databases to fit in the block cache.
    
*   Avoid configuring `cache-size` + `write-buffers-limit` close to the host’s total RAM as this leaves little room for the rest of the server’s working set.
    
*   Increase `storage.rocksdb.write-buffers-limit` for sustained, write-heavy workloads if you observe write stalls; the limit trades memory for write throughput.
    

Server memory consumption can be observed live via the `server_resources_count{kind="memoryUsedInBytes"}` metric on the diagnostics monitoring endpoint — see [Server resource usage](../diagnostics-endpoint/index.md#_server_resource_usage).

[TypeDB Backups](../typedb-backups/index.md) [Diagnostics monitoring endpoint](../diagnostics-endpoint/index.md)

[Edit on GitHub](https://github.com/typedb/typedb-docs/edit/3.x-development/maintenance-operation/modules/ROOT/pages/typedb-configuration.adoc) Edit this page on GitHub.