Server Configuration

Configure the Traverse server with CLI arguments, environment variables, or a TOML config file.

Configuration Priority

Settings are resolved in order of precedence (highest to lowest):

1. CLI arguments
2. Environment variables
3. TOML config file (traverse.toml in CWD, or --config)
4. Default values

CLI Arguments

Environment Variables

Every CLI flag has a corresponding environment variable:

TOML Config File

Place a traverse.toml in the working directory, or specify a path with --config:

listen = "0.0.0.0:7690"
http_listen = "0.0.0.0:7691"
data = "/var/lib/traverse/data"
default_db = "traverse"
memory_limit = "4GB"
auth = "admin:s3cret"
query_timeout = 30000
slow_query_threshold = 1000
durability = "snapshot"        # or "wal" for per-commit crash durability
allowed_ips = ["192.168.1.0/24", "10.0.0.0/8"]
allow_drop_database = false
api_key = "tvs_your_api_key_here"
api_base = "https://api.truespar.com"
license_key = "tskey_your_key_here"
log_level = "info"
log_dir = "/var/log/traverse"

# TLS (optional)
tls_cert = "/etc/traverse/cert.pem"
tls_key = "/etc/traverse/key.pem"

# gRPC (optional)
grpc_listen = "0.0.0.0:50051"

Data Storage

Traverse is an in-memory database. Data is loaded from .tvdb files on startup and persisted back on graceful shutdown.

• Directory mode: --data /path/to/dir - scans all *.tvdb files; each file stem becomes the database name
• File mode: --data /path/to/file.tvdb - loads a single database named with the --default-db value

Persisting Data

Data is auto-saved on graceful shutdown. Two ways to trigger:

1. SIGTERM/SIGINT (Ctrl+C) - preferred. Do not use kill -9 or taskkill /F as these skip the save step.
2. HTTP API: POST /api/save - saves all databases immediately.

Durability

New in 0.8.0: Traverse supports two durability modes, selected with --durability, TRAVERSE_DURABILITY, or the durability TOML key.

# Per-commit crash durability
traverse-server --data ./data --durability wal

Switching modes between runs is safe: write-ahead log segments from a previous run are replayed on the next startup regardless of the new mode. Choose snapshot for maximum write throughput (analytics, bulk loads, caches rebuilt from source data) and wal when Traverse is the system of record.

Client Compatibility

Traverse implements the Bolt protocol and works with the standard Neo4j drivers. Some client applications, however, verify that the server identifies itself as a genuine Neo4j instance during the Bolt handshake and refuse to connect otherwise, with an error such as:

Server does not identify as a genuine Neo4j instance: 'Traverse/0.8.1'

To use those clients, override the advertised Bolt server agent so it starts with Neo4j/:

traverse-server --data ./data --server-agent "Neo4j/5.26.0"

or with the environment variable:

TRAVERSE_SERVER_AGENT="Neo4j/5.26.0" traverse-server --data ./data

The default agent is Traverse/<version>; this override only changes the identification string, not behavior. It is a compatibility aid for third-party tools.

Inspecting Resolved Configuration

The running server exposes its resolved configuration through the SHOW SETTINGS Cypher command (composable with YIELD / WHERE). Secrets such as the license key and API key are redacted.

SHOW SETTINGS YIELD name, value WHERE name CONTAINS 'bolt';

Authentication

Seeding an Admin User

Use --auth to create an initial admin user on startup:

traverse-server --auth admin:s3cret --data ./data

User Roles

Managing Users

Via Cypher (in the CLI or through a Bolt driver):

CREATE USER alice SET PASSWORD 'hunter2' SET ROLE EDITOR;
ALTER USER alice SET ROLE ADMIN;
DROP USER alice;
SHOW USERS;

Users can also be managed via the HTTP API (GET/POST/PUT/DELETE /api/users). Passwords are hashed with bcrypt (cost factor 12) and persisted in the .tvdb metadata of the default database.

API Key

The HTTP API and Studio require an API key for authentication. A random key (tvs_ prefix + 32 hex characters, 128-bit entropy) is auto-generated on startup unless you specify one:

traverse-server --api-key tvs_your_custom_key_here

If you provide a custom key, it must start with the tvs_ prefix.

Clients authenticate with one of:

• Authorization: Bearer tvs_... header
• X-API-Key: tvs_... header
• ?token=tvs_... query parameter

IP Filtering

Restrict connections by IP address using CIDR notation:

traverse-server --allowed-ips "192.168.1.0/24,10.0.0.0/8"

Both IPv4 and IPv6 ranges are supported. When not set, all IPs are allowed. Applied at connection acceptance.

TLS

Enable encrypted connections by providing a certificate and private key:

traverse-server --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

Once TLS is enabled, Bolt clients connect via bolt+s:// and the HTTP API is served over HTTPS.

Memory Limit

By default Traverse uses up to 90% of system RAM. Override with:

traverse-server --memory-limit 4GB

Accepts TB, GB, MB, KB suffixes (case-insensitive), or raw byte counts.

Query Timeout

Set a cooperative query timeout to prevent long-running queries:

traverse-server --query-timeout 30000  # 30 seconds

Queries exceeding the timeout are cancelled via a thread-local deadline mechanism.

Slow Query Logging

Log queries that exceed a time threshold:

traverse-server --slow-query-threshold 1000  # log queries taking > 1 second

Windows Service

On Windows, Traverse can be installed as a system service:

REM Install the service (name: TraverseServer, display: "Traverse Graph Database")
traverse-server --service-install

REM Start/stop via sc or net
sc start TraverseServer
sc stop TraverseServer

REM Uninstall
traverse-server --service-uninstall

The service starts automatically on boot (AutoStart), runs as LocalSystem. Configuration is read from traverse.toml in the executable's directory or from environment variables. Logs are written to the Windows Event Viewer.

License

Set a license key to activate Traverse Enterprise and remove trial restrictions:

traverse-server --license-key tskey_your_key_here

License features control limits on: maximum databases, maximum nodes/edges per database, maximum concurrent connections, user management, and Graph Assistant (an AI-powered assistant that helps you write Cypher queries and explore your graph data).

License status levels:

• Trial - 30-day trial period
• Active - valid subscription
• Grace Period - 7 days after expiry (cached license data)
• Expired - no active license, no cache