Skip to content

Go to the docs contents

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.

View as Markdown

NATS JetStream message queues kept on disk: work passes from one service to another on a conveyor belt

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:

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:

VariableWhat it holds
NATS_URLThe 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:

PlanQueuesSpace in total
Free2256 MiB
Pro42 GiB
Enterprise810 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.

Your agent’s MCP tools

Your agent handles it with the deploy_app and get_environment tools.

Give your AI the message, and it takes care of the rest

Give this to your AI

Read while.sh/agents and help me get started with while.

Copy the message

In 3 minutes, with no sign-up, the tool has its own address. To keep it, create your account.

For a company project, write to the while team: hello@while.sh