Quickstart guide

Get started with NATS Server in minutes - install, run, and send your first message

This quickstart guide will help you get NATS Server up and running and send your first message in just a few minutes.

Prerequisites

No special prerequisites are required. NATS Server is a single binary with no external dependencies.

Get started

1. Install NATS Server

   The fastest way to get started is using Docker:

   docker pull nats:latest
   

   Alternatively, download the binary for your platform from the GitHub releases page.

   For other installation methods, see the installation guide.

2. Start the server

   Start NATS Server with default settings:

   Docker

   docker run -p 4222:4222 -p 8222:8222 nats:latest
   

   You should see output indicating the server is running:

   [1] 2026/03/04 12:00:00.000000 [INF] Starting nats-server
   [1] 2026/03/04 12:00:00.000000 [INF]   Version:  2.x.x
   [1] 2026/03/04 12:00:00.000000 [INF]   Git:      [not set]
   [1] 2026/03/04 12:00:00.000000 [INF]   Listening for client connections on 0.0.0.0:4222
   [1] 2026/03/04 12:00:00.000000 [INF]   Server is ready
   

   The default client port is 4222. The monitoring port is 8222 when enabled with -m 8222.

3. Install the NATS CLI (optional)

   For testing, install the NATS CLI tool:

   # macOS
   brew install nats-io/nats-tools/nats
   
   # Linux/macOS (using curl)
   curl -sf https://binaries.nats.dev/nats-io/natscli/nats@latest | sh
   
   # Windows (using chocolatey)
   choco install nats
   

   The NATS CLI is also included in the Docker image at /bin/nats.

4. Subscribe to a subject

   Open a new terminal and subscribe to a test subject:

   NATS CLI

   nats sub test.subject
   

   You should see:

   12:00:00 Subscribing on test.subject
   

   Leave this terminal open to receive messages.

5. Publish a message

   In another terminal, publish a message:

   NATS CLI

   nats pub test.subject "Hello NATS!"
   

   In the subscriber terminal, you should see the message:

   12:00:05 [#1] Received on "test.subject"
   Hello NATS!
   

   Try publishing multiple messages and watch them appear in real-time in the subscriber terminal!

6. Verify server status

   Check the server monitoring endpoint:

   curl http://localhost:8222/varz
   

   This returns JSON with server statistics including connections, message counts, and memory usage.

   The monitoring endpoint must be enabled with -m 8222 when starting the server, or configured in the configuration file with monitor_port: 8222.

Common server options

Here are some commonly used command-line options:

# Bind to specific address and port
nats-server -a 127.0.0.1 -p 4222

# Enable monitoring
nats-server -m 8222

# Enable JetStream with storage directory
nats-server -js --store_dir /data/nats

# Use configuration file
nats-server -c /path/to/nats-server.conf

# Enable debug logging
nats-server -D

# Enable authentication
nats-server --user admin --pass secret

For a complete list of options, run nats-server --help or see the configuration reference.

Testing with client libraries

NATS has client libraries for over 40 programming languages. Here’s a quick example in a few popular languages:

Go

package main

import (
    "log"
    "github.com/nats-io/nats.go"
)

func main() {
    nc, err := nats.Connect(nats.DefaultURL)
    if err != nil {
        log.Fatal(err)
    }
    defer nc.Close()

    // Subscribe
    nc.Subscribe("test.subject", func(m *nats.Msg) {
        log.Printf("Received: %s", string(m.Data))
    })

    // Publish
    nc.Publish("test.subject", []byte("Hello NATS!"))
    nc.Flush()
}

Next steps

Now that you have NATS Server running, explore these topics:

Configuration

Learn how to configure NATS Server for production

JetStream

Enable persistence and streaming with JetStream

Clustering

Set up high availability with clustering

Security

Secure your NATS deployment

Troubleshooting

Connection refused errors

Ensure the server is running and listening on the correct port (default 4222). Check firewall settings if connecting from a different machine.

Server won't start

Check if another process is using port 4222. Use nats-server -p 4223 to use a different port. Enable debug logging with -D for more information.

Messages not being received

Verify the subscriber is connected before publishing. Check that subject names match exactly (they are case-sensitive).

Get help

If you need assistance:

• Join the NATS Community Slack
• Ask questions on Google Groups
• Check the FAQ