Repository navigation
WebUI
tensor-router-webui is optional. It serves the management interface and connects to a router process.
When router.url is empty, the WebUI can start tensors-router from router.binary_path with router.config_path. It stops that managed process on exit when router.shutdown_with_webui is enabled.
When router.url is set, the router is external. Launch, restart, and kill controls are disabled because the WebUI does not own that process.
The management interface uses server.bind. Backend-native interfaces use the separate server.backend_ui_bind listener.
Do not assign both listeners the same address. Keeping them separate prevents management credentials and backend content from sharing an origin.
When certificate files are absent, the WebUI creates a self-signed certificate in server.state_dir. Generated certificates include localhost, loopback addresses, and local interface addresses for wildcard binds. Add browser-facing DNS names or external addresses to server.cert_hosts when they cannot be inferred.
Set server.backend_ui_public_url when NAT or a reverse proxy changes the browser-visible backend UI origin. It must be an HTTPS origin without credentials, path, query, or fragment.
Secure mode uses short-lived, single-use tickets when the browser crosses from the management origin to a backend UI origin. Router admin cookies and caller credentials are not forwarded to backend processes.
Secure non-loopback WebUI binds require server.admin_token.
Trusted-LAN mode skips WebUI login and CSRF authentication. Router cluster authentication, listener isolation, header filtering, CIDR checks, and resource limits remain active.
The WebUI and an external router validate their security profiles independently. A managed WebUI passes its effective profile to the child router.
The WebUIs tab can expose the native interface supplied by the selected backend. These interfaces can be used for backend tests or as the regular interactive frontend while requests continue through the router.
See Backend WebUI Interfaces for supported interfaces, configuration, enablement, model loading, cluster behavior, and access controls.
The Models tab requests a file inventory from configured models.file_roots. Inventory refreshes can hash configuration and model assets, so they are separate from the lightweight node inventory used by the Nodes tab.
Cooking can create a normal .kcpps file on one node or a split recipe on the master when selected components live on different nodes.
Portable export replaces local model paths with verified asset references for sharing. See KCPPS Sharing.
The Routing column opens the lending links of a model: "Image routing" for an image model and "LLM routing" for an LLM, and a model that is both shows both buttons. The dialog has two lists of models on the other nodes. Lends work to names the models that may take requests queued for this model. Borrows work from names the models whose queued requests this model may take. Each row has its own load if not loaded and reload what was displaced flags, which apply to whichever side of that link is the helper. The lists are unfiltered, because the models worth linking are usually the ones a name or hash filter would hide. Each candidate is labelled as the same weights or different weights, compared against the anchor by model hash, and linking a candidate with different weights for the first time requires an explicit acknowledgement. LLM candidates that cannot be linked are shown disabled with the reason. Clearing every row removes all links of the model. See Cluster Routing for what a link changes about scheduling.
The Nodes page lists, per node, the Held requests: requests of a linked model that the router is holding before passing them to a backend, with their lane, model, and how long they have waited, and requests currently lent to a helper, marked with the helper node and model. A request is marked queued while it waits for a free backend slot, and held only while the router is deliberately keeping it for a faster helper. Requests of models without links go straight to the backend and appear only under active requests.
The Separate column on each kobold or llama_sdcpp model opens its separate-runtime settings for that node. Toggling "Run in its own process" moves the config into the separate-runtime pool. The trigger groups (lanes, backend families, and named sibling configs) choose which loads on the shared runtime evict the pooled runtime; "Do not unload" means no trigger evicts it, though a full pool still unloads the least-recently-used one. The setting is stored per node in the model-state database and never rewrites the .kcpps.
The Analytics tab reports requests, tokens, generation speed, images, embedding vectors, audio, VRAM peaks and model loads for the selected period, nodes, models and section.
Token counts come from the backend report: the OpenAI usage object, llama.cpp timings (prompt tokens include the cached prefix) or the KoboldCpp and Ollama native counters. A streamed reply repeats those counters, and the last report wins. When a backend streams without any usage report, the request is recorded with no token counts rather than an estimate.
Generation speed is measured over the decode window, between the first and the last streamed content, so queue waiting, model loading and prompt evaluation stay out of the rate.
Router versions lists, per node, each router build that recorded events in the selected period, with when it was first and last seen. Events from builds that did not stamp a version appear as unknown. The router database also keeps every build that opened it in routerstore_binary_opens.
Vectors counts the embeddings a request returned. The count survives responses larger than the observed body limit, and so do the usage fields of such a response.
The Lending tab shows how owners lend queued work to linked helpers:
- Nodes: each node's build, whether it runs the master's lending settings, and its held and lent requests, plus the live leases.
- Settings: every lending setting with its default, config file and database value, and which one applies. Type a value and Save to store it in the database; Default removes a stored value. See Configuration for the priority order.
- Decision log: every node's lending decisions for the chosen window, lane and outcome. Repeats are folded into one row; select a row to see all of its variables.
The Load Captures tab appears when at least one selected node has analytics.load_capture_enabled. It can filter and merge attempt summaries across nodes, inspect sanitized KCPPS and asset identities, and fetch bounded stdout/stderr output incrementally. Reused loads link back to their physical attempt output.
Analytics keeps its newest events in memory until the flush interval elapses. Flush to disk on the Analytics tab writes them out at once, on this node and on every reachable slave. Download DB saves the router database of the selected node, or of every live node when All nodes is selected. The Errors tab has Clear all to delete every recorded load error on every node.
Capture rows are node-local. A node that disables capture remains absent from the viewer and does not receive capture storage writes.
See Cook Backend Options for the option catalog.
Documentation source: docs/wiki. Edit the source files in the main repository. Direct Wiki edits are overwritten by the next publication.