Router Node Setup

Last updated: 2026-06-28

A router node is the API-facing coordinator for Cortensor work. It accepts completions, delegate, validate, factcheck, MCP/A2A, trial, x402, privacy, and off-chain payload flows depending on configuration.

Router Startup

cortensord ~/.cortensor/.env routerv1

The router reads the environment file, initializes chain and contract clients, starts REST routes, publishes router metadata, and optionally starts MCP/A2A/payment/privacy surfaces.

Quick Path

1. Prepare the router .env with API enablement, REST bind settings, public metadata, chain/RPC values, and miner-facing WebSocket settings.
2. Configure active session IDs for completions, delegate, validate, factcheck, MCP, and any v3 replica pools you plan to expose.
3. Decide which access modes are enabled: bearer key, trial routes, x402, MCP, A2A, privacy, and off-chain storage.
4. Start routerv1, verify health routes, then smoke-test one enabled route family at a time.
5. Put the router behind TLS/reverse proxy before exposing public endpoints.

Router Flow

flowchart TB
  Caller["Application / gateway / agent"] --> Rest["Router REST API"]
  Rest --> Auth{"Auth / trial / x402"}
  Auth --> Sessions["Session selection"]
  Sessions --> Queue["Session queue"]
  Queue --> Miners["Miner nodes"]
  Miners --> Queue
  Queue --> Validators["Oracle / validator"]
  Rest --> Offchain["Off-chain storage"]
  Rest --> Privacy["Privacy policy"]
  Rest --> Response["Result / verdict / task status"]

Core Environment

# Enable REST API
API_ENABLE=1
API_KEY=
API_PORT=5010

# REST bind
ROUTER_REST_BIND_IP=0.0.0.0
ROUTER_REST_BIND_PORT=5010

# Public router metadata
ROUTER_EXTERNAL_DOMAIN=
ROUTER_EXTERNAL_IP=
ROUTER_EXTERNAL_PORT=443

# Miner-facing WebSocket
WS_HOST_ROUTER=0.0.0.0
WS_PORT_ROUTER=15210

Generate a router API key with the packaged tool command when the release includes it:

cortensord ~/.cortensor/.env tool gen-api-key

Before starting a public router, set API_KEY to a long random value and set ROUTER_EXTERNAL_DOMAIN / ROUTER_EXTERNAL_IP to the public hostname or address used by clients and miners.

Router metadata uses this shape:

rest_endpoint:rest_port;ws_host:ws_port

Use the reverse-proxy hostname and public ports in metadata when the router is behind Nginx or another load balancer.

Session Configuration

Router features need active session IDs. Each production environment provides its own session table.

Feature	Common environment
MCP default session	ROUTER_MCP_DEFAULT_SESSION_ID
MCP completion	ROUTER_MCP_COMPLETION_SESSION_ID
MCP delegate	ROUTER_MCP_DELEGATE_SESSION_ID
MCP validate	ROUTER_MCP_VALIDATE_SESSION_ID
MCP task reads	ROUTER_MCP_TASKS_SESSION_ID
Delegate v3 pool	ROUTER_V3_DELEGATE_SESSION_IDS_1, _3, _5
Validate v3 pool	ROUTER_V3_VALIDATE_SESSION_IDS_1, _3, _5

The v3 delegate and validate routes use replica counts to select predefined v2 session pools. For example, a replicas=3 request uses the configured three-session pool.

Auth And Public Access

Mode	Environment / route behavior
REST API enablement	API_ENABLE=1; API_PORT normally matches the REST bind port unless a deployment deliberately separates the values.
Bearer API key	API_KEY; clients send Authorization: Bearer $ROUTER_API_KEY for protected router routes.
Trial routes	X402_ROUTER_NODE_TRIAL_ENABLE, trial max requests, trial window, and trial session IDs.
x402 routes	X402_ROUTER_NODE_ENABLE, network, pay-to address, and route prices.
A2A	Agent discovery and agent protocol routes where enabled.
MCP streamable HTTP	ROUTER_MCP, bind host/port, and session IDs.
MCP SSE legacy transport	ROUTER_MCP_SSE, bind host/port, and session IDs.

x402 Settings

X402_ROUTER_NODE_ENABLE=0
X402_ROUTER_NODE_NETWORK=base-sepolia
X402_ROUTER_NODE_PAY_TO=
X402_ROUTER_NODE_PRICE_DEFAULT=0.001
X402_ROUTER_NODE_PRICE_COMPLETIONS=0.001

X402_ROUTER_NODE_TRIAL_ENABLE=0
X402_ROUTER_NODE_TRIAL_MAX_REQUESTS=1
X402_ROUTER_NODE_TRIAL_WINDOW_SECONDS=900

Enable payment-gated routes only after the public pay-to address, network, prices, and refund/support policy are confirmed.

Off-Chain Storage And Privacy

v2/v3 flows can store large or private payloads off-chain and submit URN references into the task lifecycle.

OFFCHAIN_S3_REGION=us-east-1
OFFCHAIN_S3_ACCESS_KEY=
OFFCHAIN_S3_SECRET_KEY=
OFFCHAIN_S3_ENDPOINT_URL=https://s3.us-east-1.amazonaws.com
OFFCHAIN_S3_BUCKET_NAME=

ENCRYPTION_SEED=
ENCRYPTION_ALLOWLIST_USE_CONTRACT=1
ENCRYPTION_ALLOWED_LIST=
LOG_PAYLOAD_ENC_KEY=0

URN format:

urn:blob:{version}:s3:akamai:{bucket}:{file_name}
urn:blob:v3:s3:akamai:{backend_index}:{bucket}:{file_name}

Health Routes

After the router is running, use the configured REST host:

curl -s http://127.0.0.1:5010/api/v1/ping
curl -s http://127.0.0.1:5010/api/v1/about
curl -s http://127.0.0.1:5010/api/v1/info -H "Authorization: Bearer $ROUTER_API_KEY"
curl -s http://127.0.0.1:5010/api/v1/status -H "Authorization: Bearer $ROUTER_API_KEY"
curl -s http://127.0.0.1:5010/api/v1/miners -H "Authorization: Bearer $ROUTER_API_KEY"

Route	Purpose
/api/v1/ping	Liveness check; normally open.
/api/v1/about	Router metadata; normally open.
/api/v1/info	Router/network information; bearer key required.
/api/v1/status	Runtime status; bearer key required.
/api/v1/miners	Miner/node visibility; bearer key required.

Reverse Proxy Checklist

Item	Check
TLS	Public REST and MCP routes terminate TLS at the edge.
REST upstream	Proxy to ROUTER_REST_BIND_IP:ROUTER_REST_BIND_PORT.
WebSocket upstream	Preserve WebSocket upgrade headers for miner-facing traffic.
Timeouts	Long-running inference may need higher read/proxy timeouts than normal web APIs.
Body size	Off-chain flows reduce body pressure, but direct requests still need sane limits.
Logs	Preserve request ID, route, status, duration, and upstream error information.

Smoke Test Shape

Use environment-specific smoke tests before calling a router production-ready:

1. Ping/about/info/status.
2. Completion with an active session.
3. Delegate v3 with replicas=1, 3, and 5 if pools exist.
4. Validate v3 with expected pass/fail cases.
5. Factcheck route if enabled.
6. MCP and A2A discovery if enabled.
7. Trial/x402 challenge and paid request if enabled.
8. Off-chain/private request if enabled.

Deployment Record

Keep one deployment record per public router environment:

Field	Public value to record
Hostnames and ports	REST, WebSocket, MCP, and reverse-proxy URLs.
Route families	Completion, delegate, validate, factcheck, trial, x402, A2A, MCP, privacy, and off-chain routes that are enabled.
Session IDs	Completion, delegate, validate, factcheck, and model-specific session pools.
Auth requirements	Bearer/API key, trial quota, x402 payment, and MCP/A2A policy per route family.
Storage policy	Provider, retention, deletion, encryption, and URN format for off-chain payloads.
Transport policy	MCP streamable HTTP, legacy SSE, or both.