Configuration Reference

4got uses KDL (KDL Document Language) for all configuration. All config files live in the data/ directory.

config.kdl

The main configuration file. All fields have sensible defaults.

Environment variable overrides

Every config.kdl field has a corresponding FGOT_* environment variable:

• FGOT_PORT, FGOT_HOST, FGOT_OWNER_SECRET, FGOT_DELUXE_SECRET
• FGOT_POW_DIFFICULTY, FGOT_CAPTCHA_HOURS, FGOT_POW_SECONDS
• FGOT_MAX_SEARCHES, FGOT_FANOUT_HARD_WINDOW_MS, FGOT_FANOUT_IDLE_TIMEOUT_MS
• FGOT_CACHE_WEB_S, FGOT_CACHE_IMAGES_S, FGOT_CACHE_NEWS_S
• FGOT_DATA_DIR, FGOT_DB_PATH
• FGOT_CONFIG — override the config file path entirely

KDL config files

4got uses KDL (KDL Document Language) for structured subsystem configs. Each subsystem looks for its config in two places:

1. A dedicated file (e.g. data/peers.kdl)
2. A named section inside any *.kdl file in data/ (e.g. a peers { ... } block inside data/conf.kdl)

You can use either approach but not both for the same subsystem. This lets you keep everything in a single conf.kdl or split into per-subsystem files.

peers.kdl

Configures the friend/peer network for cache sharing and service proxying.

// How many friends to wait for before proceeding.
// Float 0-1: proportion of 'up' friends (1.0 = all, 0.5 = half)
// Int >= 1: exact count
// Negative: "ok to miss" semantics (-2 = ok missing 2 friends)
wait-for 1.0

// Store results received from friends in local cache
store-friend-cache true

// Mark a friend as 'down' if they fail more than this proportion
// of requests over this time window.
failure-threshold 0.01 1d

// Services this instance allows friends to proxy through us
allow-proxy "translation" "wolfram" "autocomplete"

// Always wait for a specific friend (by name)
// always-wait-for "alice"

// Prefer a friend for specific services
// prefer-friend "alice" for="translation,wolfram"

peer "instance-b" {
    url "http://127.0.0.1:8890"
    // Optional mTLS:
    // cert "/path/to/client.crt"
    // key "/path/to/client.key"
}

groups.kdl

Defines user tiers/groups and their permissions.

group "deluxe" {
    allow "sidecar" "server_api_keys" "friend_proxy" "priority_fanout"
    label "deluxe"
}

group "researcher" {
    allow "server_api_keys"
    label "researcher"
}

Known permissions: sidecar, server_api_keys, friend_proxy, priority_fanout. Groups are assigned to users by cookie hash via the admin panel (/admin/users).

captcha.kdl

Configures the pre-rendered captcha (IQ test) pool.

pool {
    distorted-target 500     // target pool size for distorted tiles
    distorted-batch 50       // generate this many per cycle
    prebuilt-target 100      // target pool size for assembled captchas
    prebuilt-batch 20        // assemble this many per cycle
    cycle-count 25           // number of generation cycles at startup
    cycle-interval-min 5     // minutes between background replenishment cycles
}

autocomplete.kdl

Configures autocomplete suggestion backends and their weights.

backend "duckduckgo" weight=1 enabled=true
backend "brave" weight=1 enabled=true
backend "qwant" weight=1 enabled=true
backend "yahoo" weight=1 enabled=true
backend "wikipedia" weight=1 enabled=true
backend "google" weight=1 enabled=false

Higher weight = more influence when merging suggestions from multiple backends.

translation.kdl

Configures translation backends with priority routing and per-user rate limits.

// Language sets (non-overlapping)
set "cjk" "ja" "zh" "ko"
set "eu" "de" "fr" "nl" "pl" "es" "pt" "it" "ro" "sv" "da" "no" "fi" "cs" "hu" "el"

// Backends: priority (higher=tried first), languages ("all" or set name),
// limit-per-cookie, reset hours
backend "deepl" priority=3 languages="eu" limit=500 reset-hours=24
backend "papago" priority=3 languages="cjk" limit=50 reset-hours=24
backend "lingva" priority=2 languages="all" limit=100 reset-hours=24
backend "nllb" priority=1 languages="all" limit=0
backend "microsoft" priority=2 languages="all" limit=30 reset-hours=24

instances.kdl

Configures the instance browser (shows other 4got instances).

fetch-interval-min 60

friends {
    // instance "https://search.friend.example.com"
}

public {
    // instance "https://public.4got.example.com"
}

ai-research.kdl

Configures the AI research agent that synthesizes search results.

enabled true
mode "lua"                    // "lua" (sandboxed) or "bash" (dangerous)
provider "cerebras"
model "llama3.1-8b"
api-key "csk-..."
base-url "https://api.cerebras.ai/v1"
max-runtime-seconds 60
require "deluxe"              // group permission required

See ai-research.md for full details.

image-proxy.kdl (optional)

Configures the SQLite-backed image proxy cache.

enabled true
hold-time-days 30             // evict images unserved for this many days
jxl-reencode true             // reencode to JXL (requires cjxl binary)
redownload-threshold 999      // re-fetch original after N serves
require "deluxe"              // group permission required ("" for everyone)

The unified conf.kdl option

Instead of separate files, you can put everything in a single data/conf.kdl:

peers {
    wait-for 1.0
    peer "instance-b" {
        url "http://127.0.0.1:8890"
    }
}

groups {
    group "deluxe" {
        allow "sidecar" "server_api_keys"
        label "deluxe"
    }
}

translation {
    backend "lingva" priority=2 languages="all" limit=100 reset-hours=24
}

The resolver scans all *.kdl files for matching section blocks. It is an error to have both peers.kdl and a peers { ... } section in another file.

Per-user cookie settings

Users can customize their experience via cookies set on the /settings page: