CLI

Paddock ships two programs. paddock is the manager: it runs the Studio, owns the catalog and downloads, and supervises model servers. paddock-runner is one model server, and it is what actually holds a model on the GPU.

You can drive everything from the manager and never invoke a runner by hand. You can also run a runner on its own with no manager at all, which is what the config file it leaves behind is for.

paddock

Running paddock with no verb starts the manager and the Studio on http://127.0.0.1:11500. Model servers get their own ports, allocated upward from 11540.

# start the manager and the Studio
paddock

# download a catalog model, hash-verified
paddock pull qwen3.6-27b

# start an endpoint for it and wait until it is healthy
paddock serve qwen3.6-27b

# what is running
paddock ps

Verbs

Manager Flags

serve takes the spawn's shape as flags of its own: --port, --max-ctx, --max-batch, --gpu to pin the runner to one card, --artifact to pick a weights variant such as q4, --pin, and --fp8-native.

paddock-runner

One runner serves one model. Everything is settable three ways with a fixed precedence: CLI flags override PADDOCK_* environment variables, which override the config file, which overrides the built-in defaults.

# serve a model directly
paddock-runner --model ~/paddock/models/your-model.gguf \
  --device cuda --kernel-pack pd-cuda-sm120.so \
  --max-ctx 16384

# run the config file the manager wrote
paddock-runner --config ~/paddock/servers/11540.toml

# hand that endpoint to the OS so it starts at boot
paddock-runner service install --config ~/paddock/servers/11540.toml

service install registers a native Windows service or a systemd unit, and service uninstall removes it. No manager process is involved. See Running as a Service.

Flags

Exposed Deployments

These matter when a runner is reachable from more than your own machine.

Two PDF settings exist only as config-file keys or environment variables, not flags: 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. The renderer itself is built into the binary and needs no configuring.

The Config File

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. paddock serve writes one of these per endpoint at ~/paddock/servers/<port>.toml, and the file is yours to keep, hand-edit, or run without the manager.

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

• A caller on loopback. Never needs a key, whatever the server is bound to.
• A caller over the network, no key configured. The server generates one at startup, prints it in the banner, and requires it. This is the default, because the default bind serves the network.
• 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.

Inspecting A Model File

paddock 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 inspect ~/paddock/models/your-model.gguf

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

To measure a served endpoint rather than inspect a file, see Benchmarking.