Messaging with NATS

Cosmonic Desktop can give your workloads NATS messaging: core pub/sub, request/reply, JetStream, and key-value, backed by a nats-server you run. The messaging starter templates from the Builder and cosmonic new (core subscriber, request/reply, JetStream consumer and worker, KV store and watcher, and fan-out) all expect a cluster to be connected first. This guide connects one.

Like every other capability, messaging is deny-by-default: a workload reaches NATS only through a cluster the host opens for it, and the connection details (servers, credentials, TLS) stay with the host, never in the workload's manifest.

Connect a cluster

1. Open Settings → Built-in plugins. NATS is the first card.
2. Select Add cluster.
3. Fill in the connection:
   • Name: leave it blank for the Default cluster, which serves any workload that doesn't ask for a specific one; or give it a name (for example orders) for a workload that needs its own server.
   • Server URL: the address of your nats-server, for example tls://nats.corp:4222.
   • Authentication (optional): choose a token, username and password, NKey seed, or JWT. Each reads from a secret reference, so credentials never land in nats.yaml or this UI. A credentials file or TLS material are given as file paths instead.
4. Save, then restart the host to apply. A saved cluster shows a Restart to apply badge until you do; use Restart host on the card.
5. Select Test on the saved cluster to confirm the host can reach it.

One cluster is enough for most projects. Add a named cluster only when a workload needs a different server or its own credentials.

note

The Default cluster's servers can also come from the host environment. When COSMONIC_NATS_URL is set (by a service file, CI, or your shell), the Default cluster dials that address until the variable is unset.

Use it from a workload

A workload asks for messaging by declaring the wasmcloud:nats interface. It uses the Default cluster automatically, or picks a named one with (implements <name>) in its manifest. Because the connection belongs to the host, a manifest that tries to set servers, credentials, or TLS itself is refused when you apply it. That is what keeps a sandboxed workload from reaching a broker you didn't wire up.

The messaging starter templates already declare the interface, so scaffolding one and running it against a connected cluster works with no manifest edits.

Where it's stored

Clusters live in nats.yaml in the host's state directory (cosmonicd paths prints the location), which the host reads once at start. That is why a change needs a restart to take effect.

Takeaway

Connect a cluster in Settings → Built-in plugins → NATS once and restart the host. Any workload that declares wasmcloud:nats can then message through it, with credentials kept as references and off the workload.