What are NATS Leaf Nodes?

In the NATS ecosystem, Leaf Nodes are lightweight NATS server instances that extend the connectivity and reach of a NATS cluster. They allow remote or geographically distributed nodes to connect seamlessly to a central NATS cluster or supercluster, enabling efficient communication across locations, networks, or infrastructure boundaries.

Key Characteristics of Leaf Nodes

Remote Connectivity

Leaf Nodes connect remote systems to a central NATS cluster, bridging isolated environments with the main messaging infrastructure.

Lightweight

Designed to have minimal resource requirements compared to full cluster nodes, making them suitable for edge computing or resource-constrained environments.

Transparent Message Routing

Messages published to or subscribed from a Leaf Node are automatically routed through its parent cluster, allowing seamless integration without client-side changes.

Bidirectional Communication

Leaf Nodes can both send messages to and receive messages from the parent cluster.

Independent Operation

In case of a temporary loss of connection to the central cluster, Leaf Nodes can operate independently for local messaging, buffering messages for later delivery when the connection is restored.

Use of Credentials

Leaf Nodes require authentication to connect to the parent cluster, ensuring secure communication.

Support for Isolation and Multi-Tenancy

Leaf Nodes can be configured to isolate traffic or support multi-tenancy by connecting specific applications, users, or systems to designated parts of the NATS cluster.

Advantages of Leaf Nodes

Geographic Reach

Extend NATS functionality to remote or distributed environments, such as branch offices, edge devices, or hybrid clouds.

Reduced Latency

By deploying Leaf Nodes closer to users or devices, latency is reduced as local messages are handled without requiring a round trip to the central cluster.

Fault Tolerance

Ensure local operations during network outages with automatic reconnection and message buffering.

Simplified Network Setup

Avoid complex VPNs or direct connections by using Leaf Nodes to bridge networks securely.

Resource Efficiency

Lightweight design makes them ideal for constrained environments, such as IoT devices or edge nodes.

Example Use Cases

Edge Computing

Deploy Leaf Nodes on IoT gateways or remote sensors to connect edge devices with central systems.

Hybrid Cloud Integration

Use Leaf Nodes to bridge private data centers with public cloud environments.

Multi-Region Applications

Reduce inter-region latency by deploying Leaf Nodes in each region to interact with a global NATS supercluster.

Air-Gapped or Intermittent Networks

Enable messaging in isolated or intermittent connectivity environments, buffering messages locally until reconnection.

How Leaf Nodes Work

Configuration

A Leaf Node is configured to connect to a parent cluster via its server configuration file.
leafnodes {

1
`remotes = [`
2
    `{`
3
        `url: "nats://cluster.example.com:7422"`
4
        `credentials: "/path/to/credentials"`
5
    `}`
6
`]`

}

Connection

The Leaf Node establishes a secure connection with the parent cluster using the provided URL and credentials.

Message Flow

Messages published to the Leaf Node are routed to the parent cluster and distributed to subscribers. Similarly, subscribers on the Leaf Node receive messages routed from the parent cluster.

Comparison: Leaf Nodes vs. Cluster Nodes

Frequently Asked Questions

How do I connect edge devices behind firewalls to the cloud without opening inbound ports?

NATS leaf nodes initiate outbound-only connections to the hub cluster on port 7422. No inbound firewall rules, VPN tunnels, or port forwarding are required. This works behind NAT, corporate firewalls, and cellular networks because the edge device always dials out. Learn more about leaf node configuration

How do I connect edge locations to a central cloud without opening inbound firewall ports?

NATS leaf nodes at each remote site dial out to the central cluster on port 7422. No inbound firewall changes are required. This outbound-only model works behind NAT, corporate firewalls, and cellular networks. Each leaf node maintains its connection automatically with built-in reconnection logic. Learn more about leaf node configuration

How do I build a hub-and-spoke architecture for hundreds of remote edge locations?

NATS uses a central cluster as the hub with a leaf node deployed at each spoke location. Each leaf node operates independently during disconnection, handling local messaging without the hub. With configured stream mirrors or sources, JetStream replicates persisted data when the leaf node reconnects. Learn more about leaf node configuration

Will a NATS client connect to the server with the lowest round-trip time?

NATS clients randomly choose from provided server URLs by default — RTT is not considered (randomization can be disabled with the DontRandomize option). For latency-sensitive workloads, NATS provides several deployment options. Deploy individual clusters in regions where your clients are located, then connect them with gateway connections to form a super-cluster. Clients connect to any cluster and NATS routes messages across clusters transparently. For services using request-reply, deploy replicas in local regions — NATS tracks the interest graph across clusters and automatically routes requests to the shortest path. If a local service goes down, requests fall back to a remote region transparently. Leaf nodes provide the most granular option: single NATS servers deployed directly next to clients for hyper-local low-RTT messaging with a security boundary. Queue semantics are honored across leaf connections, serving local consumers first. Learn more about adaptive deployment

Is a NATS leaf node a single point of failure?

NATS allows you to deploy a local cluster at the edge where each node establishes its own leaf connection to the hub cluster. This means the leaf tier itself is redundant — if one local node goes down, the remaining nodes continue serving local clients and maintaining their leaf connections. This is especially useful when the application requires locally replicated streams via JetStream, since data is persisted across multiple nodes at the edge. Unlike cluster or gateway nodes, leaf nodes do not need to be reachable from the outside — they always initiate outbound connections. This flexibility lets you build any acyclic graph topology without exposing edge infrastructure. Learn more about leaf node configuration

Last updated: March 2026

Additional Resources

• Documentation: NATS Leaf Nodes
• NATS by Example: Simple Leaf Nodes
• Video: Extending your NATS cluster with Leaf Nodes

Leaf Nodes are a powerful feature of the NATS ecosystem, enabling secure, efficient, and flexible extensions of messaging infrastructure to edge and remote environments.