> 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cortensor.network/technical-architecture/node/node-roles/router-node.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.