---
title: "NATS JetStream message queues: the while.sh docs"
url: https://while.sh/en/docs/building-blocks/message-queues/
updated: 2026-11-21
---

# Message queues (NATS)

A message queue between your services and your jobs: the site drops the work in, the worker picks it up when it can. Any NATS client works.

> You, to your AI: Add a job queue between the site and the worker.

## What your agent writes

Your agent writes it in while.yaml, at the root of your app:

```yaml titre="while.yaml"
apiVersion: while/v1
project: my-app
services:
  - name: web
    port: 3000
queues:
  - name: jobs
```

## What your app receives

Your app receives these environment variables at every deployment:

| Variable | What it holds |
|---|---|
| `NATS_URL` | The NATS server address. |

## When to use it

Use it to hand work from one service to another, or to a scheduled job: the site drops a job and answers right away, the worker handles it afterwards. A message waits in the queue until it is read, even if the worker restarts.

A queue is shared by the services and jobs of one environment: production has its own, and so does each preview. Two projects never share a queue.

## How it works

Each queue in while.yaml is a NATS JetStream stream, kept on disk in three copies. Each service and each job receives the server address in `NATS_URL`, and its credentials in the file `/run/secrets/NATS_CREDS`. Any NATS client connects with both, for example in Node.js:

```js
import { readFileSync } from 'node:fs';
import { connect, credsAuthenticator } from 'nats';

const nc = await connect({
  servers: process.env.NATS_URL,
  authenticator: credsAuthenticator(readFileSync('/run/secrets/NATS_CREDS')),
});
```

A queue's subjects are under its name. By default, the queue `jobs` keeps the subjects `jobs.>`: `jobs.new` or `jobs.urgent.42`, but not `jobs` alone. Publish under a sub-subject, or add `jobs` to `subjects`.

Your app publishes, reads, creates its consumers and empties a queue. It neither creates nor removes one: its queues are those of while.yaml. Removing a queue from while.yaml erases its messages; destroying an environment erases those of all its queues.

Your agent follows each queue with `get_environment { view: "queues" }`: its messages, its size, its consumers and the lag of the slowest.

Depending on the plan:

| Plan | Queues | Space in total |
|---|---|---|
| Free | 2 | 256 MiB |
| Pro | 4 | 2 GiB |
| Enterprise | 8 | 10 GiB |

The space in total is the sum of the `max_bytes` of an environment's queues. A deployment that exceeds the plan's number of queues or its space is refused, and the refusal names the plan and its limit. A message is 1 MiB at most.

## Sizes, versions and settings

- `retention`: `work` by default, each message is read once, then removed; with `limits`, messages stay until `max_age` or `max_bytes`, and can be read again.

- `max_age`: how long a message is kept at most, `7d` by default (`30m`, `24h`…).

- `max_bytes`: how much space the queue takes at most, `128Mi` by default. With this default, as many queues as the plan allows always fit.

- `subjects`: eight subjects at most, all under the queue's name.

- On a `work` queue, two consumers cannot read the same subject: give each its own (`filter_subject`).

- Every key, with its bounds: [the while.yaml reference](/en/docs/reference/while-yaml/#message-queues).

## Your agent's MCP tools

Your agent handles it with the `deploy_app` and `get_environment` tools.
