Routing

Routing Rules

Route requests to specific agents based on path, headers, cookies, client IP, or HTTP method. Rules are evaluated in priority order (lowest number first). If a matching rule's target agent is offline, the request returns a 502 Bad Gateway unless the rule's Fall back to round-robin option is enabled — in which case it routes to any healthy agent instead.

Configure in the dashboard under Endpoint Settings → Routing Rules.

How Routing Works

Without routing rules, all traffic is distributed via weighted round-robin across connected agents. When you add rules, the system evaluates them in priority order:

1. Rules are sorted by priority (lower number = evaluated first)
2. Rules with the same priority are evaluated in creation order
3. For each rule, all conditions must match for the rule to apply
4. The request is routed to the matching rule's target agent
5. If the matched agent is offline: return 502, or — when the rule has Fall back to round-robin enabled — route to any healthy agent
6. If no rules match, traffic falls through to default round-robin

Visual Editor

The dashboard provides a visual rule builder. Create routing rules with the following fields:

Routing Conditions

Each condition specifies what part of the request to check. All conditions in a rule must match for the rule to apply.

Exclude Modifier

Each condition has an Exclude checkbox that inverts the match. When enabled, the rule routes to the target agent for everything except the specified pattern.

YAML Editor

For advanced use cases, switch to the YAML editor to define routing rules in code. Click Apply to save all changes (this replaces all existing rules).

rules:
  - name: API Backend
    priority: 1
    target_agent_id: api-handler
    enabled: true
    conditions:
      - match: path
        pattern: "/api/*"

  - name: Admin Panel
    priority: 2
    target_agent_id: admin-backend
    enabled: true
    conditions:
      - match: path
        pattern: "/admin/*"

  - name: EU Users
    priority: 3
    target_agent_tags: "eu,production"
    enabled: true
    conditions:
      - match: header
        name: "X-Region"
        pattern: "EU"

  - name: Exclude Health Checks
    priority: 4
    target_agent_id: monitoring-agent
    enabled: true
    conditions:
      - match: path
        pattern: "/health"
        exclude: true

Connected Agents

The Routing Rules page shows a Connected Agents section listing all agents currently registered with the endpoint. Agents register using the --id, --name, and --tags flags.

Registering Agents

When starting an agent, use flags to identify it for routing:

# Register with a specific agent ID
ngris http 3000 --url myapp --id api-handler

# Register with tags for tag-based routing
ngris http 3000 --url myapp --tags api,production

# Combine ID and name for display
ngris http 3000 --url myapp --id api-handler --name "API Server"