---
title: "Configuration"
description: "Configure a self-hosted SurrealDB server: CLI options, environment variables, storage, networking, auth, and TLS."
canonical_url: "https://surrealdb.com/docs/operate/self-hosted/configuration"
section: "Self-hosted"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Configuration

Configure a self-hosted SurrealDB server: CLI options, environment variables, storage, networking, auth, and TLS.

Most server behaviour is fixed at process start. The [`surreal db start`](/docs/reference/cli/db/commands/start.md) command is the primary entry point: pass flags for bind addresses, storage paths, authentication, TLS material, logging, and feature toggles.

Review the command reference whenever you upgrade, as defaults and supported flags can change between releases. Keep a short changelog of server flags per environment so rollbacks and comparisons stay straightforward.

Equivalent settings are often available as [environment variables](/docs/reference/cli/db/environment-variables.md), which suits containers, systemd units, and secret managers. Prefer one coherent source of truth (file, env, or flags) so configuration does not diverge silently across hosts.

**Running in the background.** `surreal db start` runs in the foreground and has no daemon mode of its own, so let the operating system's service manager start it, restart it after a failure, and stop it cleanly. In a container, `docker run -d` runs the same server in the background.

**Linux**

On Linux, let systemd run the server. Save the following as `/etc/systemd/system/surrealdb.service`, then run `sudo systemctl enable --now surrealdb`:

```ini title="/etc/systemd/system/surrealdb.service"
[Unit]
Description=SurrealDB server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=surrealdb
Group=surrealdb
EnvironmentFile=/etc/surrealdb/surrealdb.env
ExecStart=/usr/local/bin/surreal db start
Restart=on-failure
LimitNOFILE=infinity

[Install]
WantedBy=multi-user.target
```

The unit reads its settings from the environment file, which keeps the root password out of the unit file and the process list. The variable names are those on the [environment variables](/docs/reference/cli/db/environment-variables.md) page:

```ini title="/etc/surrealdb/surrealdb.env"
SURREAL_USER=root
SURREAL_PASS=secret
SURREAL_BIND=127.0.0.1:8000
SURREAL_PATH=surrealkv:///var/lib/surrealdb/data
```

Restrict the file with `chmod 600`, and make sure the `surrealdb` user owns the data directory. Use `journalctl -u surrealdb -f` to follow the server log.

**Windows**

`surreal.exe` is not written as a Windows service, so registering it directly with `sc.exe create` fails with error 1053 when the service starts. A service wrapper such as [WinSW](https://github.com/winsw/winsw) runs it as a service instead. Download `WinSW-x64.exe` from the WinSW releases, save it as `C:\SurrealDB\surrealdb-service.exe`, and save the following beside it as `surrealdb-service.xml`:

```xml title="C:\SurrealDB\surrealdb-service.xml"
<service>
  <id>surrealdb</id>
  <name>SurrealDB</name>
  <description>SurrealDB server</description>
  <executable>C:\Program Files\SurrealDB\surreal.exe</executable>
  <arguments>db start</arguments>
  <workingdirectory>C:\SurrealDB</workingdirectory>
  <env name="SURREAL_USER" value="root" />
  <env name="SURREAL_PASS" value="secret" />
  <env name="SURREAL_BIND" value="127.0.0.1:8000" />
  <env name="SURREAL_PATH" value="surrealkv://data" />
  <onfailure action="restart" delay="10 sec" />
  <log mode="roll" />
</service>
```

The `<env>` entries play the part of the Linux environment file, with the same [environment variables](/docs/reference/cli/db/environment-variables.md). The relative data path is resolved from the working directory, so the data is stored in `C:\SurrealDB\data`. Then, in a terminal opened as administrator, install and start the service:

```powershell
cd C:\SurrealDB
.\surrealdb-service.exe install
.\surrealdb-service.exe start
```

The service starts with Windows from then on. WinSW stops the server by sending it Ctrl+C, which SurrealDB handles as a clean shutdown, and writes the server's output to log files in `C:\SurrealDB`. The XML file holds the root password, so limit who can read it, for example with `icacls surrealdb-service.xml /inheritance:r /grant:r Administrators:F SYSTEM:R`.

**Storage engines** are selected by the path on [`surreal db start`](/docs/reference/cli/db/commands/start.md). For on-disk production data on a self-hosted server, use **SurrealKV** (`surrealkv://…`). RocksDB (`rocksdb://…`) was removed in SurrealDB 4.0; see [Moving a RocksDB database to SurrealKV](/docs/operate/self-hosted/deployment-models.md#moving-a-rocksdb-database-to-surrealkv). The default **`memory`** backend (SurrealMX) suits development and tests as well as solutions that make use of its Redis-like persistent storage. Capacity planning, backups, and versioning options differ by engine - see the [Deployment models](/docs/operate/self-hosted/deployment-models.md) and [Run a single-node, on-disk server](/docs/running/file-backed.md) pages for more.

**Bind address and port** determine where clients and operators reach the server. Restrict admin interfaces to trusted networks, use a load balancer or service mesh for TLS termination if that matches your platform, and document ports for HTTP, WebSocket, and any separate metrics endpoints you expose.

Firewall rules should default to deny: allow only the subnets and ports your applications and operators require.

Set **authentication** and **root user** credentials explicitly in production. Root credentials grant broad access: rotate them on a schedule, store them in a vault, and avoid reusing development passwords.

**TLS**: supply certificates and keys via `surreal db start` or env vars so wire traffic is encrypted. Renew certificates before expiry, pin trusted CAs where appropriate, and consider a reverse proxy for advanced policies while keeping SurrealDB’s own TLS configuration minimal and auditable.

After changes, confirm the effective configuration by inspecting startup logs and probing only the intended listeners. In regulated environments, record who approved credential and TLS updates and when they took effect.
