> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracenyx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Priority System

> How Nyx orders and resolves policies — the four priority bands and first-match evaluation.

Every Nyx policy carries a numeric **priority**. When more than one policy could apply to a connection, priority decides which is evaluated first — and within a single policy, rules are checked top-down. This page explains both, and what happens when nothing matches.

## The four priority bands

Priorities run from 0 to 99,999, divided into four bands by convention. Each band is the home for a different kind of policy:

| Band                | Priority range | Typical owner            | Purpose                                                                                 |
| ------------------- | -------------- | ------------------------ | --------------------------------------------------------------------------------------- |
| `platform-override` | 0–99           | Platform / security team | Non-negotiable rules that take precedence over everything else.                         |
| `namespace`         | 100–9,999      | Namespace owners         | Policies scoped to a single namespace's traffic.                                        |
| `platform-baseline` | 10,000–19,999  | Platform team            | Cluster-wide defaults and baselines, including the policies generated by `defaultMode`. |
| `workload`          | 20,000–99,999  | Application teams        | Fine-grained, workload-specific policies.                                               |

Lower numbers are evaluated first, so the bands form a precedence order from top to bottom: a `platform-override` rule wins over anything below it, and a `namespace` policy is evaluated before a `workload` policy.

<Note>
  A policy's priority is a single integer in the 0–99,999 range, and the admission webhook enforces these band boundaries — so precedence stays predictable as more teams add policies. The default priority is `100`, in the namespace band.
</Note>

## How evaluation works

Nyx resolves a connection in two nested passes:

1. **Across policies — by priority.** Every policy that could match the connection is ordered by priority, lowest number first.
2. **Within a policy — top-down.** Inside each policy, rules are checked in the order they're written. The first rule that matches decides the verdict, and evaluation stops there.

The first match across that ordered sequence wins. Nothing after it is consulted.

```mermaid theme={null}
flowchart TD
    A[Incoming connection] --> B[Evaluate policies in priority order<br/>lowest number first]
    B --> C[Within each policy, check rules top-down]
    C --> D{First matching rule?}
    D -->|Match found| E[Apply its verdict — allow or deny]
    D -->|No match in any policy| F[Fall back to cluster defaultMode]
```

Because the first match wins, rule order inside a policy matters: put specific allow rules above broad deny rules, or the broad deny will match first and the specific allow will never be reached.

## When nothing matches

If no rule in any policy matches a connection, Nyx applies the cluster's `defaultMode`, set in [`NyxClusterConfig`](/reference/nyxclusterconfig). That backstop — `allow`, `deny-cross-namespace`, or `deny` — is why a freshly installed cluster with no policies still has well-defined behaviour.

## A worked example

Suppose two policies could apply to a pod's outbound connection to the public internet:

* A `workload` policy at priority `25000` that allows egress to `0.0.0.0/0`.
* A `platform-override` policy at priority `50` that denies egress to the public internet.

Because `50` is lower than `25000`, the override is evaluated first. Its deny rule matches, the connection is blocked, and the workload's allow rule is never reached. This is how a platform team enforces guardrails that application teams can't override — by placing them in the `platform-override` band.