> For the complete documentation index, see [llms.txt](https://docs.cortensor.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortensor.network/technical-architecture/node/node-roles/router-node.md). # Router Node ### Purpose This page defines what the **Cortensor Router Node** is, what it can do today, what is working in MVP form versus still being iterated, and how it fits into higher-level product surfaces such as **Bardiel** and the emerging **Portal**. This is not only a description of a simple inference endpoint. The Router Node is increasingly the place where: * execution * validation * privacy * offchain data ownership * session routing * multi-session spreading * and agent-facing workflow primitives come together as usable API surfaces. *** ### 1. What the Router Node Is The Cortensor Router Node is the main **execution and coordination layer** between: * user-facing or product-facing requests, and * the underlying Cortensor network sessions, miners, validators, privacy/data flows, and offchain storage paths At a high level, the Router Node is responsible for translating raw network capacity into usable API surfaces. It is the layer that currently handles, or is evolving toward handling: * direct inference/completions * delegated execution * validation / grading / consensus * privacy-aware request preparation * offchain data flows and data ownership paths * request/session routing * multi-session spreading * product-facing surfaces for apps such as Bardiel and future Portal A useful one-paragraph summary is: > The Cortensor Router Node is the execution and coordination layer between user-facing or product-facing requests and the underlying Cortensor network sessions. It currently supports direct completions, delegated execution, consensus-aware validation, privacy-aware request handling, offchain storage/data-ownership flows, multi-session request spreading, and integration into higher-level product surfaces such as Bardiel and the emerging Portal. It is evolving from a simple inference entry point into a broader agentic execution, trust, privacy, and coordination surface. *** ### 2. Capability Status Labels When describing Router Node features, it is helpful to use a few consistent labels: * **Working / in MVP form** * **Working in rough form** * **Implemented but still being iterated** * **Planned / likely next** * **Not yet part of the current router path** These labels matter because the Router Node already does a lot today, but not every surface is equally mature. *** ### 3. Core API Surfaces ### 3.1 Direct Inference / Completions **Current state:** Working / MVP-to-rough form The Router Node supports direct completion/inference paths across: * v1 completions * v2 completions * v3 completions These are the simpler direct execution surfaces for standard inference requests. #### Current capabilities * accepts inference requests * routes requests into configured sessions * supports offchain / encryption-aware preparation where relevant * supports multi-session routing for completions * can sit behind a router pool or reverse-proxy path * acts as the backend execution layer under hosted/product surfaces #### Multi-session improvement The Router now supports a newer **env-based multi-session round-robin** path for completions. This means: * one completion endpoint can sit on top of multiple sessions * the Router can rotate requests across configured sessions * explicit caller-provided session selection can still win when supplied * v1/v2/v3 completion flows can share a cleaner session-spreading mechanism This is important because session spreading is now part of Router behavior instead of requiring users or apps to manually rotate session IDs. #### Current caveat * round-robin / session spreading is still fairly basic * this is not yet a full health-aware intelligent load balancer * it is best understood as a first multi-session distribution mechanism, not the final one *** ### 3.2 `/delegate` **Current state:** Working in rough-to-MVP form, still under active iteration `/delegate` is the Router’s **execution / delegation primitive**. It answers the question: > “Take this task and do it for me.” rather than: > “Just return one model completion.” #### Current conceptual modes **A. Planning mode** Used when the request is about how work should be structured rather than directly executed. Examples: * delegation plan * workflow design * routing strategy * validation plan * rollout plan * incident investigation plan * research plan * decision / recommendation framework **B. Execution mode** Used when the request is: > “Do the task and return the answer.” Examples: * summarize * extract * classify * rewrite * compare * risk review * checklist generation * incident triage * structured extraction * policy / decision support * long-text chunk / summarize / reduce * lightweight synthesis **C. Router-assisted execution** Used when the Router gathers some context first and then returns the final answer. Examples: * fetch one URL and summarize * fetch and extract facts * fetch and compare * fetch and research * read offchain content and explain / summarize * read safe onchain state and explain / summarize **D. Workflow / tool mode** If enabled, `/delegate` can use Router-side tools in a more orchestrated path. Current tool groups mentioned in the work so far include: * fetch/search helpers * JSON utilities * CSV parsing * calculator / text utilities * chunk / map-reduce helpers * validation helpers * offchain read/write * web3 read * reranking #### Version direction * v1 = earlier prompt-oriented execution primitive * v2 = structured objective/input/execution/policy contract * v3 = explicit redundancy and consensus-ready execution across multiple sessions * v4 = likely future direction for more programmable trust and reusable receipts/artifacts #### Strategic direction `/delegate` is treated as a core primitive because it represents: * execution outsourcing * specialization routing * agentic work assignment #### Current limitations * internal delegate logic still needed iterative refinement * not all delegate modes are equally mature * heavier-input and more varied tests were still being run * one future direction is making `/delegate` behave more like a mini-agent or subset of a PyClaw-style loop *** ### 3.3 `/validate` **Current state:** Working in rough-to-MVP form, with major consensus gaps filled `/validate` is the Router’s **validation / grading / consensus primitive**. It is meant to answer questions such as: * should this result be trusted? * how many validators agree? * what disagreement exists? * should we accept / retry / escalate? #### What `/validate` is today It is closer to: * redundant network validation * consensus-aware verdicting * explicit trust judgment rather than just a simple score. #### v3 model `/validate` v3 supports explicit redundancy: * 1 validator/session path * 3 validator/session path * 5 validator/session path The Router: * selects sessions * runs validation * aggregates outputs * returns a final answer plus consensus-style metadata #### Major improvement already made A major earlier gap was that the Router could return too early on the first committed result. That was improved in two parts: **Part 1 — wait for task end** * opt-in completion/wait mode was added so the Router can wait for the task to fully end * the Router can now pull fuller result sets instead of returning too early **Part 2 — consensus helper** * a Router-side consensus helper can now combine the available outputs into a final answer * rough logic includes majority-style or aggregated verdict behavior #### Dashboard support Because Router-side aggregated output is not always durably preserved in the same way as raw task outputs, the dashboards also recompute a similar consensus-style summary for `/delegate` and `/validate` for viewing and debugging purposes. #### Strategic direction `/validate` is treated as a core primitive because it represents: * network-native trust settlement * explicit multi-validator verification * decision-ready trust output for agent systems #### Current limitations * v3 still does not fully include an outcome loop / rework loop / evaluation event model * this is where a likely v4 direction may borrow from stronger outcome-style validation loops * current `/validate` is more of a consensus/judge primitive than a full “grader inside the work loop” system *** ### 3.4 `/factcheck` **Current state:** Planned / aligned with the same family as `/validate` `/factcheck` is repeatedly discussed as belonging to the same family/pattern as: * `/delegate` * `/validate` It likely follows the same v3-style redundancy/consensus path. It is not as deeply covered in current execution work as `/delegate` and `/validate`, but it is clearly part of the same direction. *** ### 3.5 Agent-Facing / Adapter Surfaces Beyond the core REST endpoints, the Router Node is also evolving into a broader product and agent-facing surface. #### Current or emerging adapter surfaces include: * REST endpoints * MCP server / MCP proxy layer * x402 / pay-per-call paths on selected endpoints * discovery / agent-card style surfaces for agent ecosystems * backend surfaces used by Bardiel and Portal These adapter layers matter because they make the Router more usable by: * apps * hosted products * agents * protocol-facing integrations rather than only by direct low-level callers. *** ### 4. Completion Paths and Session Routing Historically, the Router could: * accept explicit session selection * use fixed/default session logic That remains true, but session-routing capabilities are now expanding. ### 4.1 Single-session and explicit-session paths Single-session execution still exists and remains a valid path, especially when: * the caller explicitly provides a session * a product/backend layer already selected the session * the use case wants stable single-session behavior ### 4.2 Multi-session round-robin for completions Now implemented for completions: * one endpoint * multiple configured sessions * Router-side round-robin spreading * explicit session input can still override This is the main current session-spreading feature in the Router itself. ### 4.3 Router-pool path In productization / Portal V1 work, the Router increasingly sits behind: * Nginx / reverse proxy * router-pool grouping * API Gateway → router pool → router node request path This means: * Gateway owns product/business/session-selection logic * router pool owns healthy-router distribution * Router Node owns actual execution That separation is important and more precise than earlier rougher alternatives. *** ### 5. `/delegate` v3 and `/validate` v3 – Explicit Redundancy & Consensus The v3 evolution of `/delegate` and `/validate` is important enough to call out here directly. ### 5.1 What v3 changes v3 makes **redundancy and consensus explicit at the endpoint level**, rather than keeping them only as an internal session detail. For these endpoints, v3 supports: * `replicas = 1 / 3 / 5` * `session_pool` * `aggregation` strategy * `disagreement_policy` That means the Router can: * choose 1, 3, or 5 sessions * run the same logical task across those sessions * gather their responses * aggregate them into a final result plus consensus metadata ### 5.2 Why this matters For `/delegate`: * execution can now be spread across multiple sessions * the Router can compare outcomes rather than just trusting one path For `/validate`: * validation becomes a consensus-aware judgment rather than one score from one path For `factcheck`: * the same 1 / 3 / 5 pattern gives a cleaner trust story ### 5.3 Current v3 rough implementation shape A high-level v3 request concept includes: * `replicas` * `session_pool` * `aggregation` * `disagreement_policy` The Router must: 1. select the right sessions 2. fan out the same logical request 3. gather responses 4. produce a consensus result This is now part of the current Router direction, not just a future idea. *** ### 6. Privacy Feature 1.0 **Current state:** Working in MVP form Privacy Feature 1.0 is a major Router-adjacent capability. The Router is part of the path for: * session-scope privacy / encryption * task-scope privacy / encryption * key retrieval / privacy-aware flows * privacy-aware request handling #### Current supported forms * session-scope encryption * task-scope encryption #### Dedicated vs ephemeral Privacy Feature 1.0 works across: * dedicated nodes * ephemeral nodes #### Current caveat Task-scope privacy has more UX friction on dashboard/manual inspection flows because: * every task may require its own key retrieval/signing path But Router-side/backend support for task-level key retrieval exists. #### Practical significance This is one of the main reasons the Router is no longer “just an inference endpoint.” It is part of the privacy path itself. *** ### 7. Offchain Storage v3 and Data Ownership **Current state:** Working in MVP form Offchain Storage v3 is the current Router-side data-ownership / offchain-storage path. It supports: * router-managed offchain storage references * configurable offchain backends * offchain inputs and outputs * result URN handling * deferred-write support for ephemeral nodes ### 7.1 Dedicated-node path Dedicated-node offchain v3 flow works more directly because dedicated nodes can work with the configured storage path more cleanly. ### 7.2 Ephemeral-node path Ephemeral nodes should not receive broad storage credentials. So a deferred-write flow was introduced: 1. Router stores input offchain first 2. miner reads input 3. miner commits result URN 4. miner sends result content back to Router after commit 5. Router verifies assignment / auth / signature / precommit relationship 6. Router writes actual result object into offchain storage This closed a major data-management gap in rough/MVP form. #### Strategic significance This is why the Router is increasingly described as handling: * data privacy * data ownership via Router node * offchain result authority not just execution. *** ### 8. Session Routing, Traffic Spreading, and Execution Distribution The Router Node is increasingly responsible for request spreading and execution distribution. ### 8.1 Session-aware request distribution The Router today can already: * work with explicit session IDs * use default sessions * round-robin across configured completion sessions This is the beginning of Router-side job spreading. ### 8.2 Current limitation The current spreading path is still fairly simple: * it is not yet a sophisticated health-aware or SLA-aware global scheduler * it is primarily a session-spreading mechanism for completions ### 8.3 Future direction The clear design direction is toward smarter Router-side distribution: * better job distribution * better session awareness * more flexible spreading across session pools * richer quality/SLA-aware path selection A recurring conclusion in the work so far is: * miner-side sequential execution is acceptable because inference is expensive and hardware-limited * Router-side request distribution is where intelligence should improve over time *** ### 9. Router Role in Portal V1 **Current state:** Actively being productized In Portal V1, the Router Node becomes the backend execution layer underneath: * Portal web app * Portal API Gateway * router pools * managed dedicated-backed sessions #### Current V1 routing shape The current direction is: 1. user calls product-facing model alias 2. API Gateway chooses the session / backend route 3. request is forwarded into the router-pool path 4. router pool distributes to healthy router nodes 5. selected Router Node executes using the already-determined session path So the clean separation is: * Gateway owns product/business/session-selection logic * router pool owns healthy-router distribution * Router Node owns actual execution This is the important Portal role for the Router in V1. *** ### 10. Router Role in Bardiel and Other Product Surfaces Router Nodes already back: * Cortensor endpoints * Bardiel endpoints * v3 `/delegate` + `/validate` dataset generation * Bardiel dashboard views * ongoing heavier-input testing This means the Router is already functioning as: * shared execution layer * product backend * agent / trust surface backend The same Router primitives are expected to underpin: * Bardiel * Corgent * Portal * future agent-facing product surfaces *** ### 11. Observability, Request Logs, and Usage Tracking **Current state:** Working in rough form and actively being refined At the Router side and product side more broadly, current work already covers: * API key consumption visibility * request tracking * usage visibility * logging / request-log refinement * task lists in dashboards * status categories such as completed / processing / stale * consensus-style summary rendering for `/delegate` and `/validate` * quality and node performance views #### Still being refined * request visibility clarity * access logs * usage metering polish * per-request trace clarity * product-facing observability cleanliness The key point is that observability already exists in rough form and is now being shaped into something more product-usable. *** ### 12. Quality / SLA / Oracle Interaction These are not purely “Router Node features,” but they directly affect Router/session execution surfaces. Current quality-related direction includes: * real periodic task probes * actual user-style task checks * quality stats * quality rank tables * node performance integration * SLA-based filtering in node selection This matters because the Router/session path increasingly depends on: * better node quality selection * better request routing under variable node reliability * cleaner trust and SLA-aware product behavior In other words, the Router is where backend quality signals start becoming actual execution choices. *** ### 13. Model Support Through the Router The Router/session stack has already been extended to support newer model families, including: * Gemma 4 variants * Qwen 3.6 variants These models are being used for: * dedicated-node experiments * eventual ephemeral-node support * PyClaw iteration * tool-calling quality checks * future Portal product surfaces This matters because the Router is the layer where those models become actually usable through sessions and endpoints. *** ### 14. Router Node Today – What Is Solid vs What Is Still Rough ### 14.1 Solid / MVP Enough Today These are solid enough to describe as MVP-level capabilities: * v1 / v2 / v3 completion paths * multi-session round-robin for completions * Privacy Feature 1.0 * Offchain Storage v3 MVP * `/delegate` and `/validate` as usable v3 primitives * consensus helper + task-end wait behavior for validate * Router-backed Bardiel surfaces * Router role in Portal baseline path ### 14.2 Rough but Working / Actively Iterated These are working, but still actively being refined: * richer `/delegate` workflow / tool behavior * full `/validate` outcome-loop model * heavier product-side logging/accounting polish * more advanced Router-side job distribution * router-pool + API Gateway integration polish * large-scale performance / load behavior ### 14.3 Likely Next Near-term likely areas of iteration: * outcome-style validation loop on top of current `/validate` * smarter Router-side job distribution * more advanced multi-session and pool-level execution behavior * stronger Portal production path * more PyClaw-aligned Router behavior * further productization of agent-facing and trust-facing surfaces *** ### 15. One-Paragraph Summary The Cortensor Router Node is the execution and coordination layer between user-facing or product-facing requests and the underlying Cortensor network sessions. It currently supports direct completions, delegated execution, consensus-aware validation, privacy-aware request handling, offchain storage/data-ownership flows, multi-session request spreading, and integration into higher-level product surfaces such as Bardiel and the emerging Portal. It is evolving from a simple inference entry point into a broader agentic execution, trust, privacy, and coordination surface.