# kumo.nats.connect
{{since('2026.03.04-bb93ecb1')}}

```lua
kumo.nats.connect(CONFIG)
```

Connects to a NATS JetStream instance and constructs a client object.

`CONFIG` contains at least one address to connect to and the name. Supports
password and token authentication. The following Parameters are available:

  * `servers` - list of addresses
  * `auth` - an optional lua table containing either both `username` and
    `password`, or a `token`.  Each of `username`, `password` and `token` are
    [keysource](../keysource.md) objects that allow loading the credential from
    a supported credential store.
  * `name` - Sets the name for the client.
  * `no_echo` - disables delivering messages that were published from the same connection
  * `max_reconnects` - Specifies the number of consecutive reconnect attempts
    the client will make before giving up. This is useful for preventing zombie
    services from endlessly reaching the servers, but it can also be a footgun
    and surprise for users who do not expect that the client can give up
    entirely. Pass 0 for no limit (default).
  * `connection_timeout` - Sets a timeout for the underlying TcpStream
    connection to avoid hangs and deadlocks. Default is set to 5 seconds
  * `tls_required` - Sets or disables TLS requirement. If TLS connection is
    impossible connection will return error
  * `tls_first` - Changes how tls connection is established. If set, client
    will try to establish tls before getting info from the server. That
    requires the server to enable `handshake_first` option in the config
  * `certificate` - Loads root certificates by providing the path to them
  * `client_cert` - Loads client certificate by providing the path to it
    (`client_key` must also be set)
  * `client_key` - Loads client key by providing the path to it (`client_cert`
    must also be set)
  * `ping_interval` - Sets how often Client sends PING message to the server
  * `sender_capacity` - By default, Client dispatches op’s to the Client onto
    the channel with capacity of 128. This option enables overriding it
  * `inbox_prefix` - Sets custom prefix instead of default `_INBOX`
  * `request_timeout` - Sets a timeout for requests. Default value is set to 10 seconds
  * `retry_on_initial_connect` - By default, connect will return an error if
    the connection to the server cannot be established. Setting
    `retry_on_initial_connect` makes the client establish the connection in the
    background
  * `ignore_discovered_servers` - By default, a server may advertise other
    servers in the cluster known to it. By setting this option, the client will
    ignore the advertised servers. This may be useful if the client may not be
    able to reach them
  * `retain_servers_order` - By default, client will pick random server to
    which it will try connect to. This option disables that feature, forcing it
    to always respect the order in which server addresses were passed

## Authentication with username and password

The `username` and `password` fields of the `auth` object are
[keysource](../keysource.md) objects.  The example below shows how to hard code
a credential, but we recommend taking advantage of the key source's ability to
load data from out side of the configuration to avoid checking credentials into
your configuration management system:

```lua
local nats = kumo.nats.connect {
  servers = { '127.0.0.1:4222' },
  -- optional arguments for authentication and connection behavior
  name = 'nats-client',
  auth = {
    username = { key_data = 'username' },
    password = { key_data = 'password' },
  },
}
```

## Authentication with token

The `token` field of the `auth` object is a [keysource](../keysource.md)
object.  The example below shows how to hard code a credential, but we
recommend taking advantage of the key source's ability to load data from out
side of the configuration to avoid checking credentials into your configuration
management system:

```lua
local nats = kumo.nats.connect {
  servers = { '127.0.0.1:4222', '127.0.0.1:4422' },
  -- optional arguments for authentication and connection behavior
  name = 'nats-client',
  auth = {
    token = { key_data = 'token' },
  },
}
```
