Workload · Running a NATS message bus

Run a NATS Server with JetStream on a Machine of Your Own

A NATS server is one small binary, nats-server, that routes messages between your services; switch on JetStream and it also keeps them on disk as streams, so a consumer that was offline can catch up later. Below: what to size, a locked-down install, the ports, three-node clustering and backups.

The short version
  1. Ports: 4222 clients, 6222 cluster routes, 8222 monitoring
  2. JetStream file storage defaults to 75% of the free disk under store_dir
  3. Three servers is the smallest cluster that keeps a RAFT majority
  4. Whole machine, unmetered port, root access, month to month

What NATS asks of the machine

Disk first, then memory, then CPU. Core NATS only forwards messages; JetStream writes every stream to store_dir, and the sizing guide names disk as the resource most likely to run out.

ResourceWhat spends itWhat the NATS docs advise
DiskFile-storage streamsPin max_file_store to what the volume really holds; left unset it takes 75% of the space available under store_dir
MemoryConnections, subscriptions, memory-storage streamsMemory storage defaults to 75% of RAM; a few hundred connections fit in a few hundred megabytes
CPUTLS handshakes and JetStream replicationKeep 20 to 30% headroom above steady state
File descriptorsAbout two per stream, plus client and route socketsRaise the limit well past 1024; the upstream systemd unit sets LimitNOFILE=800000

The JetStream reference lists /tmp/nats/jetstream as the default store_dir. Set your own path before the first stream exists: changing it on a running JetStream server makes the config reload fail.

Why a whole server suits a message bus

With JetStream, the disk is what your streams actually consume, so you want it to be yours. On a dedicated server all the cores, memory and disks belong to you, with no other customer on the hardware, so nobody else's job is queuing on your drive.

A bus multiplies traffic: one message to fifty subscribers leaves the server fifty times, and replicas copy every write. The port is unmetered, so there is no allowance to run over.

If a firewall rule locks you out, rack servers, blades and the m510 and m710x cartridges still give you the console screen and power button, and any server can be reinstalled from the control panel with no ticket. The term is month to month, so a trial cluster ends when you cancel.

The server that fits your bus

  • One node for a single application or a development bus: the compact cartridge servers on the dedicated server list are meant for one job. If you will keep streams, pick one with an SSD or NVMe disk, and compare drives on the NVMe server page.
  • Three nodes for JetStream with replicas: three matching single-processor servers in one city, so routes between them stay short. The order page lists the cities each server runs in.
  • A busy shared bus with many accounts, TLS everywhere and large streams: a two-processor server leaves headroom for TLS, replication and more disks.
  • Already on Kubernetes? The NATS docs treat their Helm chart as the standard path there. Managed Kubernetes on bare metal runs the control plane for you in New York on servers that stay yours, or you can run Kubernetes yourself.
  • A test bus that sees a few messages a minute may not need a whole machine. A Cloud VPS is a virtual machine on a server shared with other customers, and is sold as exactly that.

Up and running: one node with JetStream

The Linux install from the project's getting-started guide: the server, the nats tool, a version check.

curl -sf https://binaries.nats.dev/nats-io/nats-server/v2@latest | sh
sudo mv nats-server /usr/local/bin/
curl -sf https://binaries.nats.dev/nats-io/natscli/nats@latest | sh
sudo mv nats /usr/local/bin/
nats-server --version
  1. Run the commands above. Go on only once nats-server --version prints a version.
  2. Create a system user called nats with no login shell, and a directory /var/lib/nats owned by it with mode 0700. JetStream writes under it.
  3. Make a password hash for each user with nats server passwd. Run without --pass, it asks for the password, so the plain text never lands in your shell history.
  4. Write /etc/nats-server.conf as below, owned by root with group nats and mode 0640. Paste the hashes where shown. Even a hash is a secret: keep the file out of git.
  5. Copy nats-server-hardened.service from the util folder of the nats-server repository to /etc/systemd/system/nats-server.service and change only ExecStart to /usr/local/bin/nats-server -c /etc/nats-server.conf. The unit runs as User=nats, raises LimitNOFILE and lets the server write only to /var/lib/nats.
  6. Run sudo systemctl daemon-reload and then sudo systemctl enable --now nats-server. Plain enable without --now would wait for the next boot.
  7. Check it from the server itself: curl -s http://127.0.0.1:8222/healthz should answer, and /jsz on the same port shows JetStream's own view.
server_name: n1
listen: 0.0.0.0:4222
http: "127.0.0.1:8222"

jetstream {
  store_dir: "/var/lib/nats/jetstream"
  max_memory_store: 256MB
  max_file_store: 10GB
}

accounts {
  APP: {
    jetstream: enabled
    users: [ { user: app, password: "PASTE_BCRYPT_HASH_HERE" } ]
  }
  SYS: {
    users: [ { user: sys-admin, password: "PASTE_BCRYPT_HASH_HERE" } ]
  }
}
system_account: SYS

Once an accounts block exists, JetStream is opt-in per account, and an account without jetstream: enabled gets an error on every JetStream call. A config whose only account is the system account still lets unauthenticated clients into the global account, so keep at least one tenant account like APP in place before 4222 is reachable.

Fence the ports before clients arrive

NATS listens on 4222 for clients, 6222 for cluster routes, 7222 for gateways between clusters and 8222 for the HTTP monitor. The monitor speaks plain HTTP, and its /varz output reveals the version, the client count and memory use, which is why the config binds it to localhost and the firewall denies it.

Allow SSH first. The 6222 lines stand for your other cluster nodes; skip them on a single node. If only your own servers connect, allow 4222 from their addresses alone, and add a tls {} block before clients connect across the internet.

sudo ufw allow OpenSSH
sudo ufw allow 4222/tcp
sudo ufw allow from 203.0.113.11 to any port 6222 proto tcp
sudo ufw allow from 203.0.113.12 to any port 6222 proto tcp
sudo ufw deny 8222/tcp
sudo ufw enable

ufw writes IPv6 rules only when IPv6 is enabled in /etc/default/ufw. Check that it reads IPV6=yes before ufw enable, and add the same 6222 rule for each peer's IPv6 address if the nodes talk over IPv6.

Growing to a three-node cluster

Three servers is where replication starts: RAFT needs a majority, so a stream with three replicas (R3) keeps accepting writes with one node down, and a two-node cluster cannot do that.

  • Give every server its own server_name and the identical cluster name. A server with a different name is rejected and forms a cluster of its own.
  • Add a cluster {} block listening on 6222, with routes listing two or three other servers' route ports, never 4222, which speaks the client protocol.
  • If the nodes reach each other over public addresses, put a tls {} block inside cluster {} as well. Client TLS does not cover routes, and routes carry your replicated data.
  • Budget disk for replicas: on accounts without tiered limits an R3 stream counts replicas times bytes, so a 10 GiB stream uses 30 GiB of the account's storage limit.
  • Apply config changes with systemctl reload nats-server, which sends SIGHUP. The upstream unit stops the server with SIGUSR2, which puts it into lame-duck mode, a graceful shutdown.

Keeping it healthy: backups, upgrades, monitoring

  • Back up a stream with nats backup stream ORDERS ./backups/orders/2026-11-20. Consumer state is included by default; --no-consumers keeps the messages and drops it.
  • Copy snapshots off the server. Restore with nats backup restore stream ./backups/orders/2026-11-20; the stream must not exist yet, since restore recreates it rather than merging. Before you remove a broken stream to make room, back it up to a new folder and confirm that folder exists and is not empty.
  • After a restore, compare message counts with nats stream info ORDERS. A zero exit code from the backup does not prove the snapshot is usable.
  • Memory streams cannot be snapshotted before release 2.15, so keep anything you need to back up on file storage.
  • Watch /healthz and /jsz from an agent on the host, and the real disk with df -h.
  • Upgrade one node at a time, so a three-node cluster always keeps its majority.

When this is the wrong place for it

You run NATS, not us: we keep the hardware and network running, and the config, upgrades and backups are yours. If you want a bus somebody else operates, a rented server is the wrong purchase.

One node is one point of failure: without replicas, a dead disk loses whatever was not backed up. Basic support comes with every server; faster hardware replacement is a monthly line on most servers.

Questions people ask

Do I need JetStream, or is plain NATS enough?
Plain NATS hands a message to whoever is subscribed at that moment and keeps nothing. Switch on JetStream when consumers must catch up after being offline, or for key-value buckets and the object store, which are built on it. It is enabled with -js on the command line or a jetstream {} block in the config file.
How many machines does a NATS cluster with persistence need?
Three. JetStream replicates with RAFT, which needs a majority, so three nodes let an R3 stream carry on with one node down.
How much disk should a JetStream node have?
Enough for everything your streams retain, plus room to grow: each node holding a replica keeps one full copy, so with three nodes and R3 streams every node needs room for all of it. Left unset, JetStream claims 75% of the space available under store_dir. Set max_file_store to what the disk really holds and watch usage with df -h.
Which ports does nats-server open?
4222 for clients. The others come with what you configure: 6222 for cluster routes, 7222 for gateways and 8222 for the HTTP monitor. Keep 8222 on localhost because it is plain HTTP, and allow 6222 only from your other nodes.
Does NATS cost anything to run?
The server is open source under the Apache 2.0 licence, so there is nothing to license. You install and run it yourself; the rental covers the hardware and network, not your software.
Can I run NATS on Kubernetes on your servers?
Yes. The NATS docs point to their Helm chart for Kubernetes. Managed Kubernetes in New York runs the control plane for you on nodes that are your own dedicated servers, or you can install Kubernetes yourself.

Get a server for your NATS bus

Choose a whole machine with the disk your streams need, root access and an unmetered port; a ready server is handed over within 30 minutes of approval.

Choose your server

Read next