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.
Updated November 21, 2026.
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:
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:
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:workby default, each message is read once, then removed; withlimits, messages stay untilmax_ageormax_bytes, and can be read again. -
max_age: how long a message is kept at most,7dby default (30m,24h…). -
max_bytes: how much space the queue takes at most,128Miby 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
workqueue, two consumers cannot read the same subject: give each its own (filter_subject). -
Every key, with its bounds: the while.yaml reference.
Your agent’s MCP tools
Your agent handles it with the deploy_app and get_environment tools.