Server Configuration
Paddock is configured through CLI flags, environment variables, and a TOML config file, layered in a strict precedence order.
Precedence
Every setting can come from four places. Higher layers win:
- CLI flags
PADDOCK_*environment variablespaddock.toml- Built-in defaults
The config file is paddock.toml in the working directory, or a path given with --config <path> (short form -c). Unknown keys and malformed files are errors that stop startup. The startup banner shows where each value came from, and a commented reference file, paddock.example.toml, ships with the release.
CLI Arguments
| Flag | Description | Default |
|---|---|---|
--config, -c <PATH> | Path to TOML config file | paddock.toml (CWD) |
--host <ADDR> | Address to bind the HTTP API to | 127.0.0.1 |
--port <PORT> | Port to bind the HTTP API to | 11540 |
--model, -m <MODEL> | GGUF path or catalog model id to load and serve at startup. Unset = start with no model and serve /v1/models only. | - |
--model-dir <PATH> | Directory scanned for GGUF files (repeatable) | ~/paddock/models |
--device <DEV> | Compute device: cpu or cuda. GPU serving requires cuda; the cpu device runs reference paths for a subset of models. | cpu |
--kernel-pack <PATH> | Path to the CUDA kernel pack. Required with --device cuda. | - |
--max-ctx <N> | Max context length (KV cache) for the served model | 4096 |
--max-batch <N> | Continuous-batching width: sequences batched per step (1 = serial loop). Lower it on a tight card to free memory. | 16 |
--mmproj <PATH> | Vision tower GGUF (mmproj) for multimodal models; enables image input | - |
--mtp <PATH> | Separate MTP drafter GGUF for speculative decoding (used by Gemma 4) | - |
--max-output-tokens <N> | Default max output tokens per reply when a request does not specify one | 1024 |
--api-key <KEY> | Bearer key for API auth (see Authentication) | - |
Environment Variables
Every CLI flag has a corresponding environment variable, and three PDF settings exist only as environment variables or TOML keys:
| Variable | CLI Equivalent |
|---|---|
PADDOCK_HOST | --host |
PADDOCK_PORT | --port |
PADDOCK_MODEL | --model |
PADDOCK_MODEL_DIRS | --model-dir (comma-separated) |
PADDOCK_DEVICE | --device |
PADDOCK_KERNEL_PACK | --kernel-pack |
PADDOCK_MAX_CTX | --max-ctx |
PADDOCK_MAX_BATCH | --max-batch |
PADDOCK_MMPROJ | --mmproj |
PADDOCK_MTP | --mtp |
PADDOCK_MAX_OUTPUT_TOKENS | --max-output-tokens |
PADDOCK_API_KEY | --api-key |
PADDOCK_PDFIUM_LIB | - (path to the pdfium library; enables PDF input, unset = PDF attachments are rejected) |
PADDOCK_PDF_MAX_PAGES | - (pages rendered per PDF, default 20; extra pages are dropped and the response notes it) |
PADDOCK_PDF_PAGE_LONG_EDGE | - (long-edge pixels per rendered PDF page, default 1568) |
TOML keys use the flag names with underscores (host, model_dirs, kernel_pack, max_ctx, ...). The one exception: the --max-output-tokens flag is the max_tokens TOML key.
Example paddock.toml
host = "127.0.0.1"
port = 11540
model = "qwen3.6-27b"
model_dirs = ["~/paddock/models"]
device = "cuda"
kernel_pack = "pd-cuda-sm86.dll"
max_ctx = 16384
max_batch = 16Authentication
Bearer auth covers the /v1 and /api routes. The policy depends on how the server is bound:
| Bind | Key configured | Behavior |
|---|---|---|
| Loopback (default) | No | No auth required. |
| Loopback | Yes | The configured key is required. |
| Non-loopback | No | A key is auto-generated, required, and printed in the startup banner. |
| Non-loopback | Yes | The configured key is required. |
Clients send the key as a standard Bearer header:
curl http://192.168.1.10:11540/v1/models \
-H "Authorization: Bearer <your-key>"Other Environment Variables
| Variable | Description |
|---|---|
RUST_LOG | Log filter. Defaults to info,paddock=debug when unset. |
NO_COLOR | Disables ANSI color in the startup banner (also disabled automatically when stdout is not a terminal). |
PADDOCK_BS_CALIB | Encoder-model load calibration: off skips it, force ignores the cached verdict and re-measures. See Supported Models. |