CLI

Paddock has two binaries: paddock, the server that serves the APIs and the Studio until stopped, and paddock-cli, a small admin and tools client.

The paddock Server

Everything is settable three ways with a fixed precedence: CLI flags override PADDOCK_* environment variables, which override paddock.toml, which overrides the built-in defaults. A paddock.toml in the working directory is picked up automatically, or point at one with --config.

# serve a model on CPU with the defaults (http://127.0.0.1:11540)
paddock --model ~/paddock/models/your-model.gguf

# serve on CUDA with a kernel pack and a larger context
paddock --model ~/paddock/models/your-model.gguf \
  --device cuda --kernel-pack pd-cuda-sm120.so \
  --max-ctx 16384

# run from a config file
paddock --config ./paddock.toml

Flags

Flag	Environment	Description	Default
`-c, --config <PATH>`	-	Config file to load	`./paddock.toml` if present
`--host <IP>`	`PADDOCK_HOST`	Address to bind the HTTP API to	`127.0.0.1`
`--port <PORT>`	`PADDOCK_PORT`	Port to bind the HTTP API to	`11540`
`-m, --model <PATH>`	`PADDOCK_MODEL`	GGUF model to load and serve at startup	none
`--model-dir <PATH>`	`PADDOCK_MODEL_DIRS`	Directory to scan for GGUF models (flag is repeatable; the env var is comma-separated)	`~/paddock/models`
`--device <DEVICE>`	`PADDOCK_DEVICE`	Compute device: `cpu` or `cuda`	`cpu`
`--kernel-pack <PATH>`	`PADDOCK_KERNEL_PACK`	Kernel pack path, required for `--device cuda`	none
`--max-ctx <N>`	`PADDOCK_MAX_CTX`	Max context length (KV cache) for the served model	`4096`
`--max-batch <N>`	`PADDOCK_MAX_BATCH`	Continuous-batching width: concurrent sequences per step (1 = serial loop)	`16`
`--mmproj <PATH>`	`PADDOCK_MMPROJ`	Vision tower GGUF (mmproj) enabling image input	none
`--mtp <PATH>`	`PADDOCK_MTP`	MTP drafter GGUF for speculative decoding	none
`--max-output-tokens <N>`	`PADDOCK_MAX_OUTPUT_TOKENS`	Default max output tokens per reply when a request does not specify one	none
`--api-key <KEY>`	`PADDOCK_API_KEY`	API key required for Bearer auth	none

Three PDF settings exist only as config-file keys or environment variables, not flags: pdfium_lib (PADDOCK_PDFIUM_LIB) points at the pdfium shared library and enables server-side PDF rasterization for the vision path, pdf_max_pages (PADDOCK_PDF_MAX_PAGES, default 20) caps pages rendered per document, and pdf_page_long_edge (PADDOCK_PDF_PAGE_LONG_EDGE, default 1568) sets the target long edge in pixels for each rendered page.

paddock.toml

The config file uses the same names as the flags, with model_dirs as a list and max_tokens for the output-token default. Unknown keys and malformed files are errors that stop startup.

host = "127.0.0.1"
port = 11540
model = "~/paddock/models/your-model.gguf"
model_dirs = ["~/paddock/models"]
device = "cuda"
kernel_pack = "pd-cuda-sm120.so"
max_ctx = 16384
max_batch = 16

Authentication

No key, loopback bind (the default). No auth. Local-only trust on your own machine.
No key, non-loopback bind. The server auto-generates a key, prints it in the startup banner, and requires it. Exposing the server to the network is exactly when auth must switch on.
Explicit key. Required on every request.

When auth is on, clients send Authorization: Bearer <key> on /v1 and /api paths.

Startup Banner and Logs

The banner prints the resolved configuration after the socket binds, tagging each value that came from an environment variable or a flag so you can see where every setting originated. Log filtering follows the standard RUST_LOG environment variable; the default is info with debug-level logging for Paddock's own crates. The banner respects NO_COLOR and drops color when output is piped.

paddock-cli

Commands that produce data take a --json flag for machine-readable output.

model inspect

Reads a GGUF file and prints its model card: file size and GGUF version, architecture, trained context length, geometry (blocks, embedding width, attention and KV heads, sliding window), expert counts for MoE models, tokenizer and whether a chat template is embedded, tensor count, and the quantization mix with per-type sizes. Sizes that cannot be verified are reported as unknown instead of estimated.

# human-readable card
paddock-cli model inspect ~/paddock/models/your-model.gguf

# full report as JSON
paddock-cli model inspect ~/paddock/models/your-model.gguf --json

For the benchmark harness that ships in the same workspace, see Benchmarking.