Skip to content

Server Configuration

The Tryll server reads two JSON files at startup: server-config.json (server settings — this page) and models.json (model catalog — see model management). A third file, downloads.json, is written and maintained by the server itself at runtime and should not be edited by hand.

This page documents every field of server-config.json. Relative paths inside the file are resolved against the directory containing the config file — not the process's working directory.

Location and override

The default location is data/server-config.json, symlinked next to the server executable at build time. Two CLI flags can override values without editing the file:

tryll_server.exe --config path/to/server-config.json
tryll_server.exe --port 9200

Both flags can be combined. --port overrides the port field from the config file and is how ManagedServer (C++ and Python clients) ensures the port it connects to matches the port the server listens on.

Missing fields keep their defaults; the server runs with all defaults even if the file is absent.

Minimal config

<!-- sample only; not a committed file -->
{
    "port": 9100,
    "thread_count": 4,
    "models_catalog_path": "models.json",
    "models_download_dir": ".app-data/models",
    "logs_dir": ".app-data/logs",
    "log_mode": "dev",
    "log_level": "trace"
}

Fields

Networking

Field Type Default Description
port uint16 9100 TCP port the server listens on. The wire protocol is plain TCP; clients connect to localhost:<port>.
thread_count uint 4 Size of the server's I/O thread pool. Increase for higher concurrency across many simultaneous sessions; does not affect single-agent inference throughput, which is bounded by the server's one-model-at-a-time inference queue.

Model catalog

Field Type Default Description
models_catalog_path string "data/models.json" Path to the model catalog JSON. Relative paths resolved from the config file's directory.
models_download_dir string "data/.models/" Directory where HuggingFace-downloaded model files are stored. The server creates the directory if it does not exist. Also the location of downloads.json, the runtime-maintained record of completed downloads.

Logging

Field Type Default Description
logs_dir string "data/logs" Directory for log files. Set to "" (empty string) for console-only logging. The directory is created if it does not exist.
log_mode string "production" Log file naming. "production" writes a single rotating tryll.log (10 MiB × 5 files). "dev" writes a new tryll_<timestamp>.log per process start with no rotation.
log_level string "info" Minimum log level. One of "trace", "debug", "info", "warn", "error". Use "trace" to capture per-node workflow events for debugging graphs.

In both log modes the console sink is always active.

Node defaults

Field Type Default Description
default_canned_responses_path string "data/default-canned-responses.txt" Path to the default response list for canned-response nodes that do not specify their own string storage. UTF-8 text, one response per line; blank lines and lines starting with # are skipped.
default_guardrail_patterns_path string "data/default-guardrail-patterns.txt" Path to the default regex list for human-message-guardrail nodes that do not specify their own string storage. Same format as above; patterns match case-insensitively.

Both files are loaded lazily on first use; an absent file on startup is fine as long as no node ever requests the default list.

Diagnostics

Field Type Default Description
include_interaction_in_diagnostics bool false When true, and the client sets enable_diagnostics = true on CreateAgentRequest, the current interaction's components are serialised into TurnDiagnostics.interaction on TurnCompleteResponse. Each component appears as a flat JSON object with a "_type" discriminator. Intended for debug sessions; payload grows linearly with component count.

Telemetry

Tryll ships with usage telemetry enabled by default. The top-level "telemetry" object controls it. See Telemetry for the full background — what is collected, where it goes, and what you must do before shipping a game to players.

Field Type Default Description
telemetry.enabled bool true Master switch. Set to false to disable all telemetry with zero hot-path cost.
telemetry.include_user_content bool false When true, human messages and character replies are included in turn events. Keep false unless you explicitly want conversation content in your analytics sink.
telemetry.sinks array PostHog EU sink List of sink objects. Remove or empty this array to stop sending data to PostHog (required before shipping a game to players).

Each sink in "sinks" supports:

Field Type Description
kind string Sink type. Currently only "posthog" is supported.
enabled bool Per-sink on/off switch.
endpoint string PostHog ingest URL, e.g. "https://eu.i.posthog.com".
project_api_key string PostHog project API key (phc_…).
batch_max_records uint Maximum events per batch before flushing. Default 50.
batch_max_ms uint Maximum milliseconds before a batch is flushed. Default 2000.
queue_capacity uint In-memory event queue size; oldest entry dropped when full. Default 5000.
shutdown_flush_ms uint How long (ms) to wait for queue drain on server shutdown. Default 5000.

Log-mode details

Value File naming Rotation
"production" tryll.log 10 MiB max, 5 files kept
"dev" tryll_2026-04-06_14-30-00_123.log No rotation; new file per run