Configuration

Configuration

The repository contains three canonical examples:

• config.example.yaml for tensors-router
• webui.example.yaml for tensor-router-webui
• downloader.example.yaml for tensor-router-downloader

The parsers reject unknown sections and fields. Relative paths are resolved from the directory containing the corresponding YAML file unless a field says otherwise. Durations use Go duration syntax such as 30s, 3m, or 168h.

Router configuration

Security and server

Field	Type or options	Example or default	Description
security.profile	String enum: secure, trusted_lan	secure	Selects authentication and network defaults.
server.bind	String host:port	127.0.0.1:8080	Router HTTP listener.
server.allowed_cidrs	List of CIDR strings	Loopback and RFC 1918 ranges	Limits accepted client addresses before authentication.

Authentication

Field	Type or options	Example or default	Description
auth.inference_keys	List of nonempty strings	[]	Bearer keys accepted by model inference APIs. Duplicates are rejected.
auth.admin_keys	List of nonempty strings	[]	Bearer keys accepted by management APIs. Duplicates are rejected.
auth.bearer_keys	List of nonempty strings	[]	Deprecated inference-key alias retained for existing configurations.

Models and assets

Field	Type or options	Example or default	Description
models.config_dir	Path string	./kcpps	Directory containing .kcpps files. It must exist when the router starts.
models.startup_model	String model ID	Empty	Model to load at startup. Empty leaves no requested startup model.
models.shared_dir	Path string	Empty	Shared asset destination. Empty uses cluster.store_dir/model-assets.
models.hash_workers	Integer, at least 1	1	Maximum concurrent workers used to hash model files.
models.concurrent_asset_transfers	Integer, at least 1	2	Maximum concurrent model asset transfers.
models.file_roots	List of nonempty path strings	./models in the example	Roots exposed to inventory, hashing, and portable asset resolution.

Backend selection

Field	Type or options	Example or default	Description
backend.mode	String enum: kobold, llama_sdcpp, vllm	kobold	Default backend family. A .kcpps backend_mode can override it per model.

MCP artifacts

Key	Type	Default	Meaning
mcp.enabled	Boolean	false	Enables materialization of MCP definitions stored in model configurations.
mcp.directory	Path string	./mcp	Artifact directory, resolved relative to this router configuration file.

MCP server definitions remain embedded in the .kcpps source. When active, the router writes a private, generated servers.json at <mcp.directory>/<config-stem>/servers.json. Disabling the global setting or a model's mcp_enabled removes that generated directory while retaining the embedded definition. Treat any configuration that contains mcp_servers as secret-bearing, including disabled definitions.

ffmpeg

Key	Type	Default	Meaning
ffmpeg.binary_path	Path string	""	ffmpeg binary to use. Empty resolves ffmpeg from PATH.
ffmpeg.scratch_dir	Path string	""	Directory holding finished ComfyUI-emulated videos until collected. Empty uses the system temporary directory.

Optional. Used to transcode ComfyUI-emulated video generation output into MP4 and to convert non-WAV transcription input on the buffered whisper request path. Probed once at startup; a missing or non-functional binary is logged and never fails startup, only the requests that need it.

Finished videos are written to <scratch_dir>/tensors-router-comfy-video, not held in memory. A job's output is capped at 2 GiB, the directory as a whole at 8 GiB, and an uploaded reference image at 32 MiB; jobs and uploads expire 24 hours after they are created, and at most 256 jobs are retained. Container deployments run with a read-only root and a small /tmp, so set scratch_dir to a path on the data volume there. See Deployment.

KoboldCpp process

Field	Type or options	Example or default	Description
kobold.backend_url	Loopback HTTP URL string	http://127.0.0.1:5001	Managed KoboldCpp endpoint.
kobold.embeddings_backend_url	Loopback HTTP URL string	http://127.0.0.1:0	Deprecated. Embeddings configs now join the separate-runtime pool on a router-allocated port; a value set here logs a deprecation warning.
kobold.binary_path	Path string	./bin/kobold/koboldcpp	KoboldCpp executable.
kobold.data_dir	Path string	./data	Working and data directory for the process.
kobold.multiuser	Integer, at least 1	1	Value supplied to KoboldCpp multiuser handling.
kobold.quiet	Boolean	true	Enables the managed quiet option.
kobold.skip_launcher	Boolean	true	Skips the native KoboldCpp launcher UI.
kobold.no_model	Boolean	true	Starts without a model so the router controls model loading.
kobold.hide_window	Boolean	true	Hides the child process window on supported platforms.
kobold.extra_args	List of strings	[]	Additional backend arguments. Managed host and port options cannot be overridden.

llama.cpp process

Field	Type or options	Example or default	Description
llama.backend_url	Loopback HTTP URL string	http://127.0.0.1:5002	Managed llama-server endpoint.
llama.embeddings_backend_url	Loopback HTTP URL string	http://127.0.0.1:0	Deprecated; see kobold.embeddings_backend_url.
llama.binary_path	Path string	./bin/llama/llama-server	llama-server executable.
llama.data_dir	Path string	./data/llama	Working and data directory for the text process.
llama.hide_window	Boolean	true	Hides the child process window on supported platforms.
llama.extra_args	List of strings	[]	Additional arguments. Managed host and port options cannot be overridden.

Every *_backend_url and *.embeddings_backend_url field above (plus sdcpp.backend_url and whispercpp.backend_url below) accepts three port forms: an explicit port pins the backend to that address; port 0 (the built-in default for both embeddings endpoints) lets the router allocate a free loopback port when the backend process starts, so it can never collide with another managed backend; and an omitted port is rejected at startup rather than silently falling back to a shared default. Two of these URLs resolving to the same host and port, including against server.bind, is also rejected at startup, naming both offending keys. A dynamically allocated endpoint is not addressable until the backend has started at least once.

stable-diffusion.cpp process

Field	Type or options	Example or default	Description
sdcpp.backend_url	Loopback HTTP URL string	http://127.0.0.1:7860	Managed sd-server endpoint.
sdcpp.binary_path	Path string	./bin/stable-diffusion/build/bin/sd-server	sd-server executable.
sdcpp.data_dir	Path string	./data/sdcpp	Working and data directory for the image process.
sdcpp.hide_window	Boolean	true	Hides the child process window on supported platforms.
sdcpp.extra_args	List of strings	[]	Additional arguments. Managed listen address and port options cannot be overridden.

whisper.cpp process

Field	Type or options	Example or default	Description
whispercpp.backend_url	Loopback HTTP URL string	http://127.0.0.1:5003	Managed whisper-server endpoint.
whispercpp.binary_path	Path string	./bin/whisper/whisper-server	whisper-server executable.
whispercpp.data_dir	Path string	./data/whispercpp	Working directory and location of whisper-server.log.
whispercpp.hide_window	Boolean	true	Hides the child process window on supported platforms.
whispercpp.extra_args	List of strings	[]	Additional arguments. Router-owned bind, public path, inference path, conversion, and temporary-directory flags are rejected.

vLLM companion

Field	Type or options	Example or default	Description
vllm.binary_location	Empty or executable path	Empty	Companion executable. Empty searches beside the router executable on supported platforms.
vllm.data_dir	Path string	./data/vllm	Persistent jobs, content-addressed environments, staging, bounded logs, and private runtime sockets.
vllm.profile	auto or signed profile ID	auto	Runtime profile requested by explicit initialization.
vllm.manifest_path	TUF target path, local file path, or empty	platform-specific	Signed runtime-manifest target inside the configured TUF repository. With tuf_repository_url empty it is a local file authorized by the pin below. Ignored when neither a repository nor a pin is configured.
vllm.tuf_repository_url	HTTPS URL ending in /metadata, or empty	Built-in project metadata repository	Metadata endpoint authorizing runtime manifests and their exact artifacts. Empty selects the operator-pinned or unverified tier instead.
vllm.tuf_root_path	Empty or file path	Empty	Optional trusted root override. Empty uses the root embedded in the companion.
vllm.manifest_sha256	Empty or 64-character hex digest	Empty	Authorizes a local manifest_path. Required with manifest_size when tuf_repository_url is empty and allow_unverified_install is false. Rejected alongside a TUF repository.
vllm.manifest_size	0 or positive byte count	0	Exact byte length of the operator-pinned manifest. Paired with manifest_sha256.
vllm.allow_unverified_install	Boolean	false	Installs vLLM from PyPI with no manifest and no digest pinning when no authorized manifest resolves. A real reduction in supply-chain integrity; reports the unverified trust tier in state, logs, and the WebUI.
vllm.unverified_vllm_version	Empty or exact version	Empty	Pins vllm==<version> for an unverified install. Empty installs whatever resolves as latest, which is unpinned even by version. Only valid with allow_unverified_install.
vllm.unverified_python_version	Empty or version request	Empty (3.12)	Interpreter uv provisions for the unverified environment. A request such as 3.12 resolves to a specific patch release.
vllm.unverified_index_url	Empty or HTTPS URL	Empty	Replaces the default package index for an unverified install.
vllm.unverified_extra_index_url	Empty or HTTPS URL	Empty	Additional index, most commonly an accelerator-specific torch wheel index. Left on uv's default index strategy, so a named index is preferred rather than silently outranked.
vllm.oci_run_as_image_user	Boolean	false	Runs an OCI runtime as the image's own user instead of the host user, for vendor images that install their interpreter under /root. Drops only that mapping; the read-only root filesystem, dropped capabilities, and no-new-privileges still apply.
vllm.dynamic_lora_enabled	Boolean	false	Separately enables administrator-only dynamic LoRA operations.
vllm.eep_enabled	Boolean	false	Separately enables administrator-only Elastic Expert Parallelism operations.
vllm.trust_remote_code	Boolean	false	Allows a model configuration to opt into remote repository code. Model-level consent is also required.
vllm.external_tools	Boolean	false	Allows a model configuration to opt into external tool servers. Model-level configuration is also required.

Runtime installation occurs only after an authenticated initialization request. Router startup and model loading never initialize, download, or install a vLLM environment. See vLLM for model configuration and security boundaries.

Logging

Field	Type or options	Example or default	Description
logging.mode	String enum: normal, startup_only, quiet	normal	Controls router log output.
logging.backend_logs_to_disk	Boolean	false	Writes managed backend output to files instead of retaining startup output only.
logging.enabled	Boolean	true	Deprecated compatibility field mapped to a logging mode.

Backend updates

When updates are enabled, each selected backend needs either a direct binary URL or a repository URL. All configured URLs must use HTTPS. A SHA-256 value is optional, but when present it must contain exactly 64 hexadecimal characters.

Field	Type or options	Example or default	Description
updates.enabled	Boolean	false	Enables periodic backend binary checks and replacement.
updates.check_interval	Positive duration string	168h	Time between update checks.
updates.include_prereleases	Boolean	false	Allows prerelease GitHub releases when repository resolution is used.
updates.tuf_repository_url	HTTPS URL ending in /metadata	Built-in project metadata repository	TUF metadata endpoint used to authorize repository releases. Credentials, queries, and fragments are rejected.
updates.tuf_root_path	Empty or file path	Empty	Optional trusted TUF root override. Empty uses the root embedded in the router.
updates.binary_url	Empty or HTTPS URL string	Empty	Direct KoboldCpp binary source. A direct source always requires updates.binary_sha256.
updates.binary_sha256	Empty or 64-character SHA-256 string	Empty	Expected digest for a direct KoboldCpp download.
updates.binary_repository_url	Empty or HTTPS repository URL string	https://github.com/LostRuins/koboldcpp	KoboldCpp release repository source authorized by TUF metadata.
updates.binary_asset_glob	String glob	Empty	Selects a KoboldCpp release asset.
updates.llama_binary_url	Empty or HTTPS URL string	Empty	Direct llama.cpp binary source.
updates.llama_binary_sha256	Empty or 64-character SHA-256 string	Empty	Expected digest for a direct llama.cpp download.
updates.llama_repository_url	Empty or HTTPS repository URL string	https://github.com/ggml-org/llama.cpp	llama.cpp release repository source.
updates.llama_asset_glob	String glob	Empty	Selects a llama.cpp release asset.
updates.sdcpp_binary_url	Empty or HTTPS URL string	Empty	Direct stable-diffusion.cpp binary source.
updates.sdcpp_binary_sha256	Empty or 64-character SHA-256 string	Empty	Expected digest for a direct stable-diffusion.cpp download.
updates.sdcpp_repository_url	Empty or HTTPS repository URL string	https://github.com/leejet/stable-diffusion.cpp	stable-diffusion.cpp release repository source.
updates.sdcpp_asset_glob	String glob	Empty	Selects a stable-diffusion.cpp release asset.
updates.whispercpp_binary_url	Empty or HTTPS URL string	Empty	Direct whisper.cpp executable or archive source.
updates.whispercpp_binary_sha256	Empty or 64-character SHA-256 string	Empty	Expected digest for a direct whisper.cpp download.
updates.whispercpp_repository_url	Empty or HTTPS repository URL string	https://github.com/ggml-org/whisper.cpp	whisper.cpp release repository source.
updates.whispercpp_asset_glob	String glob	Empty	Selects an official whisper.cpp release asset.

Downloader companion

Field	Type or options	Example or default	Description
downloader.enabled	Boolean	true	Enables router-owned downloader initialization and capability reporting.
downloader.binary_location	Path string	Empty	Downloader executable. Empty searches beside the router executable.
downloader.config_path	Path string	Empty	Downloader configuration. Empty uses downloader.yaml beside the router configuration; a missing file means defaults.

Cluster

Field	Type or options	Example or default	Description
cluster.role	String enum: standalone, master, slave	standalone	Selects the node's routing role.
cluster.node_id	Nonempty string	local	Stable node identity. It must be unique in a cluster.
cluster.public_url	Empty or absolute URL string	Empty	Reachable URL advertised by a slave. Required for a slave. A master may leave it empty and still serve asset transfers, because a slave falls back to its own cluster.master_url.
cluster.master_url	Empty or absolute URL string	Empty	Master URL used by a slave. Required for a slave.
cluster.slave_urls	List of absolute URL strings	[]	Slave URLs permitted and polled by a master.
cluster.token	String	Empty	Shared cluster credential. Required for master and slave roles and rejected when it is a placeholder.
cluster.store_dir	Path string	./router-store	Stores registry, asset index, recipes, benchmarks, and the router database.
cluster.database_path	Path string	Empty	SQLite path holding analytics, load captures, load errors, and routing links. Empty uses cluster.store_dir/analytics.sqlite. Model assets and model state keep their own files and cannot be named here.
cluster.sync_interval	Positive duration string	60s	Interval between slave registry synchronization attempts.
cluster.health_interval	Positive duration string	15s	Interval between cluster health checks.
cluster.control_timeout	Positive duration string	30s	Total deadline for buffered cluster control requests and responses. Model load and unload are exempt: their remote work can include a peer asset transfer, so they follow the receiving node model operation deadline instead.
cluster.sync_concurrency	Integer, 1–128	4	Maximum number of slave health snapshots fetched concurrently.

Analytics

Field	Type or options	Example or default	Description
cluster.scheduling_refresh_interval	Positive duration string	60s	How often the master refits node costs and reconsiders offload leases when no queue event arrives in between. Every queue event of a linked model also triggers a decision.
cluster.scheduling_sample_window	Positive duration string	24h	History window used to fit request duration. Must stay inside analytics.raw_retention.
cluster.scheduling_min_samples	Integer, at least 2	20	Measured requests a model needs for its own cost fit. A helper below this is priced with its owner's fit until it has one.
cluster.scheduling_backend_depth	Integer, at least 1	2	Requests admitted to the backend at once on a linked model. One running plus one queued keeps the backend busy while the rest stay lendable.
cluster.scheduling_grant_ttl	Positive duration string	30s	Lifetime of an offload lease. A lease that is not renewed expires on its own.
cluster.offload_probe_idle	Positive duration string	5s	How long a helper must be idle from its own work (its own requests and its own model loads; borrowed work does not count) before it gets a one-request probe even when the cost rule would not lend to it.
cluster.scheduling_context_reserve	Integer, at least 0	256	Tokens kept free for the answer when a text request states no limit.
cluster.offload_restore_delay	Positive duration string	1.5s	Idle time before a helper reloads the model it held before borrowing, when the link asks for it.
cluster.offload_lent_stall_timeout	Positive duration string	3m	How long a helper may show no change in the requests lent to it, and report no borrowed work running, before they are all taken back by their owners.
cluster.offload_faster_helper_slots	Integer, 1–64	2	Requests lent at once to a helper predicted to be at least as fast as the owner.
cluster.offload_slower_helper_slots	Integer, 1–64	1	Requests lent at once to a helper that pays off but is slower than the owner.
cluster.offload_probe_helper_slots	Integer, 1–64	1	Requests lent at once while probing an unpriced pair.
cluster.offload_hold_for_faster_helper	Boolean	true	When the owner would queue a waiting request behind the one it is generating, keep it for the busy helper if the helper is predicted to finish it sooner.
cluster.offload_decisions_retention	Positive duration string	720h	How long lending decisions are kept.

The scheduling_* and offload_* settings are layered. From lowest to highest priority: the built-in default, the config file, and a value saved in the WebUI Lending tab, which is stored in the router database. Default on a row removes the saved value, so the config file value or the default applies again. Every change applies at once, without a restart. A slave runs exactly the values its master resolved: the master pushes them on every refresh and after every change. | analytics.enabled | Boolean | false | Enables persisted request and runtime analytics. | | analytics.vram_enabled | Boolean | true | Enables VRAM sampling when analytics is active. | | analytics.load_capture_enabled | Boolean | false | Independently records backend load attempts and reuse metadata on each enabled node. | | analytics.load_capture_database_path | Path string | Empty | Deprecated. Names a capture database written before the databases were joined so its rows can be imported once. Set it only while that file still exists. | | analytics.load_capture_max_output_mb | Positive integer | 64 | Per-physical-load RAM cap for captured stdout and stderr. Overflow is marked and backend loading continues. | | analytics.flush_interval | Positive duration string | 3m | Interval between analytics aggregation flushes. | | analytics.database_path | Path string | Empty | Deprecated. Names an analytics database written before the databases were joined so its rows can be imported once. Set it only while that file still exists. | | analytics.raw_retention | Positive duration string | 720h | Retention period for raw analytics samples. | | analytics.vram_sample_interval | Positive duration string | 1s | Interval between VRAM samples. | | diagnostics.enabled | Boolean | true | Records failures seen before or during a backend load that are otherwise only logged. On by default so this signal survives on nodes where analytics is off. | | diagnostics.database_path | Path string | Empty | Deprecated. Names a diagnostics database written before the databases were joined so its rows can be imported once. Set it only while that file still exists. | | diagnostics.retention | Positive duration string | 720h | Age after which a load-error row is pruned on the next write. Required when diagnostics.enabled is true. | | diagnostics.max_output_kb | Positive integer, KiB | 64 | Per-row cap for captured backend output. Overflow keeps the newest bytes and is marked truncated. Required when diagnostics.enabled is true. |

One router database

Analytics, load captures, load errors, and routing links share a single SQLite file at cluster.database_path. Model assets (model-assets.sqlite) and model state (model-state.sqlite) stay in their own files, and the standalone downloader keeps its own database.

The schema is created whatever the feature flags say, so a node with analytics off still carries an empty analytics table. A flag decides whether the router writes, never whether the table exists.

On the first start after upgrading, the router imports each database it used to keep separately and renames the original to <name>.migrated, along with its -wal and -shm files. It looks in two places per subsystem: the path the deprecated key names, and the old default under cluster.store_dir. The import is recorded inside the same transaction that copies the rows, so a second start does nothing even if the rename failed. A source that cannot be read is left untouched and reported as a startup warning; the rest of the import continues and the router starts.

Analytics rollups covering the same bucket add their counters and keep the higher VRAM peak, so two files describing the same traffic still merge into one history rather than one overwriting the other.

To go back to an older router, stop the router and rename the .migrated files back. The merged file keeps the extra tables; an older binary ignores them.

The analytics tab has a Flush to disk button. It writes the in-memory event buffer out and folds the write-ahead log back into the database file, on this node and, from a master, on every reachable slave.

Load captures are opt-in and independent from request analytics, VRAM analytics, and backend disk logging. Records are retained permanently until an operator removes the database. The capture database, WAL, and SHM files are owner-restricted; size grows with load attempts and reuse records.

The analytics tab has a Download DB button. It saves the router database of the selected node, or one file per live node when All nodes is selected, so a master and its slaves can be inspected offline with any SQLite tool.

The diagnostics load-error store is separate again: identical rows are deduplicated by a phase, source, and normalized-message fingerprint, so a flapping backend rolls up into one row with an occurrence count rather than flooding the file. Rows carry the redacted message plus any captured child-process output. The /router/v1/site/load-errors endpoint and the WebUI Errors panel read it; a master fans out to every node and merges the results. Each row names the model and config that failed to load. Clear all on the Errors panel deletes every row on every reachable node after a confirmation.

Request and memory limits

All size fields are positive integers. Replay and selector scan limits cannot exceed the maximum stream request size. The memory budget must cover twice the replay buffer plus the router's transformation working set.

Field	Type or options	Example or default	Description
limits.max_control_body_mb	Positive integer, MiB	8	Maximum buffered control request body.
limits.replay_buffer_mb	Positive integer, MiB	64	Maximum body retained for replay while selecting or retrying a backend.
limits.memory_budget_mb	Positive integer, MiB	2048	Total router budget for bounded in-memory request processing.
limits.max_stream_request_gb	Positive integer, GiB	32	Maximum streamed request body.
limits.max_stream_response_gb	Positive integer, GiB	32	Maximum streamed backend response.
limits.selector_scan_mb	Positive integer, MiB	64	Maximum prefix scanned to locate a model selector.
limits.separate_runtimes	Integer ≥ 1	5	Maximum co-resident separate backend processes per node. At the cap the least-recently-used one is unloaded. See Separate runtimes.
limits.drain_timeout	Positive duration string	15m	Maximum graceful drain time during unload, restart, or shutdown.

WebUI configuration

Security and listeners

Field	Type or options	Example or default	Description
security.profile	String enum: secure, trusted_lan	secure	Selects WebUI authentication behavior.
server.bind	String host:port	127.0.0.1:8443	HTTPS management listener.
server.backend_ui_bind	String host:port	127.0.0.1:8444	Separate listener for proxied backend interfaces. It must differ from server.bind.
server.backend_ui_public_url	Empty or HTTPS origin string	Empty	Browser-visible backend UI origin for NAT or reverse proxy use. Credentials, path, query, and fragment are rejected.
server.state_dir	Path string	./webui-state	Stores generated certificates and WebUI state.
server.cert_file	Path string	Empty	TLS certificate file. Empty uses a generated certificate.
server.key_file	Path string	Empty	TLS private-key file. It must be configured with cert_file.
server.cert_hosts	List of host or IP strings	[]	Extra names and addresses added to a generated certificate.
server.admin_token	String	Empty	WebUI login credential. Required for a secure non-loopback bind and rejected when it is a placeholder.

See Backend WebUI Interfaces for listener setup, external origins, enablement, and browser access.

Router process

Field	Type or options	Example or default	Description
router.url	Empty or HTTP/HTTPS URL string	Empty	External router URL. Empty enables managed-process mode.
router.token	String	Empty	Bearer token sent to the router management API.
router.binary_path	Path string	./tensors-router	Router executable used in managed mode.
router.config_path	Path string	./config.yaml	Router YAML passed to a managed process.
router.start_when_missing	Boolean	true	Starts the managed router when no process is available.
router.shutdown_with_webui	Boolean	true	Stops the managed router during WebUI shutdown.
router.args	List of strings	[]	Extra router arguments. They cannot override the managed security profile.

Logging

Field	Type or options	Example or default	Description
logging.mode	String enum: normal, startup_only, quiet	normal	Controls WebUI process logs.
logging.enabled	Boolean	true	Deprecated compatibility field mapped to a logging mode.

Downloader configuration

Storage and Hugging Face

Field	Type or options	Example or default	Description
storage.root	Required path string	./models	Destination root for downloaded repositories and files.
storage.state_dir	Required path string	./downloader-state	Stores downloader state and temporary download staging before verified promotion to storage.root.
storage.database_path	Required path string inside state_dir	./downloader-state/downloads.sqlite	SQLite job and artifact database.
storage.free_space_reserve_gb	Integer, at least 0, GiB	5	Space that download planning must leave unused.
huggingface.token	String	Empty	Optional token for private or gated Hugging Face repositories. Empty falls back to HF_TOKEN or HUGGING_FACE_HUB_TOKEN.
huggingface.endpoint	https URL	Empty (https://huggingface.co)	Hub or mirror base URL. Empty falls back to HF_ENDPOINT. Plain http is accepted only for loopback mirrors.

Jobs and scanning

Field	Type or options	Example or default	Description
downloads.concurrent_jobs	Integer, at least 1	2	Maximum download jobs executed together.
downloads.concurrent_files	Integer, at least 1	4	Maximum files of one job downloaded together.
downloads.retry_limit	Integer, at least 0	8	Consecutive failed attempts without new bytes before a file transfer gives up.
downloads.timeout	Positive duration string	30s	Limit for Hub API requests and for waiting on a file response to start.
downloads.stall_timeout	Positive duration string	60s	A file transfer that receives no data for this long is abandoned and resumed.
scanning.hash_workers	Integer, at least 1	1	Maximum workers used while hashing local artifacts.
scanning.write_hash_sidecars	Boolean	true	Writes hash sidecar files beside indexed artifacts.

Hardware estimates and logging

Field	Type or options	Example or default	Description
hardware.default_context	Integer, at least 1	8192	Context length used by download planning estimates when model metadata does not supply one.
hardware.vram_reserve_mb	Integer, at least 0, MiB	1024	VRAM reserved from model-fit estimates.
hardware.safety_margin_percent	Integer from 0 through 99	15	Additional margin applied to hardware-fit estimates.
logging.mode	String enum: normal, startup_only, off	normal	Controls downloader logs. The log file path is derived from the downloader configuration location.

Precedence

The router and WebUI security profiles use this order:

1. Command-line option
2. TENSORS_ROUTER_SECURITY_PROFILE
3. Configuration file
4. Secure default

Other command-line and environment overrides are resolved by the corresponding executable before validation.

Credential environment inputs

Credential values can come from configuration or the environment. Each environment role accepts either the direct value or the corresponding _FILE path, never both. Secret files must be regular files containing one nonempty credential. Environment credentials replace the configured value for that role before validation.

Role	Direct value	File path
Router inference	TENSORS_ROUTER_INFERENCE_TOKEN	TENSORS_ROUTER_INFERENCE_TOKEN_FILE
Router administration	TENSORS_ROUTER_ADMIN_TOKEN	TENSORS_ROUTER_ADMIN_TOKEN_FILE
Cluster control	TENSORS_ROUTER_CLUSTER_TOKEN	TENSORS_ROUTER_CLUSTER_TOKEN_FILE
WebUI administration	TENSORS_ROUTER_WEBUI_ADMIN_TOKEN	TENSORS_ROUTER_WEBUI_ADMIN_TOKEN_FILE
WebUI-to-router management	TENSORS_ROUTER_MANAGED_ROUTER_TOKEN	TENSORS_ROUTER_MANAGED_ROUTER_TOKEN_FILE

TENSORS_ROUTER_WEBUI_TOKEN and TENSOR_ROUTER_WEBUI_TOKEN remain direct-value compatibility aliases for WebUI administration. A credential reused by inference, router administration, cluster control, or WebUI administration is rejected. The WebUI-to-router token must match an administrator credential accepted by that router, because those are the same security role across the two processes.